.tox/
__pycache__/
*.pyc
+docs/javadoc/
path = docs/submodules/integration/test
url = ../integration/test
branch = master
+[submodule "docs/submodules/aaa"]
+ path = docs/submodules/aaa
+ url = ../aaa
+ branch = master
+[submodule "docs/submodules/netconf"]
+ path = docs/submodules/netconf
+ url = ../netconf
+ branch = master
+[submodule "docs/submodules/odlparent"]
+ path = docs/submodules/odlparent
+ url = ../odlparent
+ branch = master
--- /dev/null
+-r requirements.txt
+https://github.com/zxiiro/javasphinx/raw/master/javasphinx-0.9.13-odl.tar.gz
mkdir -p $ROBOT_DIR $TMP_ROBOT_DIR
cd submodules/integration/test/csit/libraries
-for f in *.robot; do python -m robot.libdoc $f $TMP_ROBOT_DIR/$f.html; done
-for f in *.py; do python -m robot.libdoc $f $TMP_ROBOT_DIR/$f.html > /dev/null 2>&1; done
+for f in *.robot; do
+ python -m robot.libdoc $f $TMP_ROBOT_DIR/$f.html &
+done
+wait
+for f in *.py; do
+ python -m robot.libdoc $f $TMP_ROBOT_DIR/$f.html > /dev/null 2>&1 &
+done
+wait
+
cd $TMP_ROBOT_DIR/
-for f in *.html; do sed 's/black/orange/; s/white/black/; s/^<body>/<body><img src="..\/..\/odl.png">/' $f > $ROBOT_DIR/$f; done
+echo "<html><body><ul>" > $ROBOT_DIR/index.html
+for f in *.html; do
+ sed 's/black/orange/; s/white/black/; s/^<body>/<body><img src="..\/..\/odl.png">/' $f > $ROBOT_DIR/$f
+ echo "<li><a href=\"$f\">$f</a></li>" >> $ROBOT_DIR/index.html
+done
+echo "</ul></body></html>" >> $ROBOT_DIR/index.html
# ones.
extensions = []
+# Disable javasphinx generation until we have a solution to long build
+# times. readthedocs timesout after 902 seconds.
+# javasphinx_available = False
+# try:
+# import javasphinx
+# javasphinx_available = True
+# extensions.append('javasphinx')
+# except ImportError, e:
+# pass
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
import subprocess
subprocess.call(["./build-integration-robot-libdoc.sh"])
+
+# Disable javasphinx generation until we have a solution to long build
+# times. readthedocs timesout after 902 seconds.
+subprocess.call(["rm","-rf","javadoc"])
+# if javasphinx_available:
+# subprocess.call(["./generate-javaapidoc.sh"])
.. _documentation-guide:
+###################
Documentation Guide
-===================
+###################
This guide provides details on how to contribute to the OpenDaylight
documentation. OpenDaylight currently uses a mix of AsciiDoc_ and
people.
reStructuredText-based Documentation
-------------------------------------
+====================================
When using reStructuredText, we try to follow the python documentation
-style guide. See:
-
- https://docs.python.org/devguide/documenting.html
+style guide. See: https://docs.python.org/devguide/documenting.html
To build and review the reStructuredText documentation locally you must
have installed locally:
Which both should be available in most distribution's package managers.
-Then simply run tox and open the html produced via your favourite web
+Then simply run tox and open the html produced via your favorite web
browser as follows:
.. code-block:: bash
- tox -edocs
- firefox docs/_build/html/index.html
+ git clone https://git.opendaylight.org/gerrit/docs
+ cd docs
+ git submodule update --init
+ tox -edocs
+ firefox docs/_build/html/index.html
+
+.. note:: Make sure to run `tox -edocs` and not just `tox`. See `Make
+ sure you run tox -edocs`_
Directory Structure
-^^^^^^^^^^^^^^^^^^^
+-------------------
The directory structure for the reStructuredText documentation is
rooted in the ``docs`` directory inside the ``docs`` ``git``
.. note:: When including rst files using ``toctree`` omit the .rst at
the end of the file name.
+Documentation Layout and Style
+------------------------------
+
+As mentioned previously we try to follow the python documentation style guide
+which defines a few types of sections::
+
+ # with overline, for parts
+ * with overline, for chapters
+ =, for sections
+ -, for subsections
+ ^, for subsubsections
+ ", for paragraphs
+
+We try to follow the following structure based on that recommendation::
+
+ docs/index.rst -> entry point
+ docs/____-guide/index.rst -> part
+ docs/____-guide/<chapter>.rst -> chapter
+
+In the ____-guide/index.rst we use the # with overline at the very top
+of the file to determine that it is a part and then within each chapter
+file we start the document with a section using * with overline to
+denote that it's the chapter heading and then everything in the rest of
+the chapter should use::
+
+ =, for sections
+ -, for subsections
+ ^, for subsubsections
+ ", for paragraphs
+
+
Troubleshooting
-^^^^^^^^^^^^^^^
+---------------
+
+Make sure you've cloned submodules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you see an error like this::
It means that you haven't pulled down the git submodule for the integration/test project. The fastest way to do that is::
- git submodule init
- git submodule update
+ git submodule update --init
+
+In some cases, you might wind up with submodules which are somehow
+out-of-sync and in that case, the easiest way to fix it is delete the
+submodules directory and then re-clone the submodules::
+
+ rm -rf docs/submodules/
+ git submodule update --init
+
+.. warning:: This will delete any local changes or information you made
+ in the submodules. This should only be the case if you
+ manually edited files in that directory.
-Also, you may notice errors like these when building::
+Make sure you run tox -edocs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Importing test library '/Users/ckd/git-reps/docs/docs/submodules/integration/test/csit/libraries/AAAJsonUtils.py' failed: ImportError: No module named jsonpath
+If you see an error like::
- sed: 1: "SxpLib.robot.html": invalid command code S
+ ERROR: docs: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs/log/docs-1.log)', 1)
+ ERROR: docs-linkcheck: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs-linkcheck/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs-linkcheck/log/docs-linkcheck-1.log)', 1)
-They can be ignored. This is an artifact of our building documentation for the robot test framework customizations OpenDaylight has and is being tracked as `BUG-6159 <https://bugs.opendaylight.org/show_bug.cgi?id=6159>`_. More information can be found there.
+It usually means you ran `tox` and not `tox -edocs`, which will result
+in running jobs inside submodules which aren't supported by the
+environment defined by the `requirements.txt` file in the documentation
+tox setup. Just run tox -edocs and it should be fine.
+
+Clear your tox directory and try again
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes, tox will not detect when your ``requirements.txt`` file has
+changed and so will try to run things without the correct dependencies.
+This usually manifests as ``No module named X`` errors or
+an ``ExtensionError`` and can be fixed by deleting the ``.tox``
+directory and building again::
+
+ rm -rf .tox
+ tox -edocs
AsciiDoc-based Documentation
-----------------------------
+============================
Information on the AsciiDoc tools and build system can be found here:
-
- https://wiki.opendaylight.org/view/Documentation/Tools
+https://wiki.opendaylight.org/view/Documentation/Tools
Directory Structure
-^^^^^^^^^^^^^^^^^^^
+-------------------
The AsciiDoc documentation is all located in the ``manuals`` directory
of the ``docs`` ``git`` repository. An example of the directory
``src/main/resources`` directory containing images.
Migration from AsciiDoc to ReStructuredText
--------------------------------------------
+===========================================
Automatically
-^^^^^^^^^^^^^
+-------------
In theory, Pandoc_ can convert from DocBook to reStructuredText and we
produce DocBook as part of our build chain from AsciiDoctor. In
well.
By Hand
-^^^^^^^
+-------
Converting from AsciiDoc to reStructuredText is usually pretty
straightforward and involves looking up the basic syntax for what you
the HTML documentation rapid iteration is very easy.
Bold/Italics/Verbatim Formatting
-""""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is mostly minor syntax issues. In AsciiDoc you do inline
formatting something like this::
**bold** *italic* ``verbatim``
Images
-""""""
+^^^^^^
Image formats change from something like::
--- /dev/null
+#!/bin/bash
+
+projects="
+aaa
+netconf
+odlparent
+"
+
+for project in $projects
+do
+ javasphinx-apidoc --update --title "$project" -o javadoc/$project submodules/$project
+done
+***
API
-===
+***
We are in the process of creating automatically generated API documentation for
all of OpenDaylight. The following are links to the preliminary documentation
+****************************
Common OpenDaylight Features
-============================
+****************************
.. toctree::
:maxdepth: 1
+*******************************
OpenDaylight concepts and tools
-===============================
+*******************************
In this section we discuss some of the concepts and tools you encounter with
basic use of OpenDaylight. The guide walks you through the installation process
+**********************************
OpenDaylight Experimental Features
-==================================
+**********************************
.. contents::
:depth: 1
:local:
Messaging4Transport
--------------------
+===================
Adds AMQP bindings to the MD-SAL, which makes all MD-SAL APIs available via
that mechanism. AMQP bindings integration exposes the MD-SAL datatree, rpcs,
and notifications via AMQP, when installed.
Network Intent Composition (NIC)
---------------------------------
+================================
Offers an interface with an abstraction layer for you to communicate
“intentions,” i.e., what you expect from the network. The Intent model, which
is part of NIC's core architecture, describes your networking services
* Network MOdeling Renderer
UNI Manager Plug-in (Unimgr)
-----------------------------
+============================
Formed to initiate the development of data models and APIs that facilitate
OpenDaylight software applications’ and/or service orchestrators’ ability to
configure and provision connectivity services.
YANG-PUBSUB
------------
+===========
An experimental feature Plugin that allows subscriptions to be placed on
targeted subtrees of YANG datastores residing on remote devices. Changes in
YANG objects within the remote subtree can be pushed to OpenDaylight as
+#####################
Getting Started Guide
-=====================
+#####################
.. toctree::
:maxdepth: 1
project-specific-guides/index
common-features/index
security_considerations
-
.. _install_odl:
+***********************
Installing OpenDaylight
-=======================
+***********************
You complete the following steps to install your networking environment, with
specific instructions provided in the subsections below.
Install OpenDaylight
---------------------
+====================
Downloading and installing OpenDaylight
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------------
The default distribution can be found on the OpenDaylight software
download page: http://www.opendaylight.org/software/downloads
the `Install the Karaf features`_ section below.
Running the karaf distribution
-""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To run the Karaf distribution:
inflating: distribution-karaf-0.4.0-Beryllium/bin/stop.bat
$ cd distribution-karaf-0.4.0-Beryllium
$ ./bin/karaf
-
+
________ ________ .__ .__ .__ __
\_____ \ ______ ____ ____ \______ \ _____ ___.__.\| \| \|__\| ____ \| \|___/ \|_
/ \| \\____ \_/ __ \ / \ \| \| \\__ \< \| \|\| \| \| \|/ ___\\| \| \ __\
* Press ``ctrl-d`` or type ``system:shutdown`` or ``logout`` to shutdown OpenDaylight.
Install the Karaf features
---------------------------
+==========================
To install a feature, use the following command, where feature1 is the feature
name listed in the table below::
**self+all**. Not every combination has been tested.
Uninstalling features
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
To uninstall a feature, you must shut down OpenDaylight, delete the data
directory, and start OpenDaylight up again.
is not supported and can cause unexpected and undesirable behavior.
Listing available features
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
To find the complete list of Karaf features, run the following command::
feature:list
you can find in the :ref:`proj_rel_notes` section.
Karaf running on Windows 10
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
Windows 10 cannot be identify by Karaf (equinox).
Issue occurs during installation of karaf features e.g.::
Error executing command: Can't install feature odl-restconf/0.0.0:
Could not start bundle mvn:org.fusesource.leveldbjni/leveldbjni-all/1.8-odl in feature(s) odl-akka-leveldb-0.7: The bundle "org.fusesource.leveldbjni.leveldbjni-all_1.8.0 [300]" could not be resolved. Reason: No match found for native code: META-INF/native/windows32/leveldbjni.dll; processor=x86; osname=Win32, META-INF/native/windows64/leveldbjni.dll; processor=x86-64; osname=Win32, META-INF/native/osx/libleveldbjni.jnilib; processor=x86; osname=macosx, META-INF/native/osx/libleveldbjni.jnilib; processor=x86-64; osname=macosx, META-INF/native/linux32/libleveldbjni.so; processor=x86; osname=Linux, META-INF/native/linux64/libleveldbjni.so; processor=x86-64; osname=Linux, META-INF/native/sunos64/amd64/libleveldbjni.so; processor=x86-64; osname=SunOS, META-INF/native/sunos64/sparcv9/libleveldbjni.so; processor=sparcv9; osname=SunOS
-Workaround is to add
+Workaround is to add
org.osgi.framework.os.name = Win32
Beryllium features
-------------------
+==================
.. list-table:: Beryllium features
:widths: 10 25 10 5
Other Beryllium features
-------------------------
+========================
.. list-table:: Other Beryllium features
:widths: 10 25 10 5
Experimental Beryllium Features
--------------------------------
+===============================
The following functionality is labeled as experimental in OpenDaylight
Beryllium and should be used accordingly. In general, it is not supposed to be
used in production unless its limitations are well understood by those
- all
Install support for REST APIs
------------------------------
+=============================
Most components that offer REST APIs will automatically load the RESTCONF API
Support component, but if for whatever reason they seem to be missing, install
the “odl-restconf” feature to activate this support.
+************
Introduction
-============
+************
The OpenDaylight project is an open source platform for Software Defined
Networking (SDN) that uses open protocols to provide centralized, programmatic
through the installation process.
What’s different about OpenDaylight
------------------------------------
+===================================
Major distinctions of OpenDaylight’s SDN compared to traditional SDN options are
the following:
SDN programs.
What you’ll find in this guide
-------------------------------
+==============================
To set up your environment, you first install OpenDaylight followed by the
Apache Karaf features that offer the functionality you require. The OpenDaylight
+***************************
OpenDaylight Karaf Features
-===========================
+***************************
This section provides brief descriptions of the most commonly used Karaf
features developed by OpenDaylight project teams. They are presented in
:local:
AAA
----
+===
Standards-compliant Authentication, Authorization and Accounting Services.
RESTCONF is the most common consumer of AAA, which installs the AAA features
automatically. AAA provides:
The Beryllium release of AAA includes experimental support for having the database of users and credentials stored in the cluster-aware MD-SAL datastore.
ALTO
-----
+====
Implements the Application-Layer Traffic Optimization (ALTO) base IETF protocol
to provide network information to applications. It defines abstractions and
services to enable simplified network views and network services to guide
amongst endpoints.
Border Gateway Protocol (including Link-state Distribution (BGP)
-----------------------------------------------------------------
+================================================================
Is a southbound plugin that provides support for Border Gateway Protocol
(including Link-state Distribution) as a source of L3 topology information.
Border Gateway Monitoring Protocol (BMP)
-----------------------------------------
+========================================
Is a southbound plugin that provides support for BGP Monitoring Protocol as a
monitoring station.
Control and Provisioning of Wireless Access Points (CAPWAP)
------------------------------------------------------------
+===========================================================
Enables OpenDaylight to manage CAPWAP-compliant wireless termination point (WTP)
network devices. Intelligent applications, e.g., radio planning, can be
developed by tapping into the operational states made available via REST APIs of
WTP network devices.
Controller Shield
------------------
+=================
Creates a repository called the Unified-Security Plugin (USecPlugin) to provide
controller security information to northbound applications, such as the
following:
Information collected at the plugin may also be used to configure firewalls and create IP blacklists for the network.
Device Identification and Driver Management (DIDM)
---------------------------------------------------
+==================================================
Provides device-specific functionality, which means that code enabling a feature
understands the capability and limitations of the device it runs on. For
example, configuring VLANs and adjusting FlowMods are features, and there may be
functionality is implemented as Device Drivers.
DLUX
-----
+====
Web based OpenDaylight user interface that includes:
* An MD-SAL flow viewer
* A tool box and YANG model that execute queries and visualize the YANG tree
Fabric as a Service (FaaS)
---------------------------
+==========================
Creates a common abstraction layer on top of a physical network so northbound
APIs or services can be more easily mapped onto the physical network as a
concrete device configuration.
Group Based Policy (GBP)
-------------------------
+========================
Defines an application-centric policy model for OpenDaylight that separates
information about application connectivity requirements from information about
the underlying details of the network infrastructure. Provides support for:
* OFOverlay support for NAT, table offsets
Internet of Things Data Management (IoTDM)
-------------------------------------------
+==========================================
Developing a data-centric middleware to act as a oneM2M_-compliant IoT Data
Broker (IoTDB) and enable authorized applications to retrieve IoT data uploaded
by any device.
Link Aggregation Control Protocol (LACP)
-----------------------------------------
+========================================
LACP can auto-discover and aggregate multiple links between an
OpenDaylight-controlled network and LACP-enabled endpoints or switches.
Location Identifier Separation Protocol (LISP) Flow Mapping Service (LISP)
---------------------------------------------------------------------------
+==========================================================================
LISP (RFC6830) enables separation of Endpoint Identity (EID) from Routing
Location (RLOC) by defining an overlay in the EID space, which is mapped to the
underlying network in the RLOC space.
OpenDaylight via the LISP protocol.
NEMO
-----
+====
Is a Domain Specific Language (DSL) for the abstraction of network models and
identification of operation patterns. NEMO enables network users/applications to
describe their demands for network resources, services, and logical operations
in an intuitive way that can be explained and executed by a language engine.
NETCONF
--------
+=======
Offers four features:
* odl-netconf-mdsal: NETCONF Northbound for MD-SAL and applications
* odl-restconf: RESTCONF Northbound for MD-SAL and applications
NetIDE
-------
+======
Enables portability and cooperation inside a single network by using a
client/server multi-controller architecture. It provides an interoperability
layer allowing SDN Applications written for other SDN Controllers to run on
engine.
OVSDB-based Network Virtualization Services
--------------------------------------------
+===========================================
Several services and plugins in OpenDaylight work together to provide simplified
integration with the OpenStack Neutron framework. These services enable
OpenStack to offload network processing to OpenDaylight while enabling
* Network Virtualization User interface for DLUX
OpenFlow Configuration Protocol (OF-CONFIG)
--------------------------------------------
+===========================================
Provides a process for an Operation Context containing an OpenFlow Switch that uses OF-CONFIG to communicate with an OpenFlow Configuration Point, enabling remote configuration of OpenFlow datapaths.
OpenFlow plugin
----------------
+===============
Supports connecting to OpenFlow-enabled network devices via the OpenFlow
specification. It currently supports OpenFlow versions 1.0 and 1.3.2.
OF-CONFIG specifications.
Path Computation Element Protocol (PCEP)
-----------------------------------------
+========================================
Is a southbound plugin that provides support for performing Create, Read,
Update, and Delete (CRUD) operations on Multiprotocol Label Switching (MPLS)
tunnels in the underlying network.
Secure Network Bootstrapping Interface (SNBi)
----------------------------------------------
+=============================================
Leverages manufacturer-installed IEEE 802.1AR certificates to secure initial
communications for a zero-touch approach to bootstrapping using Docker. SNBi
devices and controllers automatically do the following:
federation processes.
Service Function Chaining (SFC)
--------------------------------
+===============================
Provides the ability to define an ordered list of network services (e.g.
firewalls, load balancers) that are then "stitched" together in the network to
create a service chain. SFC provides the chaining logic and APIs necessary for
* Integration with OpenDaylight OVSDB NetVirt project
SNMP Plugin
------------
+===========
The SNMP southbound plugin allows applications acting as an SNMP Manager to
interact with devices that support an SNMP agent. The SNMP plugin implements a
general SNMP implementation, which differs from the SNMP4SDN as that project
device.
SNMP4SDN
---------
+========
Provides a southbound SNMP plugin to optimize delivery of SDN controller
benefits to traditional/legacy ethernet switches through the SNMP interface. It
offers support for flow configuration on ACLs and enables flow configuration
via REST API and multi-vendor support.
Source-Group Tag Exchange Protocol (SXP)
-----------------------------------------
+========================================
Enables creation of a tag that allows you to filter traffic instead of using
protocol-specific information like addresses and ports. Via SXP an external
entity creates the tags, assigns them to traffic appropriately, and publishes
services and networking devices.
Topology Processing Framework
------------------------------
+=============================
Provides a framework for simplified aggregation and topology data query to
enable a unified topology view, including multi-protocol, Underlay, and
Overlay resources.
Time Series Data Repository (TSDR)
-----------------------------------
+==================================
Creates a framework for collecting, storing, querying, and maintaining time
series data in OpenDaylight. You can leverage various data-driven applications
built on top of TSDR when you install a datastore and at least one collector.
See these TSDR_Directions_ for more information.
Unified Secure Channel (USC)
-----------------------------
+============================
Provides a central server to coordinate encrypted communications between
endpoints. Its client-side agent informs the controller about its encryption
capabilities and can be instructed to encrypt select flows based on business
device types.
VPN Service
------------
+===========
Implements the infrastructure services required to support L3 VPN service. It
initially leverages open source routing applications as pluggable components.
L3 services include:
* Network Overlay solution necessary for a Datacenter/Cloud environment
Virtual Tenant Network (VTN)
-----------------------------
+============================
Provides multi-tenant virtual network on an SDN controller, allowing you to
define the network with a look and feel of a conventional L2/L3 network. Once
the network is designed on VTN, it automatically maps into the underlying
+**************
Other features
-==============
+**************
OpFlex
-------
+======
Provides the OpenDaylight OpFlex Agent , which is a policy agent that works
with Open vSwitch (OVS), to enforce network policy, e.g., from Group-Based
Policy, for locally-attached virtual machines or containers.
Network embedded Experience (NeXt)
-----------------------------------
+==================================
Provides a network-centric topology UI that offers visualizations of the
following:
+********
Overview
-========
+********
OpenDaylight performs the following functions:
+************************************
Project-Specific Installation Guides
-====================================
+************************************
.. toctree::
:maxdepth: 1
tsdr
vtn
yangide
-
-YangIDE Installation Guide
+YANG IDE Installation Guide
==========================
Overview
--------
-The YangIDE project provides an Eclipse plugin for viewing and editing
+The YANG IDE project provides an Eclipse plugin for viewing and editing
Yang model files. When you create a "Yang Project" using the plugin,
it creates a small Maven project with a POM file (pom.xml) that
references the appropriate OpenDaylight dependencies, along with a
sample Yang model file (acme-system.yang).
-Pre Requisites for Installing YangIDE
+Pre Requisites for Installing YANG IDE
-------------------------------------
-* YangIDE has the same hardware requirements as the Eclipse IDE, which
+* YANG IDE has the same hardware requirements as the Eclipse IDE, which
is about the same as the hardware requirements for Java 7.
* At least Java 7 is required to run Eclipse (also an obvious
- requirement), but Java 8 will be required if you're building an
+ requirement), but Java 8 will be required if you are building an
application using OpenDaylight, and Java 8 is recommended anyway.
Preparing for Installation
--------------------------
As soon as at least Java 7 (Java 8 preferred) and Eclipse are
-installed, and Eclipse is running, you can install YangIDE.
+installed, and Eclipse is running, you can install YANG IDE.
You can find the Oracle Java installer at
http://www.oracle.com/technetwork/java/javase/downloads/index.html .
the correct platform (for instance, 32-bit or 64-bit).
-Installing YangIDE
+Installing YANG IDE
------------------
-The YangIDE plugin can be installed by using the public update site URL
+The YANG IDE plugin can be installed by using the public update site URL
provided, which is http://abc.def .
While in Eclipse, select "Help" from the menu bar and select "Install
New Software ...". On the resulting "Install" dialog, click the
"Add..." button. In that dialog, enter the update site URL as
-specified above and give it a name of "YangIDE". Select the provided
+specified above and give it a name of "YANG IDE". Select the provided
plugin and approve the license.
Eclipse will prompt you to restart Eclipse. Do that.
Installation is complete at this point.
+Network Connections
+^^^^^^^^^^^^^^^^^^^
+
+If the installation failed with an indication that it could not reach
+the internet, then your work computer may be behind a firewall.
+You will need to go to the "Network Connections" section of the Eclipse
+preferences (Menubar: "Window"->"Preferences"->"General"->"Network
+Connections").
+
+Before you make these changes, you will need to know the host and port
+of your outbound proxy server.
+
+On the "Network Connections" page, you should select "Manual" in the
+"Active Provider" dropdown, then edit the "HTTP" and "HTTPS" rows in
+the table, setting the host and port of the outbound proxy server.
+
+If the proxy server requires authentication, turn on the "Requires
+Authentication" checkbox and enter the required userid and password
+fields. If you do not know whether your proxy server requires
+authentication, it probably does not.
+
Verifying your Installation
---------------------------
option and click "Next".
On the "New Yang Project" dialog, you may see a wizard page titled
-"Specify YANG Code Generators Parameters". Don't change anything on
+"Specify YANG Code Generators Parameters". Do not change anything on
that page and click "Next".
On the next wizard page, with the title "Select project name and
of the project.
In that resulting list, there are only two entries that you will ever
-care about. One is "src/main/yang", which is where you'll store the
-Yang model files, and the "pom.xml" file, which is where you'll enter
-dependencies for Yang model files to import. If you won't be
-importing any Yang model files, or you'll only be importing other Yang
-model files in your own project, then you'll never have to do anything
+care about. One is "src/main/yang", which is where you will store the
+Yang model files, and the "pom.xml" file, which is where you will enter
+dependencies for Yang model files to import. If you will not be
+importing any Yang model files, or you will only be importing other Yang
+model files in your own project, then you will never have to do anything
with the "pom.xml" file.
Click the arrow to the left of the "src/main/yang" entry to expand that.
up, you can ask questions on the #eclipse IRC channel, or post
questions on the "Newcomers" forum at http://www.eclipse.org/forums/ .
-If Java and Eclipse seem to be fine, but the YangIDE is having
+If Java and Eclipse seem to be fine, but the YANG IDE is having
problems, ask questions on the "yangide-dev" mailing list.
Post Installation Configuration
-------------------------------
-No post-installation steps are required.
+Setting Proxy Used For Maven
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your work computer sits behind a firewall, you will have had to put
+information about your firewall in the "Network Connections" section
+of the Eclipse preferences. That would have allowed you to at least
+obtain the plugin and install it into Eclipse.
+
+Much of the functionality of YANG IDE uses Maven internally. You do
+not need to be a Maven expert to use this functionality, but you will
+need to add a few more lines of configuration so that Maven can get
+through the firewall. Maven, even when running inside Eclipse, as it
+is when you are using YANG IDE, does not use the Eclipse "Network
+Connection" settings to reach the internet. You have to set the proxy
+server information in a different place for Maven.
+
+Maven looks for a file at ``$HOME/.m2/settings.xml`` (Linux) or
+``%HOME%\.m2\settings.xml`` (Windows). If the ``.m2`` folder does not
+exist, you will need to create it. If the "settings.xml" file does not
+exist, you should create it with the following contents::
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
+ <proxies>
+ <proxy>
+ <id>proxy</id>
+ <active>true</active>
+ <protocol>http</protocol>
+ <host>FULLY QUALIFIED NAME OF PROXY HOST</host>
+ <port>PROXY PORT</port>
+ </proxy>
+ <proxy>
+ <id>proxy2</id>
+ <active>true</active>
+ <protocol>https</protocol>
+ <host>FULLY QUALIFIED NAME OF PROXY HOST</host>
+ <port>PROXY PORT</port>
+ </proxy>
+ </proxies>
+ </settings>
+
+Replace "FULLY QUALIFIED NAME OF PROXY HOST" and "PROXY PORT" with the
+host and port of your proxy server.
+
+If the "settings.xml" file already existed, then you will need to edit
+it, inserting the "proxies" element from the above sample at an
+appropriate place.
Upgrading From a Previous Release
---------------------------------
-If you already had the "Yang IDE" plugin from "Xored", you'll need to
+If you already had the "YANG IDE" plugin from "Xored", you will need to
uninstall that plugin before you install this one.
-Uninstalling YangIDE
+Uninstalling YANG IDE
--------------------
-Uninstalling the YangIDE plugin is the same as uninstalling any other Eclipse plugin.
+Uninstalling the YANG IDE plugin is the same as uninstalling any other Eclipse plugin.
Click on the "Help" menu item and select "Installation Details". That
list will have all the plugins you have installed (or that came with
-the distribution). To uninstall YangIDE, you'll need to select four
+the distribution). To uninstall YANG IDE, you will need to select four
entries from that list:
* "m2e connector for YANG"
+*************
Release Notes
-=============
+*************
Target Environment
-------------------
+==================
For Execution
-^^^^^^^^^^^^^
+-------------
The OpenDaylight Karaf container, OSGi bundles, and Java class files
are portable and should run on any Java 7- or Java 8-compliant JVM to
* VTN has components which require Linux
For Development
-^^^^^^^^^^^^^^^
+---------------
OpenDaylight is written primarily in Java project and primarily uses
Maven as a build tool Consequently the two main requirements to develop
the project-specific release notes for details.
Known Issues and Limitations
-----------------------------
+============================
Other than as noted in project-specific release notes, we know of the
following limitations:
.. _proj_rel_notes:
Project-specific Release Notes
-------------------------------
+==============================
For the release notes of individual projects, please see the following pages on the OpenDaylight Wiki.
* YANG_Tools_
Projects without Release Notes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
The following projects participated in Boron, but intentionally do not have release notes.
+***********************
Security Considerations
-=======================
+***********************
This document discusses the various security issues that might affect
OpenDaylight. The document also lists specific recommendations to
which is tasked with identifying and resolving security threats.
Overview of OpenDaylight Security
----------------------------------
+=================================
There are many different kinds of security vulnerabilities that could affect
an OpenDaylight deployment, but this guide focuses on those where (a) the
a well-defined process for reporting and dealing with them.
OpenDaylight Security Resources
--------------------------------
+===============================
* If you have any security issues, you can send a mail to
*security@lists.opendaylight.org*.
refer to https://wiki.opendaylight.org/view/Security:Main
Deployment Recommendations
---------------------------
+==========================
We recommend that you follow the deployment guidelines in setting up
OpenDaylight to minimize security threats.
traffic from the data network to the management network.
Securing OSGi bundles
----------------------
+=====================
OSGi is a Java-specific framework that improves the way that Java classes
interact within a single JVM. It provides an enhanced version of the
For more information, refer to http://www.osgi.org/Main/HomePage.
Securing the Karaf container
-----------------------------
+============================
Apache Karaf is a OSGi-based runtime platform which provides a lightweight
container for OpenDaylight and applications. Apache Karaf uses
http://karaf.apache.org/manual/latest/developers-guide/security-framework.html.
Disabling the remote shutdown port
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------
You can lock down your deployment post installation. Set
``karaf.shutdown.port=-1`` in ``etc/custom.properties`` or ``etc/config.properties`` to
disable the remote shutdown port.
Securing Southbound Plugins
----------------------------
+===========================
Many individual southbound plugins provide mechanisms to secure their
communication with network devices. For example, the OpenFlow plugin supports
mechanisms to connect to devices using the relevant plugins.
Securing OpenDaylight using AAA
--------------------------------
+===============================
AAA stands for Authentication, Authorization, and Accounting. All three of
can help improve the security posture of and OpenDaylight deployment. In this
password *admin*. This should be changed before deploying OpenDaylight.
Security Considerations for Clustering
---------------------------------------
+======================================
While OpenDaylight clustering provides many benefits including high
availability, scale-out performance, and data durability, it also opens a new
+**************************
Who should use this guide?
-==========================
+**************************
OpenDaylight is for users considering open options in network programming. This
guide provides information for the following types of users:
+#################################
OpenDaylight with Openstack Guide
-=================================
+#################################
+********
Overview
---------
+********
OpenStack_ is a popular open source Infrastructure
as a service project, covering compute, storage and network management.
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.
public network, and verify that you can connect to them, and that they can
see each other.
-
+***********************
Installing OpenDaylight
------------------------
+***********************
.. toctree::
:maxdepth: 1
--- /dev/null
+Subproject commit 30d03c604b332d559f4543f47f3d5f3f4e27c1a3
-Subproject commit 9707eb0a4b4c138066b4d3f6c8c68014524cb142
+Subproject commit 1b9a451b5aac36e28c535880d597360bf0069d3b
--- /dev/null
+Subproject commit a942d22ab8fd0d4db74a44b47db852d0938339da
--- /dev/null
+Subproject commit 3d45b3c71137a3271f97e8c5db80fd98954e8087
-Subproject commit 563dcc6bebd5ea05902f92bc5aae1b3b60482e1d
+Subproject commit 6b4cc20fa5c48e706201a902c70c63f9e0520603
--- /dev/null
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+ $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " applehelp to make an Apple Help Book"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " epub3 to make an epub3"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " texinfo to make Texinfo files"
+ @echo " info to make Texinfo files and run them through makeinfo"
+ @echo " gettext to make PO message catalogs"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " xml to make Docutils-native XML files"
+ @echo " pseudoxml to make pseudoxml-XML files for display purposes"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+ @echo " coverage to run coverage check of the documentation (if enabled)"
+
+.PHONY: clean
+clean:
+ rm -rf $(BUILDDIR)/*
+
+.PHONY: html
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OpenDaylightDocumentation.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OpenDaylightDocumentation.qhc"
+
+.PHONY: applehelp
+applehelp:
+ $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+ @echo
+ @echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+ @echo "N.B. You won't be able to view it unless you put it in" \
+ "~/Library/Documentation/Help or install it in your application" \
+ "bundle."
+
+.PHONY: devhelp
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/OpenDaylightDocumentation"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OpenDaylightDocumentation"
+ @echo "# devhelp"
+
+.PHONY: epub
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+ $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+ @echo
+ @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through platex and dvipdfmx..."
+ $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo
+ @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+ @echo "Run \`make' in that directory to run these through makeinfo" \
+ "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ @echo "Running Texinfo files through makeinfo..."
+ make -C $(BUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+ $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+ @echo
+ @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+ $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+ @echo "Testing of coverage in the sources finished, look at the " \
+ "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+ $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+ @echo
+ @echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+ $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+ @echo
+ @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
--- /dev/null
+This folder is designed to receive compiled reST from the makeRST.sh
+script. It is a skeleton to receive the compiled reST and make it
+useful. It is not useful on its own.
--- /dev/null
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# OpenDaylight Documentation documentation build configuration file, created by
+# sphinx-quickstart on Mon Mar 28 14:20:08 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import sphinx_bootstrap_theme
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+javasphinx_available = False
+try:
+ import javasphinx
+ javasphinx_available = True
+ extensions.append('javasphinx')
+except ImportError, e:
+ pass
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'OpenDaylight Documentation'
+copyright = '2016, OpenDaylight Project'
+author = 'OpenDaylight Project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'Boron'
+# The full version, including alpha/beta/rc tags.
+release = 'Boron'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'bootstrap'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+html_theme_options = {
+ 'bootswatch_theme': "united",
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
+
+# The name for this set of Sphinx documents.
+# "<project> v<release> documentation" by default.
+#html_title = 'OpenDaylight Documentation v0.3.0'
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = '_static/odl_small.png'
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not None, a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+# The empty string is equivalent to '%b %d, %Y'.
+#html_last_updated_fmt = None
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# 'ja' uses this config value.
+# 'zh' user can custom change `jieba` dictionary path.
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'OpenDaylightDocumentationdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'OpenDaylightDocumentation.tex', 'OpenDaylight Documentation Documentation',
+ 'OpenDaylight Project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'opendaylightdocumentation', 'OpenDaylight Documentation Documentation',
+ [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'OpenDaylightDocumentation', 'OpenDaylight Documentation Documentation',
+ author, 'OpenDaylightDocumentation', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+
+linkcheck_ignore = [
+ # Ignore jenkins because it's often slow to respond.
+ 'https://jenkins.opendaylight.org/releng',
+ 'https://jenkins.opendaylight.org/sandbox',
+ 'http://\$CONTROL_HOST:8181/dlux/index.html',
+ # The '#' in the path makes sphinx think it's an anchor
+ 'https://git.opendaylight.org/gerrit/#/admin/projects/releng/builder',
+]
+
+# Build integration stuff
+#import subprocess
+
+#subprocess.call(["./build-integration-robot-libdoc.sh"])
+
+# Disable javasphinx generation until we have a solution to long build
+# times. readthedocs timesout after 902 seconds.
+# if javasphinx_available:
+# subprocess.call(["./generate-javaapidoc.sh"])
--- /dev/null
+.. OpenDaylight Documentation documentation master file, created by
+ sphinx-quickstart on Mon Mar 28 14:20:08 2016.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to the OpenDaylight Handbook!
+=====================================
+
+This handbook provides details on various aspects of OpenDaylight from the user
+guides to the developer guides and tries to act as a single point of contact
+for all documentation related articles in OpenDaylight. If you would like to
+contribute to the Handbook please refer to the :ref:`documentation-guide`.
+
+Content for OpenDaylight Users
+------------------------------
+
+The following content is intended for people who would like to deploy, use, or
+just learn more about OpenDaylight.
+
+.. toctree::
+ :maxdepth: 1
+
+ getting-started-guide/index
+ howto-openstack/index
+ user-guide/index
+
+.. Uncomment this when we have reST content targeting developers
+.. Content for OpenDaylight Developers
+.. -----------------------------------
+..
+.. The Following content is intended for developers building applications or code
+.. on top of OpenDaylight, but who do not plan to modify OpenDaylight code
+.. itself.
+
+
+Content for OpenDaylight Contributors
+-------------------------------------
+
+The following content is intended for developers who either currently
+participate in the development of OpenDaylight or would like to start.
+
+.. toctree::
+ :maxdepth: 1
+
+ developer-guide/index
+
+
+.. Commenting the below out until we actually use it
+.. Indices and tables
+.. ==================
+..
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`
--- /dev/null
+@ECHO OFF\r
+\r
+REM Command file for Sphinx documentation\r
+\r
+if "%SPHINXBUILD%" == "" (\r
+ set SPHINXBUILD=sphinx-build\r
+)\r
+set BUILDDIR=_build\r
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .\r
+set I18NSPHINXOPTS=%SPHINXOPTS% .\r
+if NOT "%PAPER%" == "" (\r
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%\r
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%\r
+)\r
+\r
+if "%1" == "" goto help\r
+\r
+if "%1" == "help" (\r
+ :help\r
+ echo.Please use `make ^<target^>` where ^<target^> is one of\r
+ echo. html to make standalone HTML files\r
+ echo. dirhtml to make HTML files named index.html in directories\r
+ echo. singlehtml to make a single large HTML file\r
+ echo. pickle to make pickle files\r
+ echo. json to make JSON files\r
+ echo. htmlhelp to make HTML files and a HTML help project\r
+ echo. qthelp to make HTML files and a qthelp project\r
+ echo. devhelp to make HTML files and a Devhelp project\r
+ echo. epub to make an epub\r
+ echo. epub3 to make an epub3\r
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter\r
+ echo. text to make text files\r
+ echo. man to make manual pages\r
+ echo. texinfo to make Texinfo files\r
+ echo. gettext to make PO message catalogs\r
+ echo. changes to make an overview over all changed/added/deprecated items\r
+ echo. xml to make Docutils-native XML files\r
+ echo. pseudoxml to make pseudoxml-XML files for display purposes\r
+ echo. linkcheck to check all external links for integrity\r
+ echo. doctest to run all doctests embedded in the documentation if enabled\r
+ echo. coverage to run coverage check of the documentation if enabled\r
+ goto end\r
+)\r
+\r
+if "%1" == "clean" (\r
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i\r
+ del /q /s %BUILDDIR%\*\r
+ goto end\r
+)\r
+\r
+\r
+REM Check if sphinx-build is available and fallback to Python version if any\r
+%SPHINXBUILD% 1>NUL 2>NUL\r
+if errorlevel 9009 goto sphinx_python\r
+goto sphinx_ok\r
+\r
+:sphinx_python\r
+\r
+set SPHINXBUILD=python -m sphinx.__init__\r
+%SPHINXBUILD% 2> nul\r
+if errorlevel 9009 (\r
+ echo.\r
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx\r
+ echo.installed, then set the SPHINXBUILD environment variable to point\r
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you\r
+ echo.may add the Sphinx directory to PATH.\r
+ echo.\r
+ echo.If you don't have Sphinx installed, grab it from\r
+ echo.http://sphinx-doc.org/\r
+ exit /b 1\r
+)\r
+\r
+:sphinx_ok\r
+\r
+\r
+if "%1" == "html" (\r
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.\r
+ goto end\r
+)\r
+\r
+if "%1" == "dirhtml" (\r
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.\r
+ goto end\r
+)\r
+\r
+if "%1" == "singlehtml" (\r
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.\r
+ goto end\r
+)\r
+\r
+if "%1" == "pickle" (\r
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished; now you can process the pickle files.\r
+ goto end\r
+)\r
+\r
+if "%1" == "json" (\r
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished; now you can process the JSON files.\r
+ goto end\r
+)\r
+\r
+if "%1" == "htmlhelp" (\r
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished; now you can run HTML Help Workshop with the ^\r
+.hhp project file in %BUILDDIR%/htmlhelp.\r
+ goto end\r
+)\r
+\r
+if "%1" == "qthelp" (\r
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^\r
+.qhcp project file in %BUILDDIR%/qthelp, like this:\r
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\OpenDaylightDocumentation.qhcp\r
+ echo.To view the help file:\r
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\OpenDaylightDocumentation.ghc\r
+ goto end\r
+)\r
+\r
+if "%1" == "devhelp" (\r
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished.\r
+ goto end\r
+)\r
+\r
+if "%1" == "epub" (\r
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.\r
+ goto end\r
+)\r
+\r
+if "%1" == "epub3" (\r
+ %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The epub3 file is in %BUILDDIR%/epub3.\r
+ goto end\r
+)\r
+\r
+if "%1" == "latex" (\r
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.\r
+ goto end\r
+)\r
+\r
+if "%1" == "latexpdf" (\r
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex\r
+ cd %BUILDDIR%/latex\r
+ make all-pdf\r
+ cd %~dp0\r
+ echo.\r
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.\r
+ goto end\r
+)\r
+\r
+if "%1" == "latexpdfja" (\r
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex\r
+ cd %BUILDDIR%/latex\r
+ make all-pdf-ja\r
+ cd %~dp0\r
+ echo.\r
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.\r
+ goto end\r
+)\r
+\r
+if "%1" == "text" (\r
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The text files are in %BUILDDIR%/text.\r
+ goto end\r
+)\r
+\r
+if "%1" == "man" (\r
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.\r
+ goto end\r
+)\r
+\r
+if "%1" == "texinfo" (\r
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.\r
+ goto end\r
+)\r
+\r
+if "%1" == "gettext" (\r
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.\r
+ goto end\r
+)\r
+\r
+if "%1" == "changes" (\r
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.The overview file is in %BUILDDIR%/changes.\r
+ goto end\r
+)\r
+\r
+if "%1" == "linkcheck" (\r
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Link check complete; look for any errors in the above output ^\r
+or in %BUILDDIR%/linkcheck/output.txt.\r
+ goto end\r
+)\r
+\r
+if "%1" == "doctest" (\r
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Testing of doctests in the sources finished, look at the ^\r
+results in %BUILDDIR%/doctest/output.txt.\r
+ goto end\r
+)\r
+\r
+if "%1" == "coverage" (\r
+ %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Testing of coverage in the sources finished, look at the ^\r
+results in %BUILDDIR%/coverage/python.txt.\r
+ goto end\r
+)\r
+\r
+if "%1" == "xml" (\r
+ %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The XML files are in %BUILDDIR%/xml.\r
+ goto end\r
+)\r
+\r
+if "%1" == "pseudoxml" (\r
+ %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml\r
+ if errorlevel 1 exit /b 1\r
+ echo.\r
+ echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.\r
+ goto end\r
+)\r
+\r
+:end\r
--- /dev/null
+#!/bin/bash
+
+# This script compiles documenatation from asciidoc source by
+# converting asciidoc to reStructedText automatically using
+# asciidoctor maven plug in and pandoc (http://www.pandoc.org/).
+#
+# Please make sure you have pandoc (http://www.pandoc.org/) and sphinx
+# (http://www.sphinx-doc.org/) installed.
+
+cwd=$(pwd)
+cp -r $cwd/docs/getting-started-guide $cwd/docs_autotranslation/getting-started-guide
+cp -r $cwd/docs/_static $cwd/docs_autotranslation/_static
+docs='howto-openstack developer-guide user-guide'
+for i in $docs
+ do
+ echo "Translating $i ..."
+ cd $cwd/manuals/$i
+ mvn clean compile
+ cp -r $cwd/manuals/$i/target/generated-docs $cwd/docs_autotranslation/$i
+ mvn clean
+ cd $cwd/docs_autotranslation/$i
+ pandoc -f docbook -t rst -s *.xml -o index.rst
+ done
+
+
+sphinx-build -b html $cwd/docs_autotranslation $cwd/docs_autotranslation/html
+
+
. How to add alto projects as dependencies;
. How to put/fetch data from ALTO;
+. Basic API and DataType;
. How to use customized service implementations.
=== Adding ALTO Projects as Dependencies ===
<version>${ALTO_VERSION}</version>
</dependency>
-The current stable version for ALTO is `0.1.0-Lithium`.
+The current stable version for ALTO is `0.2.0-Beryllium`.
=== Putting/Fetching data from ALTO ===
==== Using RESTful API ====
+
There are two kinds of RESTful APIs for ALTO: the one provided by
`alto-northbound` which follows the formats defined in
link:https://tools.ietf.org/html/rfc7285[RFC 7285], and the one provided by
One way to get the URLs for the resources from `alto-northbound` is to visit
the IRD service first where there is a `uri` field for every entry. However, the
IRD service is not yet implemented so currently the developers have to construct
-the URLs themselves. The base URL is `/controller/nb/v2/alto` and below is a list
-of the specific paths defined in `AltoNorthbound.java` in `alto-northbound`
+the URLs themselves. The base URL is `/alto` and below is a list
+of the specific paths defined in `alto-core/standard-northbound-route`
using Jersey `@Path` annotation:
* `/ird/{rid}`: the path to access __IRD__ services;
-* `/networkmap/{rid}[/{tag}]`: the path to access __Network Map__ services;
-* `/costmap/{rid}[/{tag}[/{mode}/{metric}]]`: the path to access __Cost Map__
-services;
-* `/filtered/networkmap/{rid}[/{tag}]`: the path to access __Filtered Network Map__
-services;
-* `/filtered/costmap/{rid}[/{tag}]`: the path to access __Filtered Cost Map__
-services;
-* `/endpointprop/lookup/{rid}[/{tag}]`: the path to access __Endpoint Property__
-services;
-* `/endpointcost/lookup/{rid}[/{tag}]`: the path to access __Endpoint Cost__
-services.
+* `/networkmap/{rid}[/{tag}]`: the path to access __Network Map__ and __Filtered Network Map__ services;
+* `/costmap/{rid}[/{tag}[/{mode}/{metric}]]`: the path to access __Cost Map__ and __Filtered Cost Map__ services;
+* `/endpointprop`: the path to access __Endpoint Property__ services;
+* `/endpointcost`: the path to access __Endpoint Cost__ services.
NOTE: The segments in brackets are optional.
If you want to fetch the data using RESTCONF, it is highly recommended to take a
-look at the `apidoc` page
-(http://{CONTROLLER_IP}:8181/apidoc/explorer/index.html)
-after installing the `alto-model` feature in karaf.
+look at the `apidoc` page (http://{CONTROLLER_IP}:8181/apidoc/explorer/index.html)
+after installing the `odl-alto-release` feature in karaf.
It is also worth pointing out that `alto-northbound` only supports `GET` and
`POST` operations so it is impossible to manipulate the data through its RESTful
approach might be disabled in the core packages of ALTO but may still be
available as an extension.
-==== Using AD-SAL ====
-Five interfaces are defined in package `service-api-rfc7285`. Follow the steps
-below to use them:
-
-. Determine the required service interface: `IRDService`, `NetworkMapService`,
-`CostMapService`, `EndpointPropertyService` or `EndpointCostService`;
-. Use the `ServiceHelper` to get the instance;
-. Call the corresponding methods with appropriate parameters.
-
==== Using MD-SAL ====
-You can also fetch data from the data store directly.
-First you must get the access to the data store by registering your module with
+You can also fetch data from the datastore directly.
+
+First you must get the access to the datastore by registering your module with
a data broker.
Then an `InstanceIdentifier` must be created. Here is an example of how to build
With the `InstanceIdentifier` you can use `ReadOnlyTransaction`,
`WriteTransaction` and `ReadWriteTransaction` to manipulate the data
accordingly. The `simple-impl` package, which provides some of the AD-SAL APIs
-mentioned above, is using this method to get data from the data store and then
+mentioned above, is using this method to get data from the datastore and then
convert them into RFC7285-compatible objects.
-=== Providing Customized Implementation ===
+=== Basic API and DataType
+
+.. alto-basic-types: Defines basic types of ALTO protocol.
+
+.. alto-service-model-api: Includes the YANG models for the five basic ALTO services defined in link:https://tools.ietf.org/html/rfc7285[RFC 7285].
+
+.. alto-resourcepool: Manages the meta data of each ALTO service, including capabilities and versions.
+
+.. alto-northbound: Provides the root of RFC7285-compatible services at http://localhost:8080/alto.
-Currently it is very simple to provide a customized network map, the
-only thing you have to do is to put the data into the data store. Cost maps are
-more complex since there are no classes for the cost values by default, you have
-to define it using `augment` in YANG. Here is an example in `alto-hosttracker`.
+.. alto-northbound-route: Provides the root of the network map resources at http://localhost:8080/alto/networkmap/.
+
+=== How to customize service
+
+==== Define new service API
+
+Add a new module in `alto-core/standard-service-models`. For example, we named our
+service model module as `model-example`.
+
+==== Implement service RPC
+
+Add a new module in `alto-basic` to implement a service RPC in `alto-core`.
+
+Currently `alto-core/standard-service-models/model-base` has defined a template of the service RPC.
+You can define your own RPC using `augment` in YANG. Here is an example in `alto-simpleird`.
[source,yang]
include::augment.yang[]
+
+==== Register northbound route
+
+If necessary, you can add a northbound route module in `alto-core/standard-northbound-routes`.
- augment "/alto-restconf:resources/alto-restconf:cost-maps/alto-restconf:cost-map/alto-restconf:map/alto-restconf:dst-costs" {
- when "/alto-restconf:resources/alto-restconf:cost-maps/alto-restconf:cost-map/alto-restconf:meta/alto-restconf:cost-type/alto-restconf:cost-mode == 'numerical'";
- leaf cost-in-hosttracker {
- type int32;
+ grouping "alto-ird-request" {
+ container "ird-request" {
}
}
+ grouping "alto-ird-response" {
+ container "ird" {
+ container "meta" {
+ }
+ list "resource" {
+ key "resource-id";
+ leaf "resource-id" {
+ type "alto-types:resource-id";
+ }
+ }
+ }
+ }
+ augment "/base:query/base:input/base:request" {
+ case "ird-request-data" {
+ uses "alto-ird-request";
+ }
+ }
+ augment "/base:query/base:output/base:response" {
+ case "ird-response-data" {
+ uses "alto-ird-response";
+ }
+ }
\ No newline at end of file
+++ /dev/null
-== Armoury
-
-=== Overview
-TBD: Overview of the Armoury feature, what logical functionality it
-provides and why you might use it as a developer.
-
-=== Armoury Architecture
-TBD: Armoury components and how they work together.
-Also include information about how the feature integrates with
-OpenDaylight and architecture.
-
-=== Key APIs and Interfaces
-TBD: Document the key things a user would want to use.
-
-==== Armoury Catalog API
-TBD: A description of Armoury Catalog API.
-
-==== Armoury Workload Manager API
-TBD: A description of Armoury Workload Manager API.
-
-==== Armoury Driver Registry API
-TBD: A description of Armoury Driver Registry API.
-
-=== API Reference Documentation
-TBD: Provide links to JavaDoc, REST API documentation, etc.
+++ /dev/null
-== BGP LS PCEP
-
-=== BGPCEP Overview
-
-An extension to a protocol means adding parsers and serializers for new elements, such as messages, objects, TLVs or subobjects.
-This is necessary when you are extending the protocol with another RFC or draft. Both BGP and PCEP parsers are pluggable and you can specify which extensions to load alongside to the base parser in the configuration file.
-
-Writing an extension to PCE protocol
-Current standards support
-Current pcep base-parser implementation supports following RFCs: +
-
-http://tools.ietf.org/html/rfc5440[RFC5440] - Path Computation Element (PCE) Communication Protocol (PCEP) +
-http://tools.ietf.org/html/rfc5541[RFC5541] - Encoding of Objective Functions in the Path Computation Element Communication Protocol (PCEP) +
-http://tools.ietf.org/html/rfc5455[RFC5455] - Diffserv-Aware Class-Type Object for the Path Computation Element Communication Protocol +
-http://tools.ietf.org/html/rfc5521[RFC5521] - Extensions to the Path Computation Element Communication Protocol (PCEP) for Route Exclusions +
-http://tools.ietf.org/html/rfc5557[RFC5557] - Path Computation Element Communication Protocol (PCEP) Requirements and Protocol Extensions in Support of Global Concurrent Optimization +
-
-There are already two extensions for: +
-https://tools.ietf.org/html/draft-ietf-pce-stateful-pce-09[draft-ietf-pce-stateful-pce] - in versions 02 and 07 +
-https://tools.ietf.org/html/draft-ietf-pce-pce-initiated-lsp-01[draft-ietf-pce-pce-initiated-lsp] - versions crabbe-initiated-00 and ietf-initiated-00
-
-
-[literal]
-
-dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>pcep-ietf-stateful02</artifactId>
-</dependency>
-
-[literal]
-
-<dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>pcep-ietf-stateful07</artifactId>
-</dependency>
-
-NOTE: It is important to load the extensions with compatible versions because that they extend each other. In this case crabbe-initiated-00 is compatible with stateful-02 and ietf-initiated-00 is compatible with stateful-07.
-
-=== Implementing an Extension to PCEP
-
-To implement an extension of PCEP: +
-
-. Create a separate artefact (eclipse project) for your extension. +
-Ensure the dependency on pcep-api and pcep-spi.
-. Write YANG model for new elements or augment existing ones.
-. Perform `mvn install` to generate files from the model.
-. Write parsers and serializers. All parsers need to implement *Parser and *Serializer interfaces from pcep-spi, (For example: If you are writing a new TLV, your parser must implement TlvParser and TlvSerializer), add Activator, that extends AbstractPCEPExtensionProviderActivator, where you register your parsers and serializers.
-
-=== Update Configuration
-Update [32-pcep.xml]. Register your parser as a module in pcep-impl: +
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
- prefix:pcep-parser-new-parser
- </type>
- <name>pcep-parser-new-parser</name>
-</module>
-
-* Add it as an extension to pcep-parser-base:
-
-[literal]
-<extension>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <name>pcep-parser-new-parser</name>
-</extension>
-
-* Add the instance to services:
-
-[literal]
-<instance>
- <name>pcep-parser-new-parser</name>
- <provider>/config/modules/module[name='pcep-parser-new-parser']/instance[name='pcep-parser-new-parser']</provider>
-</instance>
-
-* Update `odl-pcep-impl-cfg.yang` so that it generates Module and ModuleFactory classes for your new parser.
-
-[literal]
-identity pcep-parser-new-parser {
- base config:module-type;
- config:provided-service spi:extension;
- config:java-name-prefix NewParserPCEPParser;
-}
-
-[literal]
-
-augment "/config:modules/config:module/config:configuration" {
- case pcep-parser-new-parser {
- when "/config:modules/config:module/config:type = 'pcep-parser-new-parser'";
- }
-}
-
-Run mvn install on pcep-impl-config to generate Module and ModuleFactory files.
-* Update Module to start your NewParserPCEPParserModule.java whent it's created
-
-[literal]
-@Override
-public java.lang.AutoCloseable createInstance() {
- return new InitiatedActivator();
-}
-
-==== Writing an Extension to BGP +
-
-Current standards support
-
-Current bgp base-parser implementation supports following RFCs: +
-
-http://tools.ietf.org/html/rfc4271[RFC4271] - A Border Gateway Protocol 4 (BGP-4) +
-http://tools.ietf.org/html/rfc4724[RFC4724] - Graceful Restart Mechanism for BGP +
-http://tools.ietf.org/html/rfc4760[RFC4760] - Multiprotocol Extensions for BGP-4 +
-http://tools.ietf.org/html/rfc1997[RFC1997] - BGP Communities Attribute +
-http://tools.ietf.org/html/rfc4360[RFC4360] - BGP Extended Communities Attribute +
-http://tools.ietf.org/html/rfc6793[RFC6793] - BGP Support for Four-Octet Autonomous System (AS) Number Space (NEW speaker only) +
-
-There is already one extension for: +
-https://tools.ietf.org/html/draft-ietf-idr-ls-distribution-06[draft-ietf-idr-ls-distribution] - in version 04
-
-=== Implementing an Extension to BGP
-
-To implement an extension to BGP:
-
-. Create a separate artefact (eclipse project) for your extension.
-Ensure it depends on pcep-api and pcep-spi.
-. Write yang model for new elements or augment existing ones.
-. Perform `mvn install` to generate files from the model.
-. Write parsers and serializers. All parsers need to implement *Parser* and *Serializer* interfaces from bgp-spi. For example: If you are writing a new capability, your parser should implement CapabilityParser and CapabilitySerializer).
-Add Activator, that extends AbstractBGPExtensionProviderActivator, where you register your parsers and serializers. If your extension adds another AFI/SAFI you must to add another Activator that extends AbstractRIBExtensionProviderActivator and registrate new address family and subsequent address family.
-
-=== Updating Configuration
-Update 31-bgp.xml. Register your parser as a module in bgp-impl:
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:new-parser">
- prefix:bgp-new-parser
- </type>
- <name>bgp-new-parser</name>
-</module>
-
-* Add it as an extension to bgp-parser-base:
-[literal]
-<extension>
- <type xmlns:bgpspi="urn:opendaylight:params:xml:ns:yang:controller:bgp:parser:spi">
- bgpspi:extension
- </type>
- <name>bgp-new-parser</name>
-</extension>
-
-* Add the instance to services:
-[literal]
-<instance>
- <name>bgp-new-parser</name>
- <provider>/modules/module[type='bgp-new-parser'][name='bgp-new-parser']</provider>
-</instance>
-
-Also, if you are introducing new AFI/SAFI, do not forget to registrate your extension also to RIB.
-
-* Create your own configuration file so that it generates Module and ModuleFactory classes for your new parser.
-
-[literal]
-identity bgp-new-parser {
- base config:module-type;
- config:provided-service bgpspi:extension;
- config:provided-service ribspi:extension; // for new AFI/SAFI
- config:java-name-prefix NewParser;
-}
-
-[literal]
-augment "/config:modules/config:module/config:configuration" {
- case bgp-new-parser {
- when "/config:modules/config:module/config:type = 'bgp-new-parser'";
- }
-}
-
-Run mvn install on your extension artefact to generate Module and ModuleFactory files.
-
-* Update Module to start your NewParserModule.java whent it's created.
-[literal]
-@Override
-public java.lang.AutoCloseable createInstance() {
- return new NewParserActivator();
-}
-
-
-==== Programmatic Interface(s)
-
-Howto pull code from gerrit: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Pulling,_Hacking,_and_Pushing_the_Code_from_the_CLI[OpenDaylight Controller:Pulling, Hacking, and Pushing the Code from the CLI] +
-Gerrit repository: https://git.opendaylight.org/gerrit/bgpcep[gerrit] +
-Bugzilla: https://bugs.opendaylight.org/[Bugzilla] +
-Mailing lists +
-
-* bgpcep-bugs@opendaylight.org
-* bgpcep-dev@opendaylight.org
-
-YANG Models - https://jenkins.opendaylight.org/bgpcep/job/bgpcep-nightly/lastSuccessfulBuild/artifact/target/staging/releasepom/apidocs/index.html[BGP LS PCEP:Models] +
-
-API Documentation – https://wiki.opendaylight.org/view/BGP_LS_PCEP:Models[Javadoc API]
-
-For debugging purposes, set lower log levels for bgpcep project in logback.xml.
-
-[literal]
-<logger name="org.opendaylight.protocol" level="TRACE" />
-<logger name="org.opendaylight.bgpcep" level="TRACE" />
-
-
-==== Vendor Specific Constraints in PCEP
-http://tools.ietf.org/html/draft-ietf-pce-rfc7150bis-00[draft-ietf-pce-rfc7150bis-00] - Conveying Vendor-Specific Constraints in the Path Computation Element communication Protocol.
-
-Draft defines new PCEP object - Vendor Information object, that can be used to carry arbitrary, proprietary information such as vendor-specific constraints. Draft also defines new PCEP TLV - Vendor Information TLV that can be used to carry arbitrary information within any PCEP object that supports TLVs.
-
-The ODL PCEP supports _draft-ietf-pce-rfc7150bis-00_ and provides abstraction for developers to create vendor-specific TLVs/objects extensions. The yang model of _vendor-information-tlv/object_ is defined in _pcep-types.yang_ and used in pcep objects/messages as defined in the draft.
-
-This tutorial shows how to develop PCEP extension of vendor-information object and TLV for fictional company named My Vendor, whose enterprise number is 0. A result will be OSGi bundle and initial configuration xml file, that supports MY-VENDOR-TLV and MY-VENDOR-OBJECT in ODL.
-
-* First, create simple maven module named _pcep-my-vendor_. For simplification assume the module parent is _pcep_ maven project. For bundle packaging add _plugin maven-bundle-plugin_ into _pom.xml_ and also _yang-maven-plugin_ for compile-time java code generating.
-
-[literal]
-<artifactId>pcep-my-vendor</artifactId>
- <description>PCEP MY VENDOR EXTENSION</description>
- <packaging>bundle</packaging>
- <name>${project.artifactId}</name>
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-Name>${project.groupId}.${project.artifactId}</Bundle-Name>
- </instructions>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.opendaylight.yangtools</groupId>
- <artifactId>yang-maven-plugin</artifactId>
- </plugin>
- </plugins>
- </build>
-
-* Add required dependencies into _pom.xml_.
-
-[literal]
- <dependencies>
- <dependency>
- <groupId>org.opendaylight.controller</groupId>
- <artifactId>config-api</artifactId>
- </dependency>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>pcep-api</artifactId>
- </dependency>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>pcep-spi</artifactId>
- </dependency>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>pcep-impl</artifactId>
- </dependency>
- </dependencies>
-
-=== Vendor Information TLV
-
-The Vendor Information TLV is used for vendor-specific information that applies to a specific PCEP object by including the TLV in the object. For the purpose of this tutorial, define MY-VENDOR-TLV, which can be loaded wih just simple unsigned 32-bit integer (4 bytes) as it's value and the TLV is carried in Open object.
-
-*Yang model* +
-
-* Initial step is to extend pcep-types and pcep-message yang models, augmentation target is _enterprise-specific-information_ (choice) located in Open messages's Open object. Create yang file (_pcep-my-vendor.yang_), in project's _src/main/yang_ folder, with definition of the vendor information and required augmentations.
-* Now build project with maven, after that generated Java API's appears in _target/generated-sources/sal_.
-
-[literal]
-grouping my-vendor-information {
- leaf payload {
- type uint32;
- }
-}
-augment "/msg:open/msg:open-message/msg:open/msg:tlvs/msg:vendor-information-tlv/msg:enterprise-specific-information" {
- case my-vendor {
- when "enterprise-number = 0";
- uses my-vendor-information;
- }
-}
-
-* Vendor Information TLV parser/serializer
-* Next step is an implementation of the enterprise-specific-information (TLV's value) parser/serializer. It is simple serialization/deserialization of unsigned integer (long type in Java representation), other functionality is already presented in _org.opendaylight.protocol.pcep.impl.tlv.AbstractVendorInformationTlvParser abstract_ class. Create class extending _AbstractVendorInformationTlvParser_ and implement missing methods.
-
-[literal]
-
-public class MyVendorInformationTlvParser extends AbstractVendorInformationTlvParser {
- private static final EnterpriseNumber EN = new EnterpriseNumber(0L);
- @Override
- public EnterpriseNumber getEnterpriseNumber() {
- return EN;
- }
- @Override
- public EnterpriseSpecificInformation parseEnterpriseSpecificInformation(final ByteBuf buffer)
- throws PCEPDeserializerException {
- return new MyVendorBuilder().setPayload(buffer.readUnsignedInt()).build();
- }
- @Override
- public void serializeEnterpriseSpecificInformation(final EnterpriseSpecificInformation esi, final ByteBuf buffer) {
- final MyVendor myVendorInfo = (MyVendor) esi;
- buffer.writeInt(myVendorInfo.getPayload().intValue());
- }
-}
-
-*Vendor Information TLV Activator* +
-
-* Now, parser/serializer needs to be registered to _VendorInformationTlvRegistry_. Create class extending _AbstractPCEPExtensionProviderActivator_ and implement _startImpl_ method - register parser idenfied by enterprise number and register serializer identified by the class extending _EnterpriseSpecificInformation_.
-
-[literal]
-
-public class Activator extends AbstractPCEPExtensionProviderActivator {
- @Override
- protected List<AutoCloseable> startImpl(PCEPExtensionProviderContext context) {
- final List<AutoCloseable> regs = new ArrayList<>();
- final MyVendorInformationTlvParser parser = new MyVendorInformationTlvParser();
- regs.add(context.registerVendorInformationTlvParser(parser.getEnterpriseNumber(), parser));
- regs.add(context.registerVendorInformationTlvSerializer(MyVendor.class, parser));
- return regs;
- }
- }
-
-*Configuration Module* +
-
-* Create configuration yang module with name i.e. _pcep-my-vendor-cfg.yang_. Define My Vendor parser extension service provider config module.
-* Build project with maven to generate cofiguration module and module factory. They are located in _src/main/java_.
-* Implement _MyVendorPCEPParserModule#createInstance()_ - return instance of Activator created above.
-
-[literal]
-identity pcep-parser-my-vendor {
- base config:module-type;
- config:provided-service spi:extension;
- config:java-name-prefix MyVendorPCEPParser;
-}
-augment "/config:modules/config:module/config:configuration" {
- case pcep-parser-my-vendor {
- when "/config:modules/config:module/config:type = 'pcep-parser-my-vendor'";
- }
-}
-
-[literal]
-@Override
- public java.lang.AutoCloseable createInstance() {
- return new Activator();
- }
-
-*Initial Configuration* +
-
-Create initial configuration xml file, where module _pcep-parser-my-vendor_ is instantiated and injected into the _global-pcep-extensions_.
-
-[literal]
-<snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:pcep:spi?module=odl-pcep-spi-cfg&revision=2013-11-15</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:pcep:my:vendor:cfg?module=pcep-my-vendor-cfg&revision=2014-09-20</capability>
- </required-capabilities>
- <configuration>
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">prefix:pcep-extensions-impl</type>
- <name>global-pcep-extensions</name>
- <extension>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <name>pcep-parser-my-vendor</name>
- </extension>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:my:vendor:cfg">
- prefix:pcep-parser-my-vendor
- </type>
- <name>pcep-parser-my-vendor</name>
- </module>
- </modules>
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <instance>
- <name>pcep-parser-my-vendor</name>
- <provider>/config/modules/module[name='pcep-parser-my-vendor']/instance[name='pcep-parser-my-vendor']</provider>
- </instance>
- </service>
- </services>
- </data>
- </configuration>
-</snapshot>
-
-
-=== Vendor Information Object
-
-For the tutorial purposes, define MY-VENDOR-OBJECT, which can be loaded with Ipv4 address (4 bytes) as it's value and the object is carried in PCRep message's response.
-
-*Yang Model* +
-
-* Initial step is to extend _pcep-types_ and _pcep-message_ yang models, augmentation target is _enterprise-specific-information_ (choice) located in PCRep messages. Create yang file (_pcep-my-vendor.yang_), in project _src/main/yang_ folder, with definition of the vendor information and required augmentations.
-* Now build project with maven, after that generated Java API's appears in _target/generated-sources/sal_.
-
-[literal]
-grouping my-vendor-information {
- leaf payload {
- type inet:ipv4-address;
- }
-}
- augment "/msg:pcrep/msg:pcrep-message/msg:replies/msg:vendor-information-object/msg:enterprise-specific-information" {
- case my-vendor {
- when "enterprise-number = 0";
- uses my-vendor-information;
- }
-}
-
-*Vendor Information Object Parser/Serializer* +
-
-* Implementation of the _enterprise-sepecific-information_ (Object value) parser/serializer. It is simple serialization/deserialization of IPv4 address, other functionality is already presented in _org.opendaylight.protocol.pcep.impl.object.AbstractVendorInformationObjectParser_ abstract class. Create class extending _AbstractVendorInformationObjectParser_ and implement missing methods.
-
-[literal]
-
-public class MyVendorInformationObjectParser extends AbstractVendorInformationObjectParser {
- private static final EnterpriseNumber EN = new EnterpriseNumber(0L);
- @Override
- public EnterpriseNumber getEnterpriseNumber() {
- return EN;
- }
- @Override
- public EnterpriseSpecificInformation parseEnterpriseSpecificInformation(final ByteBuf buffer)
- throws PCEPDeserializerException {
- return new MyVendorBuilder().setPayload(Ipv4Util.addressForByteBuf(buffer)).build();
- }
- @Override
- public void serializeEnterpriseSpecificInformation(final EnterpriseSpecificInformation esi, final ByteBuf buffer) {
- final MyVendor myVendor = (MyVendor) esi;
- buffer.writeBytes(Ipv4Util.bytesForAddress(myVendor.getPayload()));
- }
-}
-
-*Vendor Information Object Activator* +
-
-Parser/serializer must be registered to VendorInformationObjectRegistry. Create class extending AbstractPCEPExtensionProviderActivator and implement startImpl method - register parser idenfied by enterprise number and register serializer identified by the class extending EnterpriseSpecificInformation.
-
-[literal]
-public class Activator extends AbstractPCEPExtensionProviderActivator {
- @Override
- protected List<AutoCloseable> startImpl(PCEPExtensionProviderContext context) {
- final List<AutoCloseable> regs = new ArrayList<>();
- final MyVendorInformationObjectParser parser = new MyVendorInformationObjectParser();
- regs.add(context.registerVendorInformationObjectParser(parser.getEnterpriseNumber(), parser));
- regs.add(context.registerVendorInformationObjectSerializer(MyVendor.class, parser));
- return regs;
- }
- }
-
-*Configuration Module* +
-
-* Create configuration yang module with name (_pcep-my-vendor-cfg.yang_).
-* Define My Vendor parser extension service provider configuration module.
-* Build project with maven to generate configuration module and module factory located in _src/main/java_.
-* Implement _MyVendorPCEPParserModule#createInstance()_ - return instance of Activator created.
-
-[literal]
-identity pcep-parser-my-vendor {
- base config:module-type;
- config:provided-service spi:extension;
- config:java-name-prefix MyVendorPCEPParser;
-}
-
-augment "/config:modules/config:module/config:configuration" {
- case pcep-parser-my-vendor {
- when "/config:modules/config:module/config:type = 'pcep-parser-my-vendor'";
- }
-}
-
-[literal]
- @Override
- public java.lang.AutoCloseable createInstance() {
- return new Activator();
- }
-
-
-*Initial Configuration* +
-
-Create initial configuration xml file, where module _pcep-parser-my-vendor_ is instantiated and injected into the _global-pcep-extensions_.
-
-[literal]
-<snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:pcep:spi?module=odl-pcep-spi-cfg&revision=2013-11-15</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:pcep:my:vendor:cfg?module=pcep-my-vendor-cfg&revision=2014-09-20</capability>
- </required-capabilities>
- <configuration>
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- prefix:pcep-extensions-impl
- </type>
- <name>global-pcep-extensions</name>
- <extension>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <name>pcep-parser-my-vendor</name>
- </extension>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:my:vendor:cfg">
- prefix:pcep-parser-my-vendor
- </type>
- <name>pcep-parser-my-vendor</name>
- </module>
- </modules>
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <instance>
- <name>pcep-parser-my-vendor</name>
- <provider>/config/modules/module[name='pcep-parser-my-vendor']/instance[name='pcep-parser-my-vendor']</provider>
- </instance>
- </service>
- </services>
- </data>
- </configuration>
-</snapshot>
\ No newline at end of file
</affiliation>
</author>
<copyright>
- <year>2015</year>
+ <year>2016</year>
<holder>Linux Foundation</holder>
</copyright>
- <releaseinfo>Beryllium</releaseinfo>
+ <releaseinfo>Boron</releaseinfo>
<productname>OpenDaylight</productname>
<pubdate></pubdate>
<legalnotice role="license">
include::alto/alto-developer-guide.adoc[ALTO]
-include::armoury/odl-armoury-dev.adoc[ARMOURY]
-
include::bgpcep/odl-bgpcep-bgp-all-dev.adoc[BGP]
include::bgpcep/odl-bgpcep-bmp-dev.adoc[BGP]
include::capwap/capwap-dev.adoc[CAPWAP]
+include::cardinal/odl-cardinal-dev.adoc[]
+
include::controller/controller.adoc[Controller]
include::didm/didm-dev.adoc[]
include::lacp/lacp-dev.adoc[]
-include::messaging4transport/messaging4transport-developer.adoc[]
-
include::controller/netconf/odl-netconf-dev.adoc[]
include::nic/nic-dev.adoc[]
include::sxp/odl-sxp-dev.adoc[]
-include::tcpmd5/odl-tcpmd5-all-dev.adoc[TCP-MD5]
-
include::topoprocessing/odl-topoprocessing-framework-dev.adoc[]
include::ttp/ttp-model-dev.adoc[]
--- /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:
+
+. 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"
+ }
+ }
+
+++ /dev/null
-== Messaging4Transport Developer Guide
-
-=== Overview
-Messaging4Transport can be configured such that the data tree, RPCs, and notifications are sent to an external broker, or an integrated broker with OpenDaylight. Messaging4Transport uses ActiveMQ as the default external broker. It further uses AMQP as the messaging protocol for the Beryllium Release.
-
-
-=== Messaging4Transport Architecture
-The ActiveMQ client implementation for AMQP hides the implementation behind the Java Message Service (JMS) API. ActiveMQ further depends on https://qpid.apache.org/[QPid] for its AMQP clients and broker. Hence, QPid and JMS bundles are introduced as the dependencies to the odl-messaging4transport feature.
-
-
-ActiveMQ also has a http://stomp.github.io/[Simple (or Streaming) Text Oriented Message Protocol (STOMP)] implementation in the same way through StompJmsConnectionFactory, a JMS mapping and interface for STOMP. http://activemq.apache.org/openwire.html[OpenWire] is a cross-language wire protocol from ActiveMQ. The OpenWire implementation of ActiveMQ follows the similar strategy and implementation. With almost no changes to the architecture, and minimal code changes, publishing to STOMP or OpenWire broker implementations (such as ActiveMQ) should be possible, from OpenDaylight/MD-SAL with the odl-messaging4transport feature.
-
-
-There is also an http://mqtt.org/[MQTT] implementation in ActiveMQ, which is slightly different in the implementation from AMQP, STOMP, and OpenWire implementations, and does not seem to depend on JMS.
-
-
-=== Key APIs and Interfaces
-Messaging4Transport consists of the messaging4transport feature which offers an AMQP message-oriented middleware northbound to MD-SAL, as an alternative to the traditional RESTCONF northbound.
-
-
-=== Use Cases
-
-Multiple research and industrial https://wiki.opendaylight.org/view/Messaging4Transport:Use_Cases[use cases] of Messaging4Transport has been proposed. Since Messaging4Transport is still in its early stages, many of these use cases are still proof of concepts and novel research publications.
-
-* *Software-Defined Buildings*
-+
-http://www.navigators.di.fc.ul.pt/w2/img_auth.php/9/90/Navtalk20151120_Kathiravelu.paper.pdf[Cassowary] is a middleware platform for context-aware smart buildings with software-defined sensor networks, by leveraging OpenDaylight Messaging4Transport. Messaging4Transport architecture has been extended by Cassowary approach to create a software-defined sensor and actuator network for smart buildings.
-+
-* *Software-Defined Community Networks*
-+
-http://www.gsd.inesc-id.pt/~pradeeban/SDS2016/IEEE_SDS_16_CHIEF.pdf[CHIEF] is a controller farm for clouds of software-defined community networks. CHIEF leverages the message-oriented middleware and OpenDaylight Messaging4Transport architecture to create a huge deployment of SDN for community clouds.
\ No newline at end of file
+++ /dev/null
-== Authentication Service\r
-Authentication uses the credentials presented by a user to identify the user.\r
-\r
-=== Authenthentication data model\r
-A user requests authentication within a domain in which the user has defined roles.\r
-The user chooses either of the following ways to request authentication:\r
-\r
-* Provides credentials\r
-* Creates a token scoped to a domain. In OpenDaylight, a domain is a grouping of resources (direct or indirect, physical, logical, or virtual) for the purpose of access control.\r
-\r
-==== Terms and definitions in the model\r
-Token:: A claim of access to a group of resources on the controller\r
-Domain:: A group or isolation of resources, direct or indirect, physical, logical, or virtual, for the purpose of access control\r
-User:: A person who either owns and has, or has, access to a resource or group of resources on the controller\r
-Role:: Opaque representation of a set of permissions, which is merely a unique string as admin or guest\r
-Credential:: Proof of identity such as username and password, OTP, biometrics, or others\r
-Client:: A service or application that requires access to the controller\r
-\r
-==== Authentication methods\r
-There are three ways a user may authenticate in OpenDaylight: +\r
-\r
-* Token-based Authentication\r
-** Direct authentication: A user presents username/password and a domain the user wishes to access to the controller and obtains a timed (default is 1 hour) scoped access token. The user then uses this token to access Restconf (for example).\r
-** Federated authentication: A user presents credentials to a third-party Identity Provider (for example, SSSD) trusted by the controller. Upon successful authentication, the controller returns a refresh (unscoped) token with a list of domains that the user has access to. The user then presents this refresh token scoped to a domain that the user has access to obtain a scoped access token. The user then uses this access token to access Restconf (for example).\r
-* Basic Authentication\r
-:: For backward compatibility with the ODL Hydrogen release, the controller also supports the normal basic authentication with username/password.\r
-\r
-===== Example with token authentication using curl (username/password = admin/admin, domain = sdn):\r
-\r
- # Create a token\r
- curl -ik -d 'grant_type=password&username=admin&password=admin&scope=sdn' http://localhost:8181/oauth2/token\r
-\r
- # Use the token (e.g., ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9) obtained from above (default token validity is 1 hour):\r
- curl -ik -H 'Authorization:Bearer ed3e5e05-b5e7-3865-9f63-eb8ed5c87fb9' http://localhost:8181/restconf/config/toaster:toaster\r
-\r
-Example with basic auth using curl: +\r
-\r
- curl -ik -u 'admin:admin' http://localhost:8181/restconf/config/toaster:toaster\r
-\r
-=== How the ODL Authentication Service works\r
-In direct authentication, a service relationship exists between the user and the ODL controller. The user and the controller establish trust that allows them to use, and validate credentials.\r
-The user establishes user identity through credentials.\r
-\r
-In direct authentication, a user request progresses through the following steps:\r
-\r
-. The user requests the controller administrator for a user account. \r
-\r
-:: Associated with the user account are user credentials, initially created by the administrator. Opendaylight supports only username/password credentials. By default, an administrator account is included with ODL out-of-the-box the username and password for which are admin/admin. \r
-In addition to creating the user account, the controller administrator also assigns roles to that account on one or more domains. By default, there are two user roles: admin and user. By default, there is only one domain: sdn.\r
-[start=2]\r
-. The user presents the credentials to the service within a domain in a request for a token. \r
-. The request is then passed on to the controller token endpoint.\r
-. The controller token endpoint sends it to the credential authentication entity which returns a claim for the client. \r
-. The controller token entity transforms the claim (for user, domain, and roles) into a token which it then provides to the user.\r
-\r
-In federated authentication, with the absence of a direct trust relationship between the user and the service, a third-party Identity Provider (IdP) is used for authentication. Federated authentication relies on third-party identity providers (IdP) to authenticate the user. An example of an external IdP is Linux SSSD (System Security Services Daemon) or Openstack Keystone.\r
-\r
-The user is authenticated by the trusted IdP and a claim is returned to the ODL authentication services upon successful authentication. The claim is mapped into ODL users or roles and transformed into a token that is passed onto the user. The request is passed on to the claim authentication broker that transforms it to a claim. The controller turns the claim into a token that is passed on to the user.\r
-\r
-In a federated authentication set-up, the Opendaylight controller extends SSSD claim support. SSSD also provides mapping capabilities. SSSD maps users in an external LDAP server to users defined on the Opendaylight controller.\r
-\r
-=== Configuring Authentication service\r
-Changes to AAA configurations can be made from the following:\r
-\r
-* Webconsole\r
-* CLI (config command in the Karaf shell)\r
-* Editing the etc/org.opendaylight.aaa.*.cfg files directly\r
-\r
-Every Authentication Service karaf feature has its configuration file. \r
-\r
-NOTE: Configurations for AAA are all dynamic and require no restart.\r
-\r
-To configure features from the Web console: +\r
-\r
-. Install the Web console:\r
-----\r
-feature:install webconsole\r
-----\r
-[start=2]\r
-. On the console (http://localhost:8181/system/console) (default Karaf username/password: karaf/karaf), go to *OSGi* > *Configuration* > *ODL AAA Authentication Configuration*.\r
-.. *Authorized Clients*: List of software clients that are authorized to access ODL NB APIs.\r
-.. *Enable Authentication*: Enable or disable authentication. (The default is enable.)\r
-\r
-==== Configuring tokens\r
-. On the console, click *ODL AAA Token Configuration*.\r
-:: The fields you can configure are as follows:\r
-.. *Memory Configuration*: Configure the maximum number of tokens to be retained in memory.\r
-.. *Disk Configuration*: The maximum number of tokens to be retained on the disk.\r
-\r
-NOTE: When Memory is exhausted, tokens are moved to the disk.\r
-[start=3]\r
-.. *Token Expiration*: The number of seconds that a token remains live irrespective of use.\r
-.. *Unused Token Expiration*: The number of seconds that a token is live without being accessed. \r
-(The default period for both Expiration fields is 1 hour or 3600 seconds.)\r
-\r
-==== Configuring AAA federation\r
-\r
-. On the console, click *ODL AAA Federation Configuration*.\r
-. Use the *Custom HTTP Headers* or *Custom HTTP Attributes* fields to specify the HTTP headers or attributes for federated authentication. Normally, such specification is not required.\r
-\r
-NOTE: As the changes you make to the configurations are automatically committed when they are saved, no restart of the Authentication service is required.\r
-\r
-=== How federated authentication is set up\r
-Use the following steps to set up federated authentication: +\r
-\r
-. Set up an Apache front-end and Apache mods for the ODL controller.\r
-. Set up mapping rules (from LDAP users to ODL users).\r
-. Use the ClaimAuthFilter in federation to allow claim transformation.\r
-\r
-=== Mapping users to roles and domains\r
-The ODL authentication service transforms assertions from an external federated IdP into Authentication Service data: +\r
-\r
-. The Apache web server which fronts ODL AAA sends data to SssdAuthFilter.\r
-. SssdAuthFilter constructs a JSON document from the data.\r
-. ODL Authentication Service uses a general purpose transformation mapper to transform the JSON document.\r
-\r
-==== Operational model\r
-The mapping model works as follows: +\r
-\r
-. Assertions from an IdP are stored in an associative array.\r
-. A sequence of rules is applied, and the first rule which returns success is considered a match.\r
-. Upon success, an associative array of mapped values is returned.\r
-\r
-** The mapped values are taken from the local variables set during the rule execution.\r
-** The definition of the rules and mapped results are expressed in JSON notation.\r
-\r
-==== Operational Model: Sample code\r
-----\r
-mapped = null\r
-foreach rule in rules {\r
- result = null\r
- initialize rule.variables with pre-defined values\r
-\r
- foreach block in rule.statement_blocks {\r
- for statement in block.statements {\r
- if statement.verb is exit {\r
- result = exit.status\r
- break\r
- }\r
- elif statement.verb is continue {\r
- break\r
- }\r
- }\r
- if result {\r
- break\r
- }\r
- if result == null {\r
- result = success\r
- }\r
-if result == success {\r
- mapped = rule.mapping(rule.variables)\r
-}\r
-return mapped\r
-----\r
-\r
-==== Mapping Users\r
-A JSON Object acts as a mapping template to produce the final associative array of name/value pairs. The value in a name/value pair can be a constant or a variable.\r
-An example of a mapping template and rule variables in JSON: +\r
-Template: +\r
-----\r
-{\r
- "organization": "BigCorp.com",\r
- "user: "$subject",\r
- "roles": "$roles"\r
-}\r
-----\r
-Local variables: +\r
-----\r
-{\r
- "subject": "Sally",\r
- "roles": ["user", "admin"]\r
-}\r
-----\r
-The final mapped result will be: +\r
-----\r
-{\r
- "organization": "BigCorp.com",\r
- "user: "Sally",\r
- "roles": ["user", "admin"]\r
-}\r
-----\r
-\r
-==== Example: Splitting a fully qualified username into user and realm components\r
-Some IdPs return a fully qualified username (for example, principal or subject). The fully qualified username is the concatenation of the user name, separator, and realm name.\r
-The following example shows the mapped result that returns the user and realm as independent values for the fully qualified username is bob@example.com .\r
-\r
-The mapping in JSON: +\r
-----\r
-{\r
- "user": "$username",\r
- "realm": "$domain"\r
-}\r
-----\r
-The assertion in JSON: +\r
-----\r
-{\r
- "Principal": "bob@example.com"\r
-}\r
-----\r
-The rule applied: +\r
-----\r
-[\r
- [\r
- ["in", "Principal", "assertion"],\r
- ["exit", "rule_fails", "if_not_success"],\r
- ["regexp", "$assertion[Principal]", (?P<username>\\w+)@(?P<domain>.+)"],\r
- ["set", "$username", "$regexp_map[username]"],\r
- ["set", "$domain", "$regexp_map[domain]"],\r
- ["exit, "rule_succeeds", "always"]\r
- ]\r
-]\r
-----\r
-The mapped result in JSON: +\r
-----\r
-{\r
- "user": "bob",\r
- "realm": "example.com"\r
-}\r
-----\r
-Also, users may be granted roles based on their membership in certain groups.\r
-\r
-The Authentication Service allows white lists for users with specific roles. The white lists ensure that users are unconditionally accepted and authorized with specific roles. Users who must be unconditionally denied access can be placed in a black list.\r
-\r
-=== Actors in ODL Authentication Service\r
-*ODL Controller administrator* +\r
-The ODL Controller administrator has the following responsibilities:\r
-\r
-* Authors Authentication policies using the REST API\r
-* Provides credentials, usernames and passwords to users who request them\r
-\r
-*ODL resource owners* +\r
-Resource owners authenticate (either by means of federation or directly providing their own credentials to the controller) to obtain an access token. This access token can then be used to access resources on the controller.\r
-An ODL resource owner enjoys the following privileges:\r
-\r
-* Creates, refreshes, or deletes access tokens\r
-* Gets access tokens from the Secure Token Service\r
-* Passes secure tokens to resource users\r
-\r
-*ODL resource users* +\r
-Resource users do not need to authenticate: they can access resources if they are given an access tokens by the resource owner. The default timeout for access tokens is 1 hour (This duration is configurable.).\r
-An ODL resource user does the following:\r
-\r
-* Gets access tokens either from a resource owner or the controller administrator\r
-* Uses tokens at access applications from the north-bound APIs\r
-\r
-=== Sub-components of ODL Authentication Service\r
-AuthX authoring service:: Provides AuthN and AuthZ Authoring service\r
-Light-weight Identity Manager (IdmLight):: Stores local user authentication and authorization data, and roles +\r
-Provides an Admin REST API for CRUD users/roles/domains\r
-Pluggable authenticators:: Provides domain-specific authentication mechanisms\r
-Authenticator:: Authenticates users against the authentication policy and establishes claims\r
-Authentication Cache:: Caches all authentication states and tokens\r
-Authentication Filter:: Verifies tokens and extracts claims\r
-Authentication Manager:: Contains the session token and authentication claim store\r
-\r
-==== ODL Authorization Service\r
-In progress is the addition of an authorization feature to the authentication service. Authorization will follow successful authentication. Modelled on the Role Based Access Control (RBAC) approach for authentication, the Authorization service will assign roles that define permissions and decide access levels.\r
-Authorization will do the following:\r
-\r
-* Verify the operations the user or service is authorized to do\r
-* Enforce policies to grant or deny access to resources\r
+++ /dev/null
-== Controller
-
-=== OpenDaylight Controller: MD-SAL Developers' Guide
-
-Model-Driven SAL (MD-SAL) is a set of infrastructure services aimed at providing common and generic support to application and plugin developers.
-
-MD-SAL currently provides infrastructure services for the following:
-
-* Data Services
-* RPC or Service routing
-* Notification subscription and publish services
-
-This model-driven infrastructure allows developers to develop applications and plugins against an API type of their choice (Java generated APIs, DOM APIs, REST APIs). The infrastructure automatically provides the other API types.
-The modelling language of choice for MD-SAL is YANG, which is an IETF standard, for modelling network element configuration. The YANGTools project and its development tools provide support for YANG.
-
-
-=== API types
-
-MD-SAL provides three API types: +
-
-* Java generated APIs for consumers and producers
-* DOM APIs: Mostly used by infrastucture components and usuful for XML-driven plugin and application types
-* REST APIs: https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf[Restconf] that is available to consumer type applications and provides access to RPC and data stores
-
-
-=== Basic YANG concepts and their rendition in APIs
-
-The following are the basic concepts in YANG modeling: +
-
-* Remote Procedure (RPCs): In MD-SAL, RPCs are used for any call or invocation that crosses the plugin or module boundaries. RPCs are triggered by consumers, and usually have return values.
-* Notifications: Asynchronous events, published by components for listeners.
-* Configuration and Operational Data tree: The well-defined (by model) tree structure that represents the operational state of components and systems.
-** Instance Identifier: The path that uniquely identifies the sub-tree in the configuration or operational space. Most of the addressing of data is done by Instance Identifier.
-
-==== RPC
-In YANG, Remote Procedure Calls (RPCs) are used to model any procedure call implemented by a Provider (Server), which exposes functionality to Consumers (Clients).
-
-In MD-SAL terminology, the term 'RPC' is used to define the input and output for a procedure (function) that is to be provided by a Provider, and adapted by the MD-SAL.
-
-In the context of the MD-SAL, there are three types of RPCs (RPC services): +
-
-* Global: One service instance (implementation) per controller container or mount point
-* Routed: Multiple service instances (implementations) per controller container or mount point
-
-==== Global service
-
-* There is only one instance of a Global Service per controller instance. (Note that a controller instance can consist of a cluster of controller nodes.)
-
-*Routing* +
-
-* Binding-Aware MD-SAL (sal-binding)
-** **Rpc Type**: Identified by a generated RpcService class and a name of a method invoked on that interface
-* Binding-Independent MD-SAL (sal-dom)
-** **Rpc Type**: Identified by a QName
-
-==== Routed service ====
-
-* There can be multiple instances (implementations) of a service per controller instance
-* Can be used for southbound plugins or for horizontal scaling (load-balancing) of northbound plugins (services)
-
-*Routing* +
-
-Routing is done based on the contents of a message, for example, 'Node Reference'. The field in a message that is used for routing is specified in a YANG model by using the routing-reference statement from the yang-ext model. +
-
-* Binding Aware MD-SAL (sal-binding)
-* RPC Type: Identified by an RpcService subclass and the name of the method invoked on that interface
-* Instance Identifier: In a data tree, identifies the element instance that will be used as the route target.
-The used class is: +
-----
-org.opendaylight.yang.binding.InstanceIdentifier
-----
-
-The Instance Identifier is learned from the message payload and from the model. +
-
-* Binding Independent MD-SAL (sal-dom)
-* RPC Type: Identified by a QName
-
-* Instance Identifier: In a data tree, identifies the element instance that will be used as the route target. The used class is: +
-----
-org.opendaylight.yang.data.api.InstanceIdentifier
-----
-RPCs in various API types: +
-
-* Java Generated APIs: For each model there is *Service interface. See https://wiki.opendaylight.org/view/YANG_Tools:YANG_to_Java_Mapping#Rpc[YANG Tools: Yang to Java mapping-RPC] to understand how YANG statements maps to Service interface.
-** Providers expose their implementation of *Service by registering their implementation to RpcProviderRegistry.
-** Consumers get the *Service implementation from RpcConsumerRegistry. If the implementer uses a different API type, MD-SAL automatically translates data in the background.
-* DOM APIs: RPCs are identified by QName.
-** Providers expose their implementation of RPC identified by QName registering their RpcImplementation to RpcProvisionRegistry.
-** Consumers get the *Service implementation from RpcConsumerRegistry. If the implementer uses different API type, MD-SAL automatically translates data in the background.
-* REST APIs: RPCs are identified by the model name and their name.
-* Consumers invoke RPCs by invoking POST operation to /restconf/operations/model-name:rpc-name.
-
-==== Notification
-In YANG, Notifications represent asynchronous events, published by providers for listeners.
-
-RPCs in various API types: +
-
-* Java Generated APIs: For each model, there is *Listener interface and transfer object for each notification. See https://wiki.opendaylight.org/view/YANG_Tools:YANG_to_Java_Mapping#Notification[YANG Tools: Yang to Java mapping-Notification] to understand how YANG statements map to the Notifications interface.
-** Providers publish notifications by invoking the publish method on NotificationPublishService.
-** To receive notifications, consumers register their implementation of *Listener to NotificationBrokerService. If the notification publisher uses a different API type, MD-SAL automatically translates data in the background.
-* DOM APIs: Notifications are represented only by XML Payload.
-** Providers publish notifications by invoking the publish method on NotificationPublishService.
-** To receive notifications, consumers register their implementation of *Listener to NotificationBrokerService. If the notification publisher uses a different API type, MD-SAL automatically translates data in the background.
-* REST APIs: Notifications are currently not supported.
-
-==== Instance Identifier
-
-The Instance Identifier is the unique identifier of an element (location) in the yang data tree: basically, it is the *path* to the node that uniquely identifies all the parent nodes of the node. The unique identification of list elements requires the specification of key values as well.
-
-MD-SAL currently provides three different APIs to access data in the common data store: +
-
-* Binding APIs (Java generated DTOs)
-* DOM APIs
-* https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf[OpenDaylight Controller:MD-SAL Restconf APIs]
-
-*Example* +
-
-Consider the following simple YANG model for inventory: +
-----
-module inventory {
- namespace "urn:opendaylight:inventory";
- prefix inv;
- revision "2013-06-07";
- container nodes {
- list node {
- key "id";
- leaf "id" {
- type "string";
- }
- }
- }
-}
-----
-*An example having one instance of node with the name _foo_* +
-
-Let us assume that we want to create an instance identifier for the node foo in the following bindings or formats: +
-
-
-* **YANG / XML / XPath version**
-----
-/inv:nodes/inv:node[id="foo"]
-----
-* **Binding-Aware version (generated APIs)**
-----
-import org.opendaylight.yang.gen.urn.opendaylight.inventory.rev130607.Nodes;
-import org.opendaylight.yang.gen.urn.opendaylight.inventory.rev130607.nodes.Node;
-import org.opendaylight.yang.gen.urn.opendaylight.inventory.rev130607.nodes.NodeKey;
-
-import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
-
-InstanceIdentifier<Node> identifier = InstanceIdentifier.builder(Nodes.class).child(Node.class,new NodeKey("foo")).toInstance();
-----
-NOTE: The last call, _toInstance()_ does not return an instance of the node, but the Java version of Instance identifier which uniquely identifies the node *foo*.
-
-* **HTTP Restconf APIs** +
-----
-http://localhost:8080/restconf/config/inventory:nodes/node/foo
-----
-NOTE: We assume that HTTP APIs are exposed on localhost, port 8080.
-
-* **Binding Independent version (yang-data-api)**
-----
-import org.opendaylight.yang.common.QName;
-import org.opendaylight.yang.data.api.InstanceIdentifier;
-
-QName nodes = QName.create("urn:opendaylight:inventory","2013-06-07","nodes");
-QName node = QName.create(nodes,"nodes");
-QName idName = QName.create(nodes,"id");
-InstanceIdentifier = InstanceIdentifier.builder()
- .node(nodes)
- .nodeWithKey(node,idName,"foo")
- .toInstance();
-----
-NOTE: The last call, _toInstance()_ does not return an instance of node, but the Java version of Instance identifier which uniquely identifies the node *foo*.
-
-=== MD-SAL: Plugin types
-MD-SAL has four component-types that differ in complexity, expose different models, and use different subsets of the MD-SAL functionality.
-
-* Southbound Protocol Plugin: Responsible for handling multiple sessions to the southbound network devices and providing common abstracted interface to access various type of functionality provided by these network devices
-* Manager-type application: Responsible for managing the state and the configuration of a particular functionality which is exposed by southbound protocol plugins
-* Protocol Library: Responsible for handling serialization or de-serialization between the wire protocol format and the Java form of the protocol
-* Connector Plugin: Responsible for connecting consumers (and providers) to Model-driven SAL (and other components) by means of different wire protocol or set of APIs
-
-==== Southbound protocol plugin
-
-The responsibilities of the Southbound Protocol plugin include the following :
-
-* Handling multiple sessions to southbound network devices
-* Providing a common abstracted interface to access various type of functionality provided by the network devices
-
-The Southbound Protocol Plugin should be stateless. The only preserved state (which is still transient) is the list of connected devices or sessions. Models mostly use RPCs and Notifications to describe plugin functionality
-Example plugins: Openflow Southbound Plugin, Netconf Southbound Plugin, BGP Southbound Plugin, and PCEP Southbound Plugin.
-
-==== Manager-type application
-
-The responsibilities of the Manager-type applications include the following:
-
-* Providing configuration-like functionality to set or modify the behaviour of network elements or southbound plugins
-* Coordinating flows and provide higher logic on top of stateless southbound plugins
-
-Manager-type Applications preserve state. Models mostly use Configuration Data and Runtime Data to describe component functionality.
-
-=== Protocol library
-The OpenFlow Protocol Library is a component in OpenDaylight, that mediates communication between the OpenDaylight controller and the hardware devices supporting the OpenFlow protocol. The primary goal of the library is to provide user (or upper layers of OpenDaylight) communication channel, that can be used for managing network hardware devices.
-
-=== MD-SAL: Southbound plugin development guide
-The southbound controller plugin is a functional component.
-
-The plugin: +
-
-* Provides an abstraction of network devices functionality
-* Normalizes their APIs to common contracts
-* Handles session and connections to them
-
-The plugin development process generally moves through the following phases: +
-
-. Definition of YANG models (API contracts): For Model-Driven SAL, the API contracts are defined by YANG models and the Java interfaces generated for these models. A developers opts for one of the following: +
-** Selects from existing models
-** Creates new models
-** Augments (extends) existing models
-[start=2]
-. Code Generation: The Java Interfaces, implementation of Transfer Objects, and mapping to Binding-Independent form is generated for the plugin. This phase requires the proper configuration of the Maven build and YANG Maven Tools.
-. Implementation of plugin: The actual implementation of the plugin functionality and plugin components.
-
-NOTE: The order of steps is not definitive, and it is up to the developer to find the most suitable workflow. For additional information, see <<_best_practices>>.
-
-=== Definition of YANG models
-
-In this phase, the developer selects from existing models (provided by controller or other plugins), writes new models, or augments existing ones. A partial list of available models could be found at:
-https://wiki.opendaylight.org/view/YANG_Tools:Available_Models[YANG Tools:Available Models].
-
-The mapping of YANG to Java is documented at: https://wiki.opendaylight.org/view/Yang_Tools:YANG_to_Java_Mapping[Yang Tools:YANG to Java Mapping.] This mapping provides an overview of how YANG is mapped to Java.
-
-Multiple approaches to model the functionality of the southbound plugin are available: +
-
-* Using RPCs and Notifications
-* Using Configuration Data Description
-* Using Runtime Data Description
-* Combining approaches
-
-=== RPCs
-
-RPCs can model the functionality invoked by consumers (applications) that use the southbound plugin. Although RPCs can model any functionality, they are usually used to model functionality that cannot be abstracted as configuration data, for example, PacketOut, or initiating a new session to a device (controller-to-device session).
-
-RPCs are modeled with an RPC statement in the following form: +
-+rpc foo {}+ +
-This statement is mapped to method. +
-
-*RPC input* +
-To define RPC input, use an input statement inside RPC. The structure of the input is defined with the same statements as the structure of notifications, configuration, and so on.
-----
- rpc foo {
- input {
- ...
- }
- }
-----
-*RPC output* +
-To define the RPC output (structure of result), use the RPC output statement. +
-----
- rpc foo {
- output {
- ...
- }
- }
-----
-*Notifications* +
-Use notifications to model events originating in a network device or southbound plugin which is exposed to consumers to listen.
-
-
-A notification statement defines a notification:
-----
- notification foo {
- ...
- }
-----
-*Configuration data* +
-
-Configuration data is good for the following purposes: +
-
-* Model or provide CRUD access to the state of protocol plugin and/or network devices
-* Model any functionality which could be exposed as a configuration to the consumers or applications
-
-Configuration data in YANG is defined by using the config substatement with a true argument. For example: +
-----
- container foo {
- config true;
- ...
- }
-----
-*Runtime (read-only) data* +
-Runtime (read-only) data is good to model or provide read access to the state of the protocol plugin and networtk devices, or network devices. This type of data is good to model statistics or any state data, which cannot be modified by the consumers (applications), but needs exposure (for example, learned topology, or list of connected switches).
-
-Runtime data in YANG is defined by using config subsatement with a false argument:
-----
- container foo {
- config false;
- }
-----
-*Structural elements* +
-The structure of RPCs, notifications, configuration data, and runtime data is modelled using structural elements (data schema nodes). Structural elements define the actual structure of XML, DataDOM documents, and Java APIs for accessing or storing these elements. The most commonly used structural elements are: +
-
-* Container
-* List
-* Leaf
-* Leaf-list
-* Choice
-
-=== Augmentations +
-Augmentations are used to extend existing models by providing additional structural elements and semantics. Augmentation cannot change the mandatory status of nodes in the original model, or introduce any new mandatory statements.
-
-=== Best practices
-
-* YANG models must be located under the src/main/yang folder in your project.
-* Design your models so that they are reusable and extendible by third-parties.
-* Always try to reuse existing models and types provided by these models. See https://wiki.opendaylight.org/view/YANG_Tools:Available_Models[YANG Tools:Available Models] or others if there is no model which provides you with data structures and types you need.
-
-*Code generation* +
-To configure your project for code generation, your build system needs to use Maven. For the configuration of java API generation, see https://wiki.opendaylight.org/view/Yang_Tools:Maven_Plugin_Guide[Yang Tools:Maven Plugin Guide].
-
-*Artefacts generated at compile time* +
-The following artefacts are generated at compile time: +
-
-* Service interfaces
-* Transfer object interfaces
-* Builders for transfer objects and immutable versions of transfer objects
-
-=== Implementation +
-This step uses generated artefacts to implement the intended functionality of the southbound plugin. +
-
-*Provider implementation* +
-To expose functionality through binding-awareness, the MD-SAL plugin needs to be compiled against these APIs, and must at least implement the BindingAwareProvider interface.
-The provider uses APIs which are available in the SAL-binding-api Maven artifact. To use this dependency, insert the following dependency into your pom.xml:
-----
-<dependency>
- <groupId>org.opendaylight.controller</groupId>
- <artifactId>sal-binding-api</artifactId>
- <version>1.0-SNAPSHOT</version>
- </dependency>
-----
-
-*BindingAwareProvider implementation* +
-A BindingAwareProvider interface requires the implementation of four methods, and registering an instance with BindingAwareBroker. Use AbstractBindingAwareProvider to simplify the implementation.
-
-* void onSessionInitialized(ConsumerContext ctx): This callback is called when Binding-Aware Provider is initialized and ConsumerContext is injected into it. ConsumerContext serves to access all functionality which the plugin is to consume from other controller components.
-* void onSessionInitialized(ProviderContext ctx): This callback is called when Binding-Aware Provider is initialized and ProviderContext is injected into it. ProviderContext serves to access all functionality which the plugin could use to provide its functionality to controller components.
-* Collection<? extends RpcService> getImplementations(): Shorthand registration of an already instantiated implementations of global RPC services. Automated registration is currently not supported.
-* public Collection<? extends ProviderFunctionality> getFunctionality(): Shorthand registration of an already instantiated implementations of ProviderFunctionality. Automated registration is currently not supported.
-NOTE: You also need to set your implementation of AbstractBindingAwareProvider set as Bundle Activator for MD-SAL to properly load it.
-
-=== Notifications
-To publish events, request an instance of NotificationProviderService from ProviderContext. Use the following:
-----
- ExampleNotification notification = (new ExampleNotificationBuilder()).build();
- NotificationProviderService notificationProvider = providerContext.getSALService(NotificationProviderService.class);
- notificationProvider.notify(notification);
-----
-*RPC implementations* +
-To implement the functionality exposed as RPCs, implement the generated RpcService interface. Register the implementation within ProviderContext included in the provider.
-
-If the generated RpcInterface is FooService, and the implementation is FooServiceImpl:
-----
- @Override
- public void onSessionInitiated(ProviderContext context) {
- context.addRpcImplementation(FooService.class, new FooServiceImpl());
- }
-----
-=== Best practices
-
-RPC Service interface contract requires you to return http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html[Future object] (to make it obvious that call may be asynchronous), but it is not specified how this Future is implemented. Consider using existing implementations provided by JDK or Google Guava. Implement your own Future only if necessary.
-
-Consider using http://docs.guava-libraries.googlecode.com/git-history/release/javadoc/com/google/common/util/concurrent/SettableFuture.html[SettableFuture] if you intend not to use http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/FutureTask.html[FutureTask] or submit http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Callable.html[Callables] to http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ExecutorService.html[ExecutorService].
-
-IMPORTANT: Do not implement transfer object interfaces unless necessary. Choose already generated builders and immutable versions. If you want to implement transfer objects, ensure that instances exposed outside the plugin are immutable.
-
-=== OpenDaylight Controller: MD-SAL FAQs
-
-*Q-1: What is the overall MD-SAL architecture?*
-
-* **What is the overall architecture, components, and functionality?**
-* **Who supplies which components, and how are the components plumbed?**
-
-*A-1:* The overall Model-Driven SAL (MD-SAL) architecture did not really change from the API-Driven SAL (AD-SAL). As with the AD-SAL, plugins can be data providers, or data consumers, or both (although the AD-SAL did not explicitly name them as such). Just like the AD-SAL, the MD-SAL connects data consumers to appropriate data providers and (optionally) facilitates data adaptation between them.
-
-Now, in the AD-SAL, the SAL APIs request routing between consumers and providers, and data adaptations are all statically defined at compile or build time. In the MD-SAL, the SAL APIs and request routing between consumers and providers are defined from models, and data adaptations are provided by 'internal' adaptation plugins. The API code is generated from models when a plugin is compiled. When the plugin OSGI bundle is loaded into the controller, the API code is loaded into the controller along with the rest of the plugin containing the model.
-
-.AD-SAL and MD-SAL
-image::MD-SAL.png[]
-
-The AD-SAL provides request routing (selects an SB plugin based on service type) and optionally provides service adaptation, if an NB (Service, abstract) API is different from its corresponding SB (protocol) API. For example, in the above figure, the AD-SAL routes requests from NB-Plugin 1 to SB Plugins 1 and 2. Note that the plugin SB and NB APIs in this example are essentially the same (although both of them need to be defined). Request routing is based on plugin type: the SAL knows which node instance is served by which plugin. When an NB Plugin requests an operation on a given node, the request is routed to the appropriate plugin which then routes the request to the appropriate node. The AD-SAL can also provide service abstractions and adaptations. For example, in the above figure, NB Plugin 2 is using an abstract API to access the services provided by SB Plugins 1 and 2. The translation between the SB Plugin API and the abstract NB API is done in the Abstraction module in the AD-SAL.
-
-The MD-SAL provides request routing and the infrastructure to support service adaptation. However, it does not provide service adaptation itself: service adaptation is provided by plugins. From the point of view of MD-SAL, the Adaptation Plugin is a regular plugin. It provides data to the SAL, and consumes data from the SAL through APIs generated from models. An Adaptation Plugin basically performs model-to-model translations between two APIs. Request Routing in the MD-SAL is done on both protocol type and node instances, since node instance data is exported from the plugin into the SAL (the model data contains routing information).
-
-The simplest MD-SAL APIs generated from models (RPCs and Notifications, both supported in the yang modeling language) are functionally equivalent to AD-SAL function call APIs. Additionally, the MD-SAL can store data for models defined by plugins. Provider and consumer plugins can exchange data through the MD-SAL storage. Data in the MD-SAL is accessed through getter and setter APIs generated from models. Note that this is in contrast to the AD-SAL, which is stateless.
-
-Note that in the above figure, both NB AD-SAL Plugins provide REST APIs to controller client applications.
-
-The functionality provided by the MD-SAL is basically to facilitate the plumbing between providers and consumers. A provider or a consumer can register itself with the MD-SAL. A consumer can find a provider that it is interested in. A provider can generate notifications; a consumer can receive notifications and issue RPCs to get data from providers. A provider can insert data into SAL storage; a consumer can read data from SAL storage.
-
-Note that the structure of SAL APIs is different in the MD-SAL from that in the AD-SAL. The AD-SAL typically has both NB and SB APIs even for functions or services that are mapped 1:1 between SB Plugins and NB Plugins. For example, in the current AD-SAL implementation of the OpenFlow Plugin and applications, the NB SAL APIs used by OF applications are mapped 1:1 onto SB OF Plugin APIs. The MD-SAL allows both the NB plugins and SB plugins to use the same API generated from a model. One plugin becomes an API (service) provider; the other becomes an API (service) Consumer. This eliminates the need to define two different APIs and to provide three different implementations even for cases where APIs are mapped to each other 1:1. The MD SAL provides instance-based request routing between multiple provider plugins.
-
-*Q-2: What functionality does the MD-SAL assume? For example, does the SAL assume that the network model is a part of the SAL?*
-
-*A-2:* The MD-SAL does not assume any model. All models are provided by plugins. The MD-SAL only provides the infrastructure and the plumbing for the plugins.
-
-
-*Q-3: What is the "day in the life" of an MD-SAL plugin?*
-
-
-*A-3:* All plugins (protocol, application, adaptation, and others) have the same lifecycle. The life of a plugin has two distinct phases: design and operation. +
-During the design phase, the plugin designer performs the following actions: +
-
-* The designer decides which data will be consumed by the plugin, and imports the SAL APIs generated from the API provider’s models. Note that the topology model is just one possible data type that may be consumed by a plugin. The list of currently available data models and their APIs can be found in YANG_Tools:Available_Models.
-* The designer decides which data and how it will be provided by the plugin, and designs the data model for the provided data. The data model (expressed in yang) is then run through the https://wiki.opendaylight.org/view/YANG_Tools:Available_Models[YANG Tools], which generate the SAL APIs for the model.
-* The implementations for the generated consumer and provider APIs, along with other plugin features and functionality, are developed. The resulting code is packaged in a “plugin” OSGI bundle. Note that a developer may package the code of a subsystem in multiple plugins or applications that may communicate with each other through the SAL.
-* The generated APIs and a set of helper classes are also built and packaged in an “API” OSGI bundle.
-
-The plugin development process is shown in the following figure. +
-
-.Plugin development process
-image::plugin-dev-process.png[]
-
-When the OSGI bundle of a plugin is loaded into the controller and activated, the operation phase begins. The plugin operation is probably best explained with a few examples describing the operation of the OF Protocol plugin and OF applications, such as the Flow Programmer Service, the ARP Handler, or the Topology Manager. The following figure shows a scenario where a “Flow Deleted” notification from a switch arrives at the controller.
-
-.Flow deleted at controller
-image::flow-deleted-at-controller.png[]
-
-The scenario is as follows: +
-
-. The Flow Programmer Service registers with the MD SAL for the `Flow Deleted' notification. This is done when the Controller and its plugins or applications are started.
-. A `Flow Deleted' OF packet arrives at the controller. The OF Library receives the packet on the TCP/TLS connection to the sending switch, and passes it to the OF Plugin.
-. The OF Plugin parses the packet, and uses the parsed data to create a `Flow Deleted' SAL notification. The notification is actually an immutable `Flow Deleted' Data Transfer Object (DTO) that is created or populated by means of methods from the model-generated OF Plugin API.
-. The OF Plugin sends the `Flow Deleted' SAL notification (containing the notification DTO) into the SAL. The SAL routes the notification to registered consumers, in this case, the Flow Programmer Service.
-. The Flow Programmer Service receives the notification containing the notification DTO.
-. The Flow Programmer Service uses methods from the API of the model-generated OF Plugin to get data from the immutable notification DTO received in Step 5. The processing is the same as in the AD-SAL.
-
-Note that other packet-in scenarios, where a switch punts a packet to the controller, such as an ARP or an LLDP packet, are similar. Interested applications register for the respective notifications. The OF plugin generates the notification from received OF packets, and sends them to the SAL. The SAL routes the notifications to the registered recipients. +
-The following figure shows a scenario where an external application adds a flow by means of the NB REST API of the controller.
-
-.External app adds flow
-image::md-sal-faqs-add_flow.png[]
-
-The scenario is as follows: +
-
-. Registrations are performed when the Controller and its plugins or applications are started.
-
-.. The Flow Programmer Service registers with the MD SAL for Flow configuration data notifications.
-.. The OF Plugin registers (among others) the ‘AddFlow’ RPC implementation with the SAL.
-Note that the RPC is defined in the OF Plugin model, and the API is generated during build time. +
-[start=2]
-. A client application requests a flow add through the REST API of the Controller. (Note that in the AD-SAL, there is a dedicated NB REST API on top of the Flow Programming Service. The MD-SAL provides a common infrastructure where data and functions defined in models can be accessed by means of a common REST API. For more information, see http://datatracker.ietf.org/doc/draft-bierman-netconf-restconf/). The client application provides all parameters for the flow in the REST call.
-. Data from the ‘Add Flow’ request is deserialized, and a new flow is created in the Flow Service configuration data tree. (Note that in this example the configuration and operational data trees are separated; this may be different for other services). Note also that the REST call returns success to the caller as soon as the flow data is written to the configuration data tree.
-. Since the Flow Programmer Service is registered to receive notifications for data changes in the Flow Service data tree, the MD-SAL generates a ‘data changed’ notification to the Flow Programmer Service.
-. The Flow Programmer Service reads the newly added flow, and performs a flow add operation (which is basically the same as in the AD-SAL).
-. At some point during the flow addition operation, the Flow Programmer Service needs to tell the OF Plugin to add the flow in the appropriate switch. The Flow Programmer Service uses the OF Plugin generated API to create the RPC input parameter DTO for the “AddFlow” RPC of the OF Plugin.
-. The Flow Programmer Service gets the service instance (actually, a proxy), and invokes the “AddFlow” RPC on the service. The MD-SAL will route the request to the appropriate OF Plugin (which implements the requested RPC).
-. The `AddFlow' RPC request is routed to the OF Plugin, and the implementation method of the “AddFlow” RPC is invoked.
-. The `AddFlow' RPC implementation uses the OF Plugin API to read values from the DTO of the RPC input parameter. (Note that the implementation will use the getter methods of the DTO generated from the yang model of the RPC to read the values from the received DTO.)
-. The `AddFlow' RPC is further processed (pretty much the same as in the AD-SAL) and at some point, the corresponding flowmod is sent to the corresponding switch.
-
-*Q-4: Is there a document that describes how code is generated from the models for the MD-SAL?*
-
-*A-4:* https://wiki.opendaylight.org/view/YANG_Tools:YANG_to_Java_Mapping[Yangtools] documents the Yang to Java generation, including examples of how the yang constructs are mapped into Java classes. You can write unit tests against the generated code. You will have to write implementations of the generated RPC interfaces. The generated code is just Java, and it debugs just like Java.
-
-If you want to play with generating Java from Yang there is a maven archetype to help you get going: https://wiki.opendaylight.org/view/Maven_Archetypes:odl-model-project[Maven Archetypes: ODL Model Project]. +
-Or, you can try creating a project in Eclipse as explained at: http://sdntutorials.com/yang-to-java-conversion-how-to-create-maven-project-in-eclipse/[YANG to Java conversion: How to create Maven project in Eclipse].
-
-*Q-5: The code generation tools mention 'producers' and consumers'. How are these related to 'southbound' and 'northbound SAL plugins?*
-
-*A-5:* The difference between southbound and northbound plugins is that the southbound plugins talk protocols to network nodes, and northbound plugins talk application APIs to the controller applications. As far as the SAL is concerned, there is really no north or south. The SAL is basically a data exchange and adaptation mechanism between plugins. The plugin SAL roles (consumer or producer) are defined with respect to the data being moved around or stored by the SAL. A producer implements an API, and provides the data of the API: a consumer uses the API, and consumes the data of the API. +
-While 'northbound' and 'southbound' provide a network engineer's view of the SAL, 'consumer' and 'producer' provide a software engineer's view of the SAL, and is shown in the following figure:
-
-.SAL consumer and producer view
-
-image::mdsal-sal-sw-eng.png[]
-
-*Q-6: Where can I find models that have already been defined in OpenDaylight?*
-
-*A-6:* The list of models that have been defined for the SAL and in various plugins can be found in https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Model_Reference[MD-SAL Model Reference].
-
-*Q-7: How do I migrate my existing plugins and services to MD-SAL?*
-
-*A-7:* The migration guide can be found in the https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Application_Migration_Guide[MD-SAL Application Migration Guide].
-
-*Q-8: Where can I find SAL example code?*
-
-*A-8:* The toaster sample provides a simple yet complete example of a model, a service provider (toaster), and a service consumer. It provides the model of a programmable toaster, a sample consumer application that uses MD-SAL APIs; a sample southbound plugin (a service provider) that implements toaster; and a unit test suite.
-
-The toaster example is in _controller.git_ under _opendaylight/md-sal/samples_.
-
-*Q-9: Where is the REST API code for the example?*
-
-*A-9:* The REST APIs are derived from models. You do not have to write any code for it. The controller will implement the http://datatracker.ietf.org/doc/draft-bierman-netconf-restconf/[RESTCONF protocol] which defines access to yang-formatted data through REST. Basically, all you need to do is define your service in a model, and expose that model to the SAL. REST access to your modeled data will then be provided by the SAL infrastructure. However, if you want to, you can create your own REST API (for example, to be compliant with an existing API).
-
-*Q-10: How can one use RESTCONF to access the MD-SAL datastore?*
-
-*A-10:* For information on accessing the MD-SAL datastore, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf[MD-SAL Restconf].
-
-=== OpenDaylight Controller Configuration: Java Code Generator
-
-==== YANG to Java code generator
-
-The Java code for the configuration system is generated by the yang-maven-plugin and the yang-jmx-generator-plugin.
-The input Yang module files are converted to java files by the definition of the module and the specified templates. the generated java code can represent interfaces, classes, or abstract classes used for configuration.
-
-=== Service interfaces generating
-
-Service interfaces (SI) are generated from YANG "service-types". Each SI must be defined as "identity" with a "base" statement set to "config:service-type", or another SI. This is because a service must have a globally unique name.
- Each SI must be annotated with @ServiceInterfaceAnnotation, and must extend AbstractServiceInterface.
-
-*Sample YANG module representing service interface* +
-
-----
-module config-test {
- yang-version 1;
- namespace "urn:opendaylight:params:xml:ns:yang:controller:test";
- prefix "test";
-
- import config { prefix config; revision-date 2013-04-05; }
-
- description
- "Testing API";
-
- revision "2013-06-13" {
- description
- "Initial revision";
- }
-
- identity testing {
- description
- "Test api";
-
- base "config:service-type";
- config:java-class "java.lang.AutoCloseable";
- }
-}
-----
-The "description" node of identity is generated as javadoc in the service interface. +
-The "config:java-class" is generated as *ServiceInterfaceAnnotation*. It specifies java classes or interfaces in the "osgiRegistrationTypes" parameter. The module implementing this service interface must instantiate a java object that can be cast to any of the java types defined in "osgiRegistrationTypes".
-
-*Generated java source file: AutoCloseableServiceInterface* +
-----
-package %prefix%.test;
-
-/**
-* Test api
-*/
-@org.opendaylight.controller.config.api.annotations.Description(value = "Test api")
-@org.opendaylight.controller.config.api.annotations.ServiceInterfaceAnnotation(value = "testing", osgiRegistrationType = java.lang.AutoCloseable.class)
-public interface AutoCloseableServiceInterface extends org.opendaylight.controller.config.api.annotations.AbstractServiceInterface
-{
-
-}
-----
-
-==== Module stubs generating
-
-Modules are constructed during configuration transaction. A module implements the ModuleMXBean interface. The ModuleMXBean interface represents getters and setters for attributes that will be exposed to the configuration registry by means of JMX. Attributes can either be simple types, or composite types.
-
-Each ModuleMXBean must be defined in yang as "identity" with the base statement set to "config:module-type". Not only are ModuleMXBeans generated, but also ModuleFactory and Module stubs. Both are first generated as abstract classes with almost full functionality. Then their implementations, which are allowed to be modified by users, are generated, but only once.
-
-=== Runtime beans generating
-
-Runtime JMX beans are purposed to be the auditors: they capture data about running module instances. A module can have zero or more runtime beans. Runtime beans are hierarchically ordered, and each must be uniquely identified.
- A runtime bean is defined as a configuration augment of a module, from which interface RuntimeMXBean, RuntimeRegistrator, and RuntimeRegistretion are generated. Augment definition contains arguments representing the data of a module that must be watched.
-
-==== RPCs
-
-Method calls in yang must be specified as top level elements. The context, where an RPC operation exits, must be defined in the RPC definition itself, and in the runtime bean that provides method implementation.
-
-=== OpenDaylight Controller MD-SAL: Restconf
-
-==== Restconf operations overview
-
-Restconf allows access to datastores in the controller. +
-There are two datastores: +
-
-* Config: Contains data inserted via controller
-* Operational: Contains other data
-
-NOTE: Each request must start with the URI /restconf. +
-Restconf listens on port 8080 for HTTP requests.
-
-Restconf supports *OPTIONS*, *GET*, *PUT*, *POST*, and *DELETE* operations. Request and response data can either be in the XML or JSON format. XML structures according to yang are defined at: http://tools.ietf.org/html/rfc6020[XML-YANG]. JSON structures are defined at: http://tools.ietf.org/html/draft-lhotka-netmod-yang-json-02[JSON-YANG]. Data in the request must have a correctly set *Content-Type* field in the http header with the allowed value of the media type. The media type of the requested data has to be set in the *Accept* field. Get the media types for each resource by calling the OPTIONS operation.
-Most of the paths of the pathsRestconf endpoints use https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Concepts#Instance_Identifier[Instance Identifier]. +<identifier>+ is used in the explanation of the operations.
-
-*<identifier>* +
-
-* It must start with <moduleName>:<nodeName> where <moduleName> is a name of the module and <nodeName> is the name of a node in the module. It is sufficient to just use <nodeName> after <moduleName>:<nodeName>. Each <nodeName> has to be separated by /.
-* <nodeName> can represent a data node which is a list or container yang built-in type. If the data node is a list, there must be defined keys of the list behind the data node name for example, <nodeName>/<valueOfKey1>/<valueOfKey2>.
-* The format <moduleName>:<nodeName> has to be used in this case as well: +
-Module A has node A1. Module B augments node A1 by adding node X. Module C augments node A1 by adding node X. For clarity, it has to be known which node is X (for example: C:X).
-For more details about encoding, see: http://tools.ietf.org/html/draft-bierman-netconf-restconf-02#section-5.3.1[Restconf 02 - Encoding YANG Instance Identifiers in the Request URI.]
-
-=== Mount point
-A Node can be behind a mount point. In this case, the URI has to be in format <identifier>/*yang-ext:mount*/<identifier>. The first <identifier> is the path to a mount point and the second <identifier> is the path to a node behind the mount point. A URI can end in a mount point itself by using <identifier>/*yang-ext:mount*. +
-More information on how to actually use mountpoints is available at: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf[ OpenDaylight Controller:Config:Examples:Netconf].
-
-==== HTTP methods
-
-===== OPTIONS /restconf +
-
-* Returns the XML description of the resources with the required request and response media types in Web Application Description Language (WADL)
-
-===== GET /restconf/config/<identifier> +
-
-* Returns a data node from the Config datastore.
-* <identifier> points to a data node which must be retrieved.
-
-===== GET /restconf/operational/<identifier> +
-
-* Returns the value of the data node from the Operational datastore.
-* <identifier> points to a data node which must be retrieved.
-
-===== PUT /restconf/config/<identifier>
-
-* Updates or creates data in the Config datastore and returns the state about success.
-* <identifier> points to a data node which must be stored.
-
-*Example:* +
-----
-PUT http://<controllerIP>:8080/restconf/config/module1:foo/bar
-Content-Type: applicaton/xml
-<bar>
- …
-</bar>
-----
-*Example with mount point:* +
-----
-PUT http://<controllerIP>:8080/restconf/config/module1:foo1/foo2/yang-ext:mount/module2:foo/bar
-Content-Type: applicaton/xml
-<bar>
- …
-</bar>
-----
-===== POST /restconf/config
-* Creates the data if it does not exist
-
-For example: +
-----
-POST URL: http://localhost:8080/restconf/config/
-content-type: application/yang.data+json
-JSON payload:
-
- {
- "toaster:toaster" :
- {
- "toaster:toasterManufacturer" : "General Electric",
- "toaster:toasterModelNumber" : "123",
- "toaster:toasterStatus" : "up"
- }
- }
-----
-===== POST /restconf/config/<identifier>
-
-* Creates the data if it does not exist in the Config datastore, and returns the state about success.
-* <identifier> points to a data node where data must be stored.
-* The root element of data must have the namespace (data are in XML) or module name (data are in JSON.)
-
-*Example:* +
-----
-POST http://<controllerIP>:8080/restconf/config/module1:foo
-Content-Type: applicaton/xml/
-<bar xmlns=“module1namespace”>
- …
-</bar>
-----
-*Example with mount point:*
-----
-http://<controllerIP>:8080/restconf/config/module1:foo1/foo2/yang-ext:mount/module2:foo
-Content-Type: applicaton/xml
-<bar xmlns=“module2namespace”>
- …
-</bar>
-----
-===== POST /restconf/operations/<moduleName>:<rpcName>
-
-* Invokes RPC.
-* <moduleName>:<rpcName> - <moduleName> is the name of the module and <rpcName> is the name of the RPC in this module.
-* The Root element of the data sent to RPC must have the name “input”.
-* The result can be the status code or the retrieved data having the root element “output”.
-
-*Example:* +
-----
-POST http://<controllerIP>:8080/restconf/operations/module1:fooRpc
-Content-Type: applicaton/xml
-Accept: applicaton/xml
-<input>
- …
-</input>
-
-The answer from the server could be:
-<output>
- …
-</output>
-----
-*An example using a JSON payload:* +
-----
-POST http://localhost:8080/restconf/operations/toaster:make-toast
-Content-Type: application/yang.data+json
-{
- "input" :
- {
- "toaster:toasterDoneness" : "10",
- "toaster:toasterToastType":"wheat-bread"
- }
-}
-----
-
-NOTE: Even though this is a default for the toasterToastType value in the yang, you still need to define it.
-
-===== DELETE /restconf/config/<identifier>
-
-* Removes the data node in the Config datastore and returns the state about success.
-* <identifier> points to a data node which must be removed.
-
-More information is available in the http://tools.ietf.org/html/draft-bierman-netconf-restconf-02[Restconf RFC].
-
-==== How Restconf works
-Restconf uses these base classes: +
-
-InstanceIdentifier:: Represents the path in the data tree
-ConsumerSession:: Used for invoking RPCs
-DataBrokerService:: Offers manipulation with transactions and reading data from the datastores
-SchemaContext:: Holds information about yang modules
-MountService:: Returns MountInstance based on the InstanceIdentifier pointing to a mount point
-MountInstace:: Contains the SchemaContext behind the mount point
-DataSchemaNode:: Provides information about the schema node
-SimpleNode:: Possesses the same name as the schema node, and contains the value representing the data node value
-CompositeNode:: Can contain CompositeNode-s and SimpleNode-s
-
-==== GET in action
-Figure 1 shows the GET operation with URI restconf/config/M:N where M is the module name, and N is the node name.
-
-
-.Get
-image::Get.png[width=500]
-
-. The requested URI is translated into the InstanceIdentifier which points to the data node. During this translation, the DataSchemaNode that conforms to the data node is obtained. If the data node is behind the mount point, the MountInstance is obtained as well.
-. Restconf asks for the value of the data node from DataBrokerService based on InstanceIdentifier.
-. DataBrokerService returns CompositeNode as data.
-. StructuredDataToXmlProvider or StructuredDataToJsonProvider is called based on the *Accept* field from the http request. These two providers can transform CompositeNode regarding DataSchemaNode to an XML or JSON document.
-. XML or JSON is returned as the answer on the request from the client.
-
-==== PUT in action
-
-Figure 2 shows the PUT operation with the URI restconf/config/M:N where M is the module name, and N is the node name. Data is sent in the request either in the XML or JSON format.
-
-.Put
-
-image::Put.png[width=500]
-
-. Input data is sent to JsonToCompositeNodeProvider or XmlToCompositeNodeProvider. The correct provider is selected based on the Content-Type field from the http request. These two providers can transform input data to CompositeNode. However, this CompositeNode does not contain enough information for transactions.
-. The requested URI is translated into InstanceIdentifier which points to the data node. DataSchemaNode conforming to the data node is obtained during this translation. If the data node is behind the mount point, the MountInstance is obtained as well.
-. CompositeNode can be normalized by adding additional information from DataSchemaNode.
-. Restconf begins the transaction, and puts CompositeNode with InstanceIdentifier into it. The response on the request from the client is the status code which depends on the result from the transaction.
-
-=== Something practical
-
-. Create a new flow on the switch openflow:1 in table 2.
-
-*HTTP request* +
-----
-Operation: POST
-URI: http://192.168.11.1:8080/restconf/config/opendaylight-inventory:nodes/node/openflow:1/table/2
-Content-Type: application/xml
-----
-----
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<flow
- xmlns="urn:opendaylight:flow:inventory">
- <strict>false</strict>
- <instructions>
- <instruction>
- <order>1</order>
- <apply-actions>
- <action>
- <order>1</order>
- <flood-all-action/>
- </action>
- </apply-actions>
- </instruction>
- </instructions>
- <table_id>2</table_id>
- <id>111</id>
- <cookie_mask>10</cookie_mask>
- <out_port>10</out_port>
- <installHw>false</installHw>
- <out_group>2</out_group>
- <match>
- <ethernet-match>
- <ethernet-type>
- <type>2048</type>
- </ethernet-type>
- </ethernet-match>
- <ipv4-destination>10.0.0.1/24</ipv4-destination>
- </match>
- <hard-timeout>0</hard-timeout>
- <cookie>10</cookie>
- <idle-timeout>0</idle-timeout>
- <flow-name>FooXf22</flow-name>
- <priority>2</priority>
- <barrier>false</barrier>
-</flow>
-----
-*HTTP response* +
-----
-Status: 204 No Content
-----
-[start=2]
-. Change _strict_ to _true_ in the previous flow.
-
-*HTTP request* +
-----
-Operation: PUT
-URI: http://192.168.11.1:8080/restconf/config/opendaylight-inventory:nodes/node/openflow:1/table/2/flow/111
-Content-Type: application/xml
-----
-----
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<flow
- xmlns="urn:opendaylight:flow:inventory">
- <strict>true</strict>
- <instructions>
- <instruction>
- <order>1</order>
- <apply-actions>
- <action>
- <order>1</order>
- <flood-all-action/>
- </action>
- </apply-actions>
- </instruction>
- </instructions>
- <table_id>2</table_id>
- <id>111</id>
- <cookie_mask>10</cookie_mask>
- <out_port>10</out_port>
- <installHw>false</installHw>
- <out_group>2</out_group>
- <match>
- <ethernet-match>
- <ethernet-type>
- <type>2048</type>
- </ethernet-type>
- </ethernet-match>
- <ipv4-destination>10.0.0.1/24</ipv4-destination>
- </match>
- <hard-timeout>0</hard-timeout>
- <cookie>10</cookie>
- <idle-timeout>0</idle-timeout>
- <flow-name>FooXf22</flow-name>
- <priority>2</priority>
- <barrier>false</barrier>
-</flow>
-----
-*HTTP response* +
-----
-Status: 200 OK
-----
-[start=3]
-. Show flow: check that _strict_ is _true_.
-
-*HTTP request* +
-----
-Operation: GET
-URI: http://192.168.11.1:8080/restconf/config/opendaylight-inventory:nodes/node/openflow:1/table/2/flow/111
-Accept: application/xml
-----
-*HTTP response* +
-----
-Status: 200 OK
-----
-
-----
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<flow
- xmlns="urn:opendaylight:flow:inventory">
- <strict>true</strict>
- <instructions>
- <instruction>
- <order>1</order>
- <apply-actions>
- <action>
- <order>1</order>
- <flood-all-action/>
- </action>
- </apply-actions>
- </instruction>
- </instructions>
- <table_id>2</table_id>
- <id>111</id>
- <cookie_mask>10</cookie_mask>
- <out_port>10</out_port>
- <installHw>false</installHw>
- <out_group>2</out_group>
- <match>
- <ethernet-match>
- <ethernet-type>
- <type>2048</type>
- </ethernet-type>
- </ethernet-match>
- <ipv4-destination>10.0.0.1/24</ipv4-destination>
- </match>
- <hard-timeout>0</hard-timeout>
- <cookie>10</cookie>
- <idle-timeout>0</idle-timeout>
- <flow-name>FooXf22</flow-name>
- <priority>2</priority>
- <barrier>false</barrier>
-</flow>
-----
-[start=4]
-. Delete the flow created.
-
-*HTTP request* +
-----
-Operation: DELETE
-URI: http://192.168.11.1:8080/restconf/config/opendaylight-inventory:nodes/node/openflow:1/table/2/flow/111
-----
-*HTTP response* +
-----
-Status: 200 OK
-----
-=== OpenDaylight Controller: Configuration
-The Controller configuration operation has three stages:
-
-* First, a Proposed configuration is created. Its target is to replace the old configuration.
-* Second, the Proposed configuration is validated, and then committed. If it passes validation successfully, the Proposed configuration state will be changed to Validated.
-* Finally, a Validated configuration can be Committed, and the affected modules can be reconfigured.
-
-In fact, each configuration operation is wrapped in a transaction. Once a transaction is created, it can be configured, that is to say, a user can abort the transaction during this stage. After the transaction configuration is done, it is committed to the validation stage. In this stage, the validation procedures are invoked.
- If one or more validations fail, the transaction can be reconfigured. Upon success, the second phase commit is invoked.
- If this commit is successful, the transaction enters the last stage, committed. After that, the desired modules are reconfigured. If the second phase commit fails, it means that the transaction is unhealthy - basically, a new configuration instance creation failed, and the application can be in an inconsistent state.
-
-.Configuration states
-image::configuration.jpg[width=500]
-
-.Transaction states
-image::Transaction.jpg[width=500]
-
-==== Validation
-To secure the consistency and safety of the new configuration and to avoid conflicts, the configuration validation process is necessary.
-Usually, validation checks the input parameters of a new configuration, and mostly verifies module-specific relationships.
-The validation procedure results in a decision on whether the proposed configuration is healthy.
-
-==== Dependency resolver
-Since there can be dependencies between modules, a change in a module configuration can affect the state of other modules. Therefore, we need to verify whether dependencies on other modules can be resolved.
-The Dependency Resolver acts in a manner similar to dependency injectors. Basically, a dependency tree is built.
-
-=== APIs and SPIs
-This section describes configuration system APIs and SPIs.
-
-
-==== SPIs
-*Module* org.opendaylight.controller.config.spi. Module is the common interface for all modules: every module must implement it. The module is designated to hold configuration attributes, validate them, and create instances of service based on the attributes.
-This instance must implement the AutoCloseable interface, owing to resources clean up. If the module was created from an already running instance, it contains an old instance of the module. A module can implement multiple services. If the module depends on other modules, setters need to be annotated with @RequireInterface.
-
-*Module creation*
-
-. The module needs to be configured, set with all required attributes.
-. The module is then moved to the commit stage for validation. If the validation fails, the module attributes can be reconfigured. Otherwise, a new instance is either created, or an old instance is reconfigured.
-A module instance is identified by ModuleIdentifier, consisting of the factory name and instance name.
-
-*ModuleFactory* org.opendaylight.controller.config.spi. The ModuleFactory interface must be implemented by each module factory. +
-A module factory can create a new module instance in two ways: +
-
-* From an existing module instance
-* An entirely new instance +
-ModuleFactory can also return default modules, useful for populating registry with already existing configurations.
-A module factory implementation must have a globally unique name.
-
-==== APIs
-
-|===
-| ConfigRegistry | Represents functionality provided by a configuration transaction (create, destroy module, validate, or abort transaction).
-| ConfigTransactionController | Represents functionality for manipulating with configuration transactions (begin, commit config).
-| RuntimeBeanRegistratorAwareConfiBean | The module implementing this interface will receive RuntimeBeanRegistrator before getInstance is invoked.
-|===
-
-==== Runtime APIs
-
-|===
-| RuntimeBean | Common interface for all runtime beans
-| RootRuntimeBeanRegistrator | Represents functionality for root runtime bean registration, which subsequently allows hierarchical registrations
-| HierarchicalRuntimeBeanRegistration | Represents functionality for runtime bean registration and unreregistration from hierarchy
-|===
-
-==== JMX APIs
-
-JMX API is purposed as a transition between the Client API and the JMX platform. +
-
-|===
-| ConfigTransactionControllerMXBean | Extends ConfigTransactionController, executed by Jolokia clients on configuration transaction.
-| ConfigRegistryMXBean | Represents entry point of configuration management for MXBeans.
-| Object names | Object Name is the pattern used in JMX to locate JMX beans. It consists of domain and key properties (at least one key-value pair). Domain is defined as "org.opendaylight.controller". The only mandatory property is "type".
-|===
-
-==== Use case scenarios
-
-A few samples of successful and unsuccessful transaction scenarios follow: +
-
-*Successful commit scenario*
-
-. The user creates a transaction calling creteTransaction() method on ConfigRegistry.
-. ConfigRegisty creates a transaction controller, and registers the transaction as a new bean.
-. Runtime configurations are copied to the transaction. The user can create modules and set their attributes.
-. The configuration transaction is to be committed.
-. The validation process is performed.
-. After successful validation, the second phase commit begins.
-. Modules proposed to be destroyed are destroyed, and their service instances are closed.
-. Runtime beans are set to registrator.
-. The transaction controller invokes the method getInstance on each module.
-. The transaction is committed, and resources are either closed or released.
-
-*Validation failure scenario* +
-The transaction is the same as the previous case until the validation process. +
-
-. If validation fails, (that is to day, illegal input attributes values or dependency resolver failure), the validationException is thrown and exposed to the user.
-. The user can decide to reconfigure the transaction and commit again, or abort the current transaction.
-. On aborted transactions, TransactionController and JMXRegistrator are properly closed.
-. Unregistration event is sent to ConfigRegistry.
-
-==== Default module instances
-The configuration subsystem provides a way for modules to create default instances. A default instance is an instance of a module, that is created at the module bundle start-up (module becomes visible for
-configuration subsystem, for example, its bundle is activated in the OSGi environment). By default, no default instances are produced.
-
-The default instance does not differ from instances created later in the module life-cycle. The only difference is that the configuration for the default instance cannot be provided by the configuration subsystem.
-The module has to acquire the configuration for these instances on its own. It can be acquired from, for example, environment variables.
-After the creation of a default instance, it acts as a regular instance and fully participates in the configuration subsystem (It can be reconfigured or deleted in following transactions.).
-
-=== OpenDaylight Controller configuration: Initial
-The Initial configuration of the controller involves two methods.
-
-=== Initial configuration for controller
-The two ways of configuring the controller: +
-
-* Using the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:config.ini[config.ini] property file to pass configuration properties to the OSGi bundles besides the config subsystem.
-* Using the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Configuration:Initial#Configuration_Persister[configuration persister] to push the initial configuration for modules managed by the config subsystem.
-
-==== Using the config.ini property file
-
-The config.ini property file can be used to provide a set of properties for any OSGi bundle deployed to the controller. It is usually used to configure bundles that are not managed by the config subsystem. For details, see <<_opendaylight_controller_configuration_config_ini>>.
-
-==== Using configuration persister
-
-Configuration persister is a default service in the controller, and is started automatically using the OSGi Activator. Its purpose is to load the initial configuration for the config subsystem and store a snapshot for every new configuration state pushed to the config-subsystem from external clients.
-For details, see <<_opendaylight_controller_configuration_persister>>.
-
-=== OpenDaylight Controller configuration: config.ini
-
-Various parts of the system that are not under the configuration subsystem use the file config.ini. Changes to this file apply after a server restart. The tabulation of several important configuration keys and values follows:
-
-[cols="2*", width="75%"]
-|===
-
-|Setting | Description
-| yangstore.blacklist=.\*controller.model.* | This regular expression (can be OR-ed using pipe character) tells netconf to exclude the yang files found in the matching bundle symbolic name from the hello message. This is helpful when dealing with a netconf client that has parsing problems.
-| netconf.config.persister.* settings | See <<_opendaylight_controller_configuration_initial>>.
-| netconf.tcp.address=0.0.0.0 netconf.tcp.port=8383 +
-
-netconf.ssh.address=0.0.0.0 netconf.ssh.port=1830 netconf.ssh.pk.path = ./configuration/RSA.pk +
-
-netconf.tcp.client.address=127.0.0.1 netconf.tcp.client.port=8383 | These settings specify the netconf server bindings. IP address 0.0.0.0 is used when all available network interfaces must be used by the netconf server. When starting the ssh server, the user must provide a private key. The actual authentication is done in the user admin module. By default, users admin:admin and netconf:netconf can be used to connect by means of ssh. Since the ssh bridge acts as a proxy, one needs to specify the netconf plaintext TCP address and port. These settings must normally be identical to those specified by netconf.tcp.* .
-|===
-=== OpenDaylight Controller: Configuration Persister
-One way of configuring the controller is to use the configuration persister to push the initial configuration for modules managed by the config subsystem.
-
-==== Using configuration persister
-
-The configuration persister is a default service in the controller, and is started automatically using the OSGi Activator.
-Its purpose: +
-
-* Load the initial configuration for the config subsystem.
-* Store a snapshot for every new configuration state pushed to the config-subsystem from external clients. +
-
-It retrieves the base configuration from the config.ini property file, and tries to load the configuration for the config subsystem.
-The configuration for the config subsystem is pushed as a set of edit-config netconf rpcs followed by a commit rpc since the config persister acts as a netconf client.
-
-*Configuration persister lifecycle:* +
-
-. Start the config persister service at _config-persister-impl_ bundle startup.
-. Retrieve the base configuration of the adapters from the config.ini property file.
-. Initialize the backing storage adapters.
-. Initialize the netconf client, and connect to the netconf endpoint of the config subsystem.
-. Load the initial configuration snapshots from the latest storage adapter.
-. Send the edit-config rpc with the initial configuration snapshots.
-. Send the commit rpc.
-. Listen for any of the following changes to the configuration and persist a snapshot.
-
-*Configuration Persister interactions:* +
-
-.Persister
-image::Persister.jpg[width=500]
-
-=== Current configuration for controller distribution
-
-The _config.ini_ property file contains the following configuration for the configuration persister: +
-----
-netconf.config.persister.active=1,2
-
-netconf.config.persister.1.storageAdapterClass=org.opendaylight.controller.config.persist.storage.directory.autodetect.AutodetectDirectoryStorageAdapter
-
-netconf.config.persister.1.properties.directoryStorage=configuration/initial/
-
-netconf.config.persister.1.readonly=true
-
-
-netconf.config.persister.2.storageAdapterClass=org.opendaylight.controller.config.persist.storage.file.xml.XmlFileStorageAdapter
-
-netconf.config.persister.2.properties.fileStorage=configuration/current/controller.currentconfig.xml
-
-netconf.config.persister.2.properties.numberOfBackups=1
-----
-
-With this configuration, the configuration persister initializes two adapters: +
-
-* AutodetectDirectoryStorageAdapter to load the initial configuration files from the _configuration/initial/_ folder. These files will be pushed as the initial configuration for the config subsystem. Since this adapter is Read only, it will not store any configuration snapshot during the controller lifecycle.
-* XmlFileStorageAdapter to store snapshots of the current configuration after any change in the file _configuration/current/controller.currentconfig.xml_ (Only 1 snapshot backup is kept; every new change overwrites the previous one). +
-The initial configuration in the controller distribution consists of 2 files in the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Configuration:Initial#Persisted_snapshot_format[xml format]. +
-* configuration/initial/00-netty.xml: +
-----
-<snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:netty?module=netty&revision=2013-11-19</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:eventexecutor?module=netty-event-executor&revision=2013-11-12</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:threadgroup?module=threadgroup&revision=2013-11-07</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:timer?module=netty-timer&revision=2013-11-19</capability>
- </required-capabilities>
- <configuration>
-
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:threadgroup">netty:netty-threadgroup-fixed</type>
- <name>global-boss-group</name>
- </module>
- <module>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:threadgroup">netty:netty-threadgroup-fixed</type>
- <name>global-worker-group</name>
- </module>
- <module>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:timer">netty:netty-hashed-wheel-timer</type>
- <name>global-timer</name>
- </module>
- <module>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty:eventexecutor">netty:netty-global-event-executor</type>
- <name>global-event-executor</name>
- </module>
- </modules>
-
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
- <instance>
- <name>global-boss-group</name>
- <provider>/modules/module[type='netty-threadgroup-fixed'][name='global-boss-group']</provider>
- </instance>
- <instance>
- <name>global-worker-group</name>
- <provider>/modules/module[type='netty-threadgroup-fixed'][name='global-worker-group']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-event-executor</type>
- <instance>
- <name>global-event-executor</name>
- <provider>/modules/module[type='netty-global-event-executor'][name='global-event-executor']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-timer</type>
- <instance>
- <name>global-timer</name>
- <provider>/modules/module[type='netty-hashed-wheel-timer'][name='global-timer']</provider>
- </instance>
- </service>
- </services>
- </data>
-
- </configuration>
-</snapshot>
-----
-This configuration snapshot instantiates netty utilities, which will be utilized by the controller components that use netty internally. +
-
-*configuration/initial/01-md-sal.xml:* +
-----
-<snapshot>
-
- <configuration>
-
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">prefix:schema-service-singleton</type>
- <name>yang-schema-service</name>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">prefix:hash-map-data-store</type>
- <name>hash-map-data-store</name>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">prefix:dom-broker-impl</type>
- <name>dom-broker</name>
- <data-store xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl">
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-data-store</type>
- <!-- to switch to the clustered data store, comment out the hash-map-data-store <name> and uncomment the cluster-data-store one -->
- <name>hash-map-data-store</name>
- <!-- <name>cluster-data-store</name> -->
- </data-store>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-broker-impl</type>
- <name>binding-broker-impl</name>
- <notification-service xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
- <name>binding-notification-broker</name>
- </notification-service>
- <data-broker xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
- <name>binding-data-broker</name>
- </data-broker>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:runtime-generated-mapping</type>
- <name>runtime-mapping-singleton</name>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-notification-broker</type>
- <name>binding-notification-broker</name>
- </module>
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-data-broker</type>
- <name>binding-data-broker</name>
- <dom-broker xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
- <name>dom-broker</name>
- </dom-broker>
- <mapping-service xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">binding:binding-dom-mapping-service</type>
- <name>runtime-mapping-singleton</name>
- </mapping-service>
- </module>
-
- </modules>
-
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:schema-service</type>
- <instance>
- <name>yang-schema-service</name>
- <provider>/modules/module[type='schema-service-singleton'][name='yang-schema-service']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
- <instance>
- <name>binding-notification-broker</name>
- <provider>/modules/module[type='binding-notification-broker'][name='binding-notification-broker']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-data-store</type>
- <instance>
- <name>hash-map-data-store</name>
- <provider>/modules/module[type='hash-map-data-store'][name='hash-map-data-store']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-broker-osgi-registry</type>
- <instance>
- <name>binding-osgi-broker</name>
- <provider>/modules/module[type='binding-broker-impl'][name='binding-broker-impl']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-rpc-registry</type>
- <instance>
- <name>binding-rpc-broker</name>
- <provider>/modules/module[type='binding-broker-impl'][name='binding-broker-impl']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:binding-impl="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">binding-impl:binding-dom-mapping-service</type>
- <instance>
- <name>runtime-mapping-singleton</name>
- <provider>/modules/module[type='runtime-generated-mapping'][name='runtime-mapping-singleton']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:dom="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">dom:dom-broker-osgi-registry</type>
- <instance>
- <name>dom-broker</name>
- <provider>/modules/module[type='dom-broker-impl'][name='dom-broker']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
- <instance>
- <name>binding-data-broker</name>
- <provider>/modules/module[type='binding-data-broker'][name='binding-data-broker']</provider>
- </instance>
- </service>
-
- </services>
- </data>
-
- </configuration>
-
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:netty:eventexecutor?module=netty-event-executor&revision=2013-11-12</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:threadpool?module=threadpool&revision=2013-04-09</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding?module=opendaylight-md-sal-binding&revision=2013-10-28</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom?module=opendaylight-md-sal-dom&revision=2013-10-28</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl?module=opendaylight-sal-binding-broker-impl&revision=2013-10-28</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom:impl?module=opendaylight-sal-dom-broker-impl&revision=2013-10-28</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:common?module=opendaylight-md-sal-common&revision=2013-10-28</capability>
- </required-capabilities>
-
-</snapshot>
-----
-This configuration snapshot instantiates md-sal modules.
-
-After the controller is started, all these modules will be instantiated and configured. They can be further referenced from the new modules as dependencies, reconfigured, or even deleted.
-These modules are considered to be the base configuration for the controller and the purpose of them being configured automatically is to simplify the process of controller configuration for users, since the base modules will already be ready for use.
-
-=== Adding custom initial configuration
-
-There are multiple ways to add the custom initial confguration to the controller distribution:
-
-. Manually create the config file, and put it in the initial configuration folder.
-. Reconfigure the running controller using the yuma yangcli tool. The XmlFileStorageAdapter adapter will store the current snapshot, and on the next startup of the controller (assuming it was not rebuilt since), it will load the configuration containing the changes.
-
-==== Custom initial configuration in bgpcep distribution
-
-The BGPCEP project will serve as an example for adding the custom initial configuration. The bgpcep project contains the custom initial configuration that is based on the initial configuration from the controller. It adds new modules, which depend on MD-SAL and netty modules created with the initial config files of the controller. There are multiple config files in the bgpcep project. Only the 30-programming.xml file located under the programming-parent/controller-config project will be described in this section. This file contains the configuration for an instance of the instruction-scheduler module:
-
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- vi: set et smarttab sw=4 tabstop=4: -->
-<!--
- Copyright (c) 2013 Cisco Systems, Inc. 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.
--->
-<snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding?module=opendaylight-md-sal-binding&revision=2013-10-28</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:netty?module=netty&revision=2013-11-19</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:programming:impl?module=config-programming-impl&revision=2013-11-15</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:programming:spi?module=config-programming-spi&revision=2013-11-15</capability>
- </required-capabilities>
- <configuration>
-
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:programming:impl">prefix:instruction-scheduler-impl</type>
- <name>global-instruction-scheduler</name>
- <data-provider>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
- <name>binding-data-broker</name>
- </data-provider>
- <notification-service>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
- <name>binding-notification-broker</name>
- </notification-service>
- <rpc-registry>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-rpc-registry</type>
- <name>binding-rpc-broker</name>
- </rpc-registry>
- <timer>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-timer</type>
- <name>global-timer</name>
- </timer>
- </module>
- </modules>
-
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:pgmspi="urn:opendaylight:params:xml:ns:yang:controller:programming:spi">pgmspi:instruction-scheduler</type>
- <instance>
- <name>global-instruction-scheduler</name>
- <provider>/modules/module[type='instruction-scheduler-impl'][name='global-instruction-scheduler']</provider>
- </instance>
- </service>
- </services>
- </data>
-
- </configuration>
-</snapshot>
-----
-Instruction-scheduler is instantiated as a module of type _instruction-scheduler-impl_ with the name *global-instruction-scheduler:* +
-----
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:programming:impl">prefix:instruction-scheduler-impl</type>
- <name>global-instruction-scheduler</name>
- ...
-----
-There is also an alias created for this module instancfe, and the alias is *global-instruction-scheduler* of type _instruction-scheduler_: +
-----
-...
-<service>
- <type xmlns:pgmspi="urn:opendaylight:params:xml:ns:yang:controller:programming:spi">pgmspi:instruction-scheduler</type>
- <instance>
- <name>global-instruction-scheduler</name>
- <provider>/modules/module[type='instruction-scheduler-impl'][name='global-instruction-scheduler']</provider>
- </instance>
-</service>
-...
-----
-The type of the alias is instruction-scheduler. This type refers to a certain service that is implemented by the instruction-scheduler-impl module. With this service type, the global-instruction-scheduler instance can be injected into any other module that requires instruction-scheduler as a dependency.
-One module can provide (implement) multiple services, and each of these services can be assigned an alias. This alias can be later used to reference the implementation it is pointing to.
-If no alias is assigned by the user, a default alias will be assigned for each provided service.
-The default alias is constructed from the name of the module instance with a prefix *ref_* and a possible suffix containing a number to resolve name clashes.
-It is recommended that users provide aliases for each service of every module instance, and use these aliases for dependency injection. References to the alias global-instruction-scheduler can be found in subsequent config files in the bgpcep project for example, _32-pcep.xml_ located under the _pcep-parent/pcep-controller-config_ project.
-
-The configuration contains four dependencies on the MD-SAL and the netty modules: +
-----
-...
-<data-provider>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-data-broker</type>
- <name>binding-data-broker</name>
-</data-provider>
-<notification-service>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-notification-service</type>
- <name>binding-notification-broker</name>
-</notification-service>
-<rpc-registry>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">binding:binding-rpc-registry</type>
- <name>binding-rpc-broker</name>
-</rpc-registry>
-<timer>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-timer</type>
- <name>global-timer</name>
-</timer>
-...
-----
-
-MD-SAL dependencies: +
-
-* Data-provider dependency
-* Notification-service dependency
-* Rpc-registry dependency
-
-All MD-SAL dependencies can be found in the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Configuration:Initial#Current_configuration_for_controller_distribution[MD-SAL initial configuration file]. For example, rpc-registry dependency points to an alias binding-rpc-broker of the type binding-rpc-registry. This alias further points to an instance of the binding-broker-impl named binding-broker-impl.
-The Yang module that defines the binding-broker-impl module : https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-binding-broker/src/main/yang/opendaylight-binding-broker-impl.yang;a=blob[opendaylight-binding-broker-impl.yang].
-
-*Netty dependencies:* +
-
-* Timer dependency
-
-This configuration expects these dependencies to be already up and ready. It is the responsibility of the configuration subsystem to find the dependency and inject it.
-If the configuration of a module points to a non-existing dependency, the configuration subsystem will produce an exception during the validation phase.
-Every user-created configuration needs to point to existing dependencies. In the case of multiple initial configuration files that depend on one another, the resolution order can be ensured by the names of the files. Files are sorted by their names in ascending order. This means that every configuration file will have the visibility of modules from all previous configuration files by means of aliases.
-
-NOTE: The configuration provided by initial config files can also be pushed to the controller at runtime using netconf client. The whole configuration located under the data tag needs to be inserted into the config tag in the edit-config rpc. For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Main#Examples[Examples].
-
-==== Configuration Persister
-
-As a part of the configuration subsystem, the purpose of the persister is to save and load a permanent copy of a configuration. The Persister interface represents basic operations over a storage - persist configuration and load last config, configuration snapshot is represented as string and set of it's capabilities. StorageAdapter represents an adapter interface to the ConfigProvider - subset of BundleContext, allowing access to the OSGi framework system properties.
-
-===== Persister implementation
-
-Configuration persister implementation is part of the Controller Netconf. PersisterAggregator class is the implementation of the Presister interface. The functionality is delegated to the storage adapters. Storage adapters are low level persisters that do the heavy lifting for this class. Instances of storage adapters can be injected directly by means of the constructor, or instantiated from a full name of its class provided in a properties file. There can be many persisters configured, and varying numbers of them can be used.
-
-*Example of presisters configuration:* +
-----
-netconf.config.persister.active=2,3
- # read startup configuration
- netconf.config.persister.1.storageAdapterClass=org.opendaylight.controller.config.persist.storage.directory.xml.XmlDirectoryStorageAdapter
- netconf.config.persister.1.properties.fileStorage=configuration/initial/
-
- netconf.config.persister.2.storageAdapterClass=org.opendaylight.controller.config.persist.storage.file.FileStorageAdapter
- netconf.config.persister.2.readonly=true
- netconf.config.persister.2.properties.fileStorage=configuration/current/controller.config.1.txt
-
- netconf.config.persister.3.storageAdapterClass=org.opendaylight.controller.config.persist.storage.file.FileStorageAdapter
- netconf.config.persister.3.properties.fileStorage=configuration/current/controller.config.2.txt
- netconf.config.persister.3.properties.numberOfBackups=3
-----
-
-During server startup, ConfigPersisterNotificationHandler requests the last snapshot from the underlying storages. Each storage can respond by giving a snapshot or an absent response. The PersisterAggregator#loadLastConfigs() will search for the first non-absent response from storages ordered backwards as user specified (first '3', then '2'). When a commit notification is received, '2' will be omitted because the read-only flag is set to true, so only '3' will have a chance to persist the new configuration.
-If read-only was false, or not specified, both storage adapters would be called in the order specified by 'netconf.config.persister' property.
-
-=== Persister Notification Handler
-
-ConfigPersisterNotificationHandler class is responsible for listening for netconf notifications containing the latest committed configuration.
-The listener can handle incoming notifications, or delegates the configuration saving or loading to the persister.
-
-==== Storage Adapter implementations
-
-*XML File Storage* +
-
-The XmlFileStorageAdapter implementation stores configuration in an xml file.
-
-*XML Directory Storage* +
-
-XmlDirectoryStorageAdapter retrieves the initial configuration from a directory. If multiple xml files are present, files are ordered based on the file names and pushed in this order (for example, 00.xml, then 01.xml..) Each file defines its required capabilities, so it will be pushed when those capabilities are advertized by ODL. Writing to this persister is not supported.
-
-*No-Operation Storage* +
-
-NoOpStorageAdapter serves as a dummy implementation of the storage adapter.
-
-*Obsolete storage adapters* +
-
-* File Storage
-
-* FileStorageAdapter implements StorageAdapter, and provides file based configuration persisting.
-File path and name is stored as a property and a number of stored backups, expressing the count of the last configurations to be persisted too.
-The implementation can handle persisting input configuration, and load the last configuration.
-
-* Directory Storage
-
-* DirectoryStorageAdapter retrieves initial configurations from a directory. If multiple files are present, snapshot and required capabilities will be merged together. See configuration later on this page for details. Writing to this persister is not supported.
-
-* Autodetect Directory Storage
-
-* AutodetectDirectoryStorageAdapter retrieves initial configuration from a directory (exactly as Xml Directory Storage) but supports xml as well as plaintext format for configuration files. Xml and plaintext files can be combined in one directory. Purpose of this persister is to keep backwards compatibility for plaintext configuration files.
-
-IMPORTANT: This functionality will be removed in later releases since Plaintext File/Directory adapters are deprecated, and will be fully replaced by xml storage adapters.
-
-===== Persisted snapshot format
-
-Configuration snapshots are persisted in xml files for both file and directory adapters. They share the same format: +
-----
-<snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:netty?module=netty&revision=2013-11-19</capability>
- ...
- </required-capabilities>
- <configuration>
-
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- ...
- </modules>
-
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- ...
- </services>
-
- </data>
-
- </configuration>
-</snapshot>
-----
-The whole snapshot is encapsulated in the snapshot tag that contains two children elements: +
-
-* The required-capabilities tag contains the list of yang capabilities that are required to push configurations located under the configuration tag. The config persister will not push the configuration before the netconf endpoint for the config subsystem reports all needed capabilities. Every yang model that is referenced within this xml file (as namespace for xml tag) must be referenced as a capability in this list.
-* The configuration tag contains the configurations to be pushed to the config subsystem. It is wrapped in a data tag with the base netconf namespace. The whole data tag, with all its child elements, will be inserted into an edit-config rpc as config tag. For more information about the structure of configuration data, see base yang model for the config subsystem and all the configuration yang files for the controller modules as well as those provided examples. Examples contain multiple explained edit-config rpcs that change the configuration.
-
-NOTE: XML File adapter adds additional tags to the xml format since it supports multiple snapshots per file.
-
-The xml format for xml file adapter: +
-----
-<persisted-snapshots>
- <snapshots>
- <snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:shutdown:impl?module=shutdown-impl&revision=2013-12-18</capability>
- </required-capabilities>
- <configuration>
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- ....
- </modules>
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- ...
- </services>
- </data>
- </configuration>
- </snapshot>
- <snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:controller:shutdown:impl?module=shutdown-impl&revision=2013-12-18</capability>
- </required-capabilities>
- <configuration>
- <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- ....
- </modules>
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- ...
- </services>
- </data>
- </configuration>
- </snapshot>
- </snapshots>
-</persisted-snapshots>
-----
-=== MD-SAL architecture: Clustering Notifications
-MD-SAL supports two kinds of messaging exchange pattern: +
-
-* Request/Reply
-* Publish/Subscribe
-The RPC module implements the Request/Reply pattern. The notification module implements the Publish/Subscribe functionality. The implementation details are provided at: https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Explained:Messaging_Patterns[OpenDaylight Controller:MD-SAL:Explained:Messaging Patterns].
-The focus now is on Publish/Subscribe implementation.An earlier implementation assumed a single VM deployment of the controller.The message exchange happens only within a VM in memory. The current requirement is to enable these notifications across nodes in the cluster.
-
-Publish/Subscribe notifications are of two kinds: +
-
-* Data Change events
-* Yang notifications
-In both cases, the notifications are broadcast to all "listeners". +
-*Requirements* +
-Some of the requirements: +
-
-* Ability to publish notifications to any subscriber in the cluster
-* Subscriber ability to specify delivery policy
-* 1 of N: Delivery of the notification to any one of N instances of application running in the cluster
-* N of N: Broadcasts
-* Local only: Notifying events generated on the same node as the application instance
-* Load Balancing: Round robin, least loaded etc
-* Content Based or any other application specified custom logic
-* Publisher capability to attach properties to the message
-* Message priority
-* Delivery guarantee
-* Ability to plug-in external systems such as AMQP based systems
-
-==== Proposed change
-Based on the requirements, a change in the aPI was proposed: +
-----
- Yang notification
- publish(Notification notification, MessageProperties props);
- registerNotificationListener(org.opendaylight.yangtools.yang.binding.NotificationListener.NotificationListener listener, Selector selector);
- registerNotificationListener(Class notificationType, org.opendaylight.controller.sal.binding.api.NotificationListener listener, Selector selector);
- Data change notification
- registerDataChangeListener(LogicalDatastoreType store, P path, L listener, DataChangeScope triggeringScope, "Selector selector");
-public interface MessageProperties{
- public Priority priority();
- ...[add more properties]
-}
-public enum Priority { HIGH, NORMAL, LOW};
-public interface Selector {
- public List<InstanceLocator> select(Notification event, List<InstanceLocator> instances);
-}
-----
-
-=== MD-SAL Architecture: DOM
-There are several issues that impede the reliability and performance of mD-SAL: +
-
-* Data structures (defined in yang-data-api) are like XML structures. Therefore, it is hard to implement an optimized datastore atop them. Instead, YANG-defined data structures must be used in the data store. YANG-defined data structures are already being used in the MD-SAL: in the Java DTOs generated by YangTools, and in other components.
-* The current MD-SAL data contracts do not provide enough capabilities to more accurately specify an the intent of an application and to perform optimizations to clients (for example, 'do not unnecessarily deserialize data', or 'compute only necessary change sets'). The current datastore implementation prevents atomic updates on subtrees.
-
-==== MD-SAL DOM Data Broker
-The current DOM Data Broker design does not include an assumption of a intelligent in-memory cache with tree-like structures that would:
-
-* Be able to track dependencies
-* Calculate change sets
-* Maintain the relationships between commit handlers, notification listeners and the actual data.
-This may lead to an inefficient implementation of the two-phase commit, where all state tracking during the is done by the Data Broker itself as follows: +
-. Calculate the affected subtrees.
-. Filter the commit handlers by the affected subtrees.
-. Filter data change listeners by the affected subtrees.
-. Capture the initial state for data change listeners (one read per data change listener set).
-. Start Request Commit of all the affected commit handlers.
-. Finish Commit on all the affected commit handlers.
-. Capture the final state for data change listeners (one read per data change listener set).
-. Publish the Data Change events to the affected data change listeners.
-The states that the current DOM Data Broke keeps and maintains are mapping of subtree paths to: *
-
-* Registered commit handlers
-* Registered data change listeners
-* Registered data readers
-DOM Data Broker has the following state keeping responsibilities: *
-
-* Read request routing for data readers
-* Two phase commit coordination
-* Publish Data Change Events
-* Capture Before and After state
-
-=== MD-SAL: Infinispan Data Store
-
-==== Components of Infinispan Data Store
-Infinispan Data Store comprises the following major components: +
-
-* Encoding or Decoding a Normalized Node into and from the Infinispan TreeCache
-* Managing transactions
-* Managing DataChange notifications
-
-==== Encoding or Decoding a Normalized Node into and from the Inifinispan TreeCache +
-A NormalizedNode represents a tree whose structure closely models the yang model of a bunch of modules. The NormalizedNode tree typically has values either placed in: +
-
-* A LeafNode (corresponding to a leaf in yang)
-* A LeafSetEntryNode (corresponding to a leaflist in yang) +
-The encoding logic walks the NormalizedNode tree looking for LeafNodes and LeafSetEntryNodes.When the logic finds a LeafNode or a LeafSetEntryNode, it records the finding in a map with the following: +
-
-* Instance Identifier of the parent as the key
-* The value of the leaf or leafset entry store in a map where:
-** The NodeIdentifier of the leaf/leafsetentry is the key.
-** The value of the leaf/leafsetentry is the value.
-The decoding process involves the following steps: +
-
-. Uses the interface of TreeCache to get to a certain node in the tree
-. Walks through the tree, and reconstructs the NormalizedNode based on the key and value in the Infinispan TreeCache
-. Validates the NormalizedNode against the schema
-
-==== Managing Transactions +
-To ensure read-write isolation level, and for other reasons, an infinispan (JTA) transaction for each datastore transaction is created. Since a single thread may be used for multiple JTA transactions,
-the implementation has to ensure the suspension and resumption of the JTA transactions appropriately.
-However, this does not seem to have an impact on performance.
-
-==== Managing DataChange notifications +
-The current interface for data change notifications supports the registering of listeners for the following notifications: +
-
-* Data changes at Node (consider node of a tree) level
-* Events for any changes that happen at *one* level (meaning immediate children)
-* Any change at the subtree level
-The event sent to the listener requires that the following snapshots of the tree be maintained: +
-
-* Before data change
-* After data change
-
-NOTE: This process is very expensive. It means maintaining a Normalized Node representing a snapshot of the tree. It involves converting the tree in Infinispan to NormalizeNode object tree required by the consumer at the start of each transaction.
-
-*To maintain the data changes:* +
-
-. At the begin of transaction, get a NormalizedNode Object tree of the current tree in ISPN TreeCache (This is mandated by the current DataChangeEvent interface.)
-. For each CUD operations that happens within the transaction, maintain a transaction log.
-. When the pre-commit of the 3PhaseCommit Transaction Interface is called, prepare data changes. This involves: +
-.. Comparing the transaction log items with the Snapshot Tree one taken at the beginning of the transactions
-.. Preparing the DataChangeEvent lists based on what level the listeners have registered
-. Upon a commit, send the events to the listeners in a separate executor, that is asynchronously.
-
-*Suggested changes* +
-
-* Remove the requirement for sending the `before transaction tree' or the `after transaction tree' within each event.
-* Send the changed paths of tree to the consumer, and let the consumer do the reading.
-
-==== Building the POC +
-To build or run the POC, you need the latest version of the following: +
-
-* Yangtools
-* Controller
-* OpenFlow plugin
-
-==== To get yangtools +
-
-. Get the latest yangtools sources, and then create a branch of it using the following command:
-: git checkout 306ffd9eea5a52556b4877debd2a79ca0573ff0c -b infinispan-data-store +
-. Build using the following command:
-: mvn clean install -DskipTests +
-
-==== To get the Controller
-
-. Get the latest controller, and then create a branch using the following command:
-: git checkout 259b65622b8c29c49235c2210609b9f7a68826eb -b infinispan-data-store +
-. Apply the following gerrit.
-: https://git.opendaylight.org/gerrit/#/c/5900/
-. Build using the following command:
-: mvn clean install -DskipTests +
-. If the build should fails, use the following commang:
-: cd opendaylight/md-sal/sal-ispn-datastore +
-. Build using the following command:
-+mvn clean install+
-. Return to the controller directory, and build using:
-: mvn clean install -DskipTests or resume build +
-
-==== To get the OpenFlowplugin
-
-. Get the latest openflowplugin code and then create a branch using the following command:
-: git checkout 6affeefef4de51ce4b7de86fd9ccf51add3922f7 -b infinispan-data-store +
-. Build using the following command:
-: mvn clean install -DskipTests +
-. Copy the sal-ispn-datastore jar to the plugins folder.
-
-==== Running the POC +
-*Prerequisite* +
-Ensure that the 01-md-sal.xml file has been changed to use the new MD-SAL datastore. +
-
-* Run the controller with the infinispan datastore. The section, <<_comparison_of_in_memory_and_infinispan_datastore>> provides information about cbench testing.
-
-NOTE: If you want to see performance numbers similar to those documented, disable datachange notifications.
-The only way to do that in the POC is to change the code in ReadWriteTransactionImpl. Look for the FIXME comments.
-
-=== State of the POC +
-
-* Encoding and Decoding a Normalized Node into an Infinispan TreeCache works
-* Integrated with the controller
-* Eventing works
-* With Data Change events disabled, the Infinispan based datastore performs the same, or better than, the custom In-Memory Datastore. Although initially slow, with time it seems to perform more consistently than the In-Memory Datastore.,
-* Not fully tested
-
-=== Infinispan-related learnings +
-
-*Below par functioning of TreeCache#removeNode API* +
-The Infinispan removeNode API failed to remove nodes in the tree, as was promised, correctly. This means, for example, that when a mininet topology changes, some nodes may not be removed from inventory and topology.
-This behaviour has not been properly evaluated, and no remedy is currently available.
-
-=== Datastore-related learnings +
-
-*Multiple transactions can be created per thread* +
-This is a problem because if the backing datastore (infinispan) uses JTA transactions, only one transaction can be active per thread.
-Although this does not necessarily mean the usage of one thread per transaction, it calls for the suspension of one transaction and the resumption of another.
-TIP::
-* Allow only one active transaction per thread.
-* Add an explicit suspend or resume method to a transaction.
-
-=== No clarity on the closing of Read-Only transactions +
-For every DataStore transaction, a JTA transaction needs to be created. This is to ensure isolation (repeatable reads). When the transaction is done, it must be committed, rolled back, or closed in some fashion. Read-only transactions may not close. This leads to JTA transactions being open until they are timed out.
-
-TIP::
-
-* A DataStore may need to do time-outs as well.
-* Call _close_ explicitly for read-only transactions.
-
-==== Write and Delete methods in a read-write transaction do not return a Future
-The Write and Delete methods on the DOMWriteTransaction return a void instead of a Future, creating the impression that these methods are synchronous. This is not necessarily true in all cases: for example, in the infinispan datastore, the write was actually done in a separate thread to support multiple transactions on a single thread.
-TIP: Return a ListenableFuture for both Write and Delete methods.
-
-==== Expense of creating a DataChange event +
-Creating a DataChange event is very expensive because it needs to pass the Original Sub tree and the Modified Sub tree. +
-A NormalizedNode object needs to be created to create a DataChange event. The NormalizedNode object may be a snapshot of the complete modules data to facilitate the sending of the original subtree to DataChange listeners. The prohibitive expense prevents this implementation in every transaction. This is a problem not only in the infinispan datastore but also in a distributed system. A distributed system shards data to collocate it on a different node on the cluster with applications and datachange listeners. For example, while a system may have shards collocated with the inventory application; the topology application may be a datachange listener for datachange events. In this case, the original subtree and the modified sub tree would need to be serialized in some form, and sent to the topology listener.
-TIP: Remove the getOriginalSubtree and getModifiedSubtree methods from the datachange listener; understand the use case for providing them; and find a cheaper alternative.
-
-==== Complications of reconstructing a Normalized Node from different data-structures +
-The reconstruction of a Normalized Node from a different data-structure, like a map or a key-value store, is complicated or may appear complicated.
-A NormalizedNode is the binding-independent equivalent of data that gets stored in the datastore. For the in-memory datastore, it is the native storage format. It is a complicated structure that basically mirrors the model as defined in yang. Understanding it and properly decoding it could be a challenge for the implemention of an alternate datastore.
-TIP: Create utility classes to construct a normalized node from a simple tree structure. The Old CompositeNode or the Infinispan Node for example is a much simpler structure to follow.
-
-==== Comparison of In-Memory and Infinispan Datastore
-Cbench was used to compare the performance of the two datastores.
-To prepare the controller for testing: +
-
-IMPORTANT: Use the openflow plugin distribution.
-
-. Remove the simple forwarding, arp handler, and md-sal statistics manager bundles.
-. Set the log level to ERROR.
-. Run the controller with the following command: +
-: ./run.sh -Xmx4G -Xms2G -XX:NewRatio=5 -XX:+UseG1GC -XX:MaxPermSize=256m
-. From the osgi command prompt, use *dropAllPackets on*.
-
-==== Running cbench +
-For both the in-memory and infinispan datastore versions, cbench was run 11 times. The first run is ignored in both cases.
-
-* Use the cbench command: +
-: cbench -c <controller ip> -p 6633 -m 1000 -l 10 -s 16 -M 1000
-This was a latency test and the arguments roughly translate to this: +
-: -m 1000 : use 1000 milliseconds per test -l 10 : use 10 loops per test -s 16 : fake 16 switches -M 1000 : use 1000 hosts per switch
- </div>
-
-==== The results for In-Memory Datastore +
-To test the in-memory datastore, a pre-built openflow plugin distribution from Jenkins was downloadedon and on which was enabled the new in-memory datastore. +
-*In-Memory Datastore Results*
-[options="header",width="75%"]
-|===
-| Run | Min | Max | Avg | StdDev
-| 1 | 365 | 1049 | 715 | 04
-| 2 | 799 | 1044 | 953 | 71
-| 3 | 762 | 949 | 855 | 59
-| 4 | 616 | 707 | 666 | 27
-| 5 | 557 | 639 | 595 | 24
-| 6 | 510 | 583 | 537 | 25
-| 7 | 455 | 535 | 489 | 22
-| 8 | 351 | 458 | 420 | 38
-| 9 | 396 | 440 | 417 | 14
-| 10 | 376 | 413 | 392 | 13
-|===
-
-==== Infinispan Datastore +
-The Infinispan Datastore was built of a master a month old. Since the In-Memory datastore was hardcoded at that time the in-memory datastore was swapped for the the infinispan datastore by modifying the sal-broker-impl sources.
-
-
-Listed are some steps that were either completed to isolate the changes that were being made, or to tweak performance: +
-
-* Infinispan 5.3 was used because to isolate changes to utilize tree cache to the infinispan datastore bundles. Attempting to use version 6.0 caused a problem in loading some classes from infinispan.Ideally, to use infinispan as a backing store, tweak clustering services to obtain a treecache.
-* Added an exists method onto the In-Memory ReadTransaction API. This was because it was found that in one place in the BA Broker was code which checked for the existence of nodes in the tree by doing a read. Reads are a little expensive on the Infinispan datastore because of the need to convert to a NormalizedNode. An exists method was added to the interface to just check for node-existence.
-* When a transaction was used to read data it was not being closed causing the Infinispan JTA transactions to persist. Again, a change in the broker was made to close a transaction after it was concluded so that it dis not persist and trigger a clean by the reaper.
-
-*Infinispan Datastore Results*
-[cols="5*",^,options="header",width="75%"]
-|===
-| Run | Min | Max | Avg | StdDev
-| 1 | 43 | 250 | 186 | 61
-| 2 | 266 | 308 | 285 | 13
-| 3 | 300 | 350 | 325 | 12
-| 4 | 378 | 446 | 412 | 24
-| 5 | 609 | 683 | 644 | 26
-| 6 | 492 | 757 | 663 | 76
-| 7 | 794 | 838 | 816 | 11
-| 8 | 645 | 845 | 750 | 60
-| 9 | 553 | 829 | 708 | 100
-| 10 | 615 | 910 | 710 | 86
-|===
-
-=== OpenDaylight Controller configuration: FAQs
-==== Generic questions about the configuration subsystem
-*There is already JMX. Why do we need another system?*
-
-Java Management Extensions (JMX) provides programmatic access to management data, defining a clear structure on the level of a single object (MBeans). It provides the mechanism to query and set information exposed from these MBeans, too. It is adequate for replacing properties, but it does not treat the JVM container for what it is: a collection of applications working in concert. When the configuration problem is taken to the level of an entire system, there are multiple issues which JMX does not solve:
-
-* The need to validate that a proposed system is semantically valid before an attempt to change is made
-* The ability to synchronize modification multiple properties at the same time, such that both occur at the same time
-* The ability to express dependencies between applications
-* Machine-readable descriptions of layouts of configuration data
-
-*Why use YANG?*
-
-The problem of configuring a device has been tackled in https://ietf.org/[IETF] for many years now, initially using https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol[SNMP] (with https://en.wikipedia.org/wiki/Management_information_base[MIB] as the data definition language). While the protocol has been successful for monitoring devices, it has never gained traction as the unified way of configuring devices. The reasons for this have been https://tools.ietf.org/html/rfc3535[analyzed] and https://datatracker.ietf.org/doc/rfc6241/[NETCONF] was standardized as the successor protocol. NETCONF provides the abstractions to deal with configuration validation, and relies on http://tools.ietf.org/html/rfc6020[YANG] as its data modeling language. The configuration subsystem is designed to completely align with NETCONF such that it can be used as the native transport with minimal translation.
-
-=== OpenDaylight Controller configuration: Component map
-[cols="5,5a",^,options="header",width="75%"]
-|===
-| Component | Description
-| config-subsystem-core | Config subsystem core.
- Manages the configuration of the controller.
-
-Responsibilities:
-
-
-* Scanning of bundles for ModuleFactories.
-
-* Transactional management of lifecycle and dependency injection for config modules.
-
-* Exposure of modules and their configuration into JMX.
-| netty-config| Config modules for netty related resources, for example, netty-threadgroup, netty-timer and others.
-
-Contains config module definition in the form of yang schemas + generated code binding for the config subsystem.
-| controller-shutdown | Controller shutdown mechanism.
-
-Brings down the whole OSGi container of the controller.
-
-Authorization required in the form of a "secret string".
-
-Also contains config module definition in the form of yang schemas + generated code binding for the config subsystem. This makes it possible to invoke shutdown by means of the config-subsystem.
-| threadpool-config | Config modules for threading related resources, for example, threadfactories, fixed-threadpool, and others.
-
-Contains config module definition in the form of yang schemas + generated code binding for the config subsystem.
-| logback-config | Config modules for logging (logback) related resources, for example, loggers, appenders, and others.
-
-Contains config module definition in the form of yang schemas + generated code binding for the config subsystem.
-| netconf-config-dispatcher-config | Config modules for netconf-dispatcher(from netconf subsystem).
-
-Contains config module definition in the form of yang schemas + generated code binding for the config subsystem.
-| yang-jmx-config-generator | Maven plugin that generates the config subsystem code binding from provided yang schemas. This binding is required when the bundles want to participate in the config subsystem.
-| yang-jmx-config-generator-testing-modules | Testing resources for the maven plugin.
-| config-persister | Contains the api definition for an extensible configuration persister(database for controller configuration).
-
-The persister (re)stores the configuration for the controller. Persister implementation can be found in the netconf subsystem.
-
-The adapter bundles contain concrete implementations of storage extension. They store the config as xml files on the filesystem.
-| config-module-archetype | Maven archetype for "config subsystem aware" bundles.
-
-This archetype contains blueprints for yang-schemas, java classes, and other files(for example, pom.xml) required for a bundle to participate in the config subsystem.
-
-This archetype generates a bundle skeleton that can be developed into a full blown "config subsystem aware" bundle.
-|===
-
-=== OpenDaylight Controller: Netconf component map
-
-[cols="2", options="header", width="75%"]
-|===
-|Component | Description
-
-| netconf-server | Implementation of the generic (extensible) netconf server over tcp/ssh. Handles the general communication over the network, and forwards the rpcs to its extensions that implement the specific netconf rpc handles (For example: get-config).
-| netconf-to-config-mapping | API definition for the netconf server extension with the base implementation that transforms the netconf rpcs to java calls for the config-subsystem (config-subsystem netconf extension).
-| netconf-client | Netconf client basic implementation. Simple netconf client that supports netconf communication with remote netconf devices using xml format.
-| netconf-monitoring | Netconf-monitoring yang schemas with the implementation of a netconf server extension that handles the netconf-monitoring related handlers (For example: adding netconf-state to get rpc)
-| config-persister-impl | Extensible implementation of the config persister that persists the configuration in the form of xml,(easy to inject to edit-config rpc) and loads the initial configuration from the persisted files. The configuration is stored after every successful commit rpc.
-| netconf-cli | Prototype of a netconf cli.
-|===
-
-=== OpenDaylight Controller Configuration: Examples sample project
-*Sample maven project* +
-
-In this example, we will create a maven project that provides two modules, each implementing one service. We will design a simple configuration, as well as runtime data for each module using yang.
-A sample maven project called config-demo was created. This project contains two Java interfaces: Foo and Bar. Each interface has one default implementation per interface, FooImpl and BarImpl. Bar is the producer in our example and produces integers when the method getNextEvent() is called. Foo is the consumer, and its implementation depends on a Bar instance. Both implementations require some configuration that is injected by means of constructors.
-
-* Bar.java:
-----
-package org.opendaylight.controller.config.demo;
-
-public interface Bar {
-
- int getNextEvent();
-
-}
-----
-* BarImpl.java:
-----
-package org.opendaylight.controller.config.demo;
-
-public class BarImpl implements Bar {
-
- private final int l1, l2;
- private final boolean b;
-
- public BarImpl(int l1, int l2, boolean b) {
- this.l1 = l1;
- this.currentL = l1;
- this.l2 = l2;
- this.b = b;
- }
-
- private int currentL;
-
- @Override
- public int getNextEvent() {
- if(currentL==l2)
- return -1;
- return currentL++;
- }
-}
-----
-* Foo.java:
-----
-package org.opendaylight.controller.config.demo;
-
-public interface Foo {
-
- int getEventCount();
-}
-----
-* FooImpl.java:
-----
-package org.opendaylight.controller.config.demo;
-
-public class FooImpl implements Foo {
-
- private final String strAttribute;
- private final Bar barDependency;
- private final int intAttribute;
-
- public FooImpl(String strAttribute, int intAttribute, Bar barDependency) {
- this.strAttribute = strAttribute;
- this.barDependency = barDependency;
- this.intAttribute = intAttribute;
- }
-
- @Override
- public int getEventCount() {
- int count = 0;
- while(barDependency.getNextEvent() != intAttribute) {
- count++;
- }
- return count;
- }
-}
-----
-* pom.xml (config-demo project is defined as a sub-module of the controller project, and at this point contains only the configuration for maven-bundle-plugin):
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<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/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <artifactId>commons.opendaylight</artifactId>
- <groupId>org.opendaylight.controller</groupId>
- <version>1.4.1-SNAPSHOT</version>
- <relativePath>../commons/opendaylight/pom.xml</relativePath>
- </parent>
- <groupId>org.opendaylight.controller</groupId>
- <version>0.1.1-SNAPSHOT</version>
- <artifactId>config-demo</artifactId>
- <packaging>bundle</packaging>
- <name>${project.artifactId}</name>
- <prerequisites>
- <maven>3.0.4</maven>
- </prerequisites>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <version>2.4.0</version>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-Name>${project.groupId}.${project.artifactId}</Bundle-Name>
- <Export-Package>
- org.opendaylight.controller.config.demo,
- </Export-Package>
- </instructions>
- </configuration>
- </plugin>
- </plugins>
- </build>
-
-</project>
-----
-
-==== Describing the module configuration using yang
-In order to fully leverage the utilities of the configuration subsystem, we need to describe the services, modules, their configurations, and the runtime state using the yang modeling language. We will define two services and two modules, which will be used to configure the instances of FooImpl and BarImpl. This definition will be split into two yang files: config-demo.yang (service definition) and config-demo-impl.yang (module definition).
-
-* config-demo.yang
-----
-module config-demo {
- yang-version 1;
- namespace "urn:opendaylight:params:xml:ns:yang:controller:config:demo";
- prefix "demo";
-
- import config { prefix config; revision-date 2013-04-05; }
-
- description
- "Service definition for config-demo";
-
- revision "2013-10-14" {
- description
- "Initial revision";
- }
-
- // Service definition for service foo that encapsulates instances of org.opendaylight.controller.config.demo.Foo
- identity foo {
- description
- "Foo service definition";
-
- base "config:service-type";
- config:java-class "org.opendaylight.controller.config.demo.Foo";
- }
-
- identity bar {
- description
- "Bar service definition";
-
- base "config:service-type";
- config:java-class "org.opendaylight.controller.config.demo.Bar";
- }
-}
-----
-The config yang module needs to be imported in order to define the services. There are two services defined, and these services correspond to the Java interfaces Foo and Bar (specified by the config:java-class extension).
-
-* config-demo-impl.yang
-----
-module config-demo-impl {
-
- yang-version 1;
- namespace "urn:opendaylight:params:xml:ns:yang:controller:config:demo:java";
- prefix "demo-java";
-
- // Dependency on service definition for config-demo
- /* Service definitions could be also located in this yang file or even
- * in a separate maven project that is marked as maven dependency
- */
- import config-demo { prefix demo; revision-date 2013-10-14;}
-
- // Dependencies on config subsystem definition
- import config { prefix config; revision-date 2013-04-05; }
- import rpc-context { prefix rpcx; revision-date 2013-06-17; }
-
-
- description
- "Service implementation for config-demo";
-
- revision "2013-10-14" {
- description
- "Initial revision";
- }
- //----- module foo-impl ----- //
- // Module implementing foo service //
- identity foo-impl { //
- base config:module-type; //
- config:provided-service demo:foo; //
- config:java-name-prefix FooImpl; //
- } //
- //
- // Configuration for foo-impl module //
- augment "/config:modules/config:module/config:configuration" { //
- case foo-impl { //
- when "/config:modules/config:module/config:type = 'foo-impl'"; //
- //
- leaf str-attribute { //
- type string; //
- } //
- //
- leaf int-attribute { //
- type int32; //
- } //
- //
- //
- // Dependency on bar service instance //
- container bar-dependency { //
- uses config:service-ref { //
- refine type { //
- mandatory true; //
- config:required-identity demo:bar; //
- } //
- } //
- } //
- //
- } //
- } //
- //
- // Runtime state definition for foo-impl module //
- augment "/config:modules/config:module/config:state" { //
- case foo-impl { //
- when "/config:modules/config:module/config:type = 'foo-impl'"; //
- //
- //
- } //
- } //
- // ---------- //
- // Module implementing bar service
- identity bar-impl {
- base config:module-type;
- config:provided-service demo:bar;
- config:java-name-prefix BarImpl;
- }
-
- augment "/config:modules/config:module/config:configuration" {
- case bar-impl {
- when "/config:modules/config:module/config:type = 'bar-impl'";
-
- container dto-attribute {
- leaf int-attribute {
- type int32;
- }
-
- leaf int-attribute2 {
- type int32;
- }
-
- leaf bool-attribute {
- type boolean;
- }
- }
-
- }
- }
-
- augment "/config:modules/config:module/config:state" {
- case bar-impl {
- when "/config:modules/config:module/config:type = 'bar-impl'";
-
- }
- }
-
-}
-----
-The config yang module as well as the config-demo yang module need to be imported. There are two modules defined: foo-impl and bar-impl. Their configuration (defined in the augment "/config:modules/config:module/config:configuration" block) corresponds to the configuration of the FooImpl and BarImpl Java classes. In the constructor of FooImpl.java, we see that the configuration of foo-impl module defines three similar attributes. These arguments are used to instantiate the FooImpl class. These yang files are placed under the src/main/yang folder.
-
-==== Updating the maven configuration in pom.xml
-
-The yang-maven-plugin must be added to the pom.xml. This plugin will process the yang files, and generate the configuration code for the defined modules. Plugin configuration: +
-----
-<plugin>
- <groupId>org.opendaylight.yangtools</groupId>
- <artifactId>yang-maven-plugin</artifactId>
- <version>${yangtools.version}</version>
- <executions>
- <execution>
- <goals>
- <goal>generate-sources</goal>
- </goals>
- <configuration>
- <codeGenerators>
- <generator>
- <codeGeneratorClass>
- org.opendaylight.controller.config.yangjmxgenerator.plugin.JMXGenerator
- </codeGeneratorClass>
- <outputBaseDir>${project.build.directory}/generated-sources/config</outputBaseDir>
- <additionalConfiguration>
- <namespaceToPackage1>
- urn:opendaylight:params:xml:ns:yang:controller==org.opendaylight.controller.config.yang
- </namespaceToPackage1>
- </additionalConfiguration>
- </generator>
- </codeGenerators>
- <inspectDependencies>true</inspectDependencies>
- </configuration>
- </execution>
- </executions>
- <dependencies>
- <dependency>
- <groupId>org.opendaylight.controller</groupId>
- <artifactId>yang-jmx-generator-plugin</artifactId>
- <version>${config.version}</version>
- </dependency>
- </dependencies>
-</plugin>
-----
-The configuration important for the plugin: the output folder for the generated files, and the mapping between the yang namespaces and the java packages (Inspect dependencies must be set to true.). The default location for the yang files is under the src/main/yang folder. This plugin is backed by the artifact yang-jmx-generator-plugin and its class org.opendaylight.controller.config.yangjmxgenerator.plugin.JMXGenerator is responsible for code generation. This artifact is part of the configuration subsystem.
-
-In addition to the yang-maven-plugin, it is neccessary to add the build-helper-maven-plugin in order to add the generated sources to the build process:
-----
-<plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>build-helper-maven-plugin</artifactId>
- <version>1.8</version>
- <executions>
- <execution>
- <id>add-source</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>add-source</goal>
- </goals>
- <configuration>
- <sources>
- <source>${project.build.directory}/generated-sources/config</source>;
- </sources>
- </configuration>
- </execution>
- </executions>
-</plugin>
-----
-Earlier, the configuration yang module in the yang files was imported. In order to acquire this yang module, we need to add a dependency to the pom file:
-----
-<dependency>
- <groupId>org.opendaylight.controller</groupId>
- <artifactId>config-api</artifactId>
- <version>${config.version}</version>
-</dependency>
-----
-In addition, a couple of utility dependencies must be added:
-----
-<dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-api</artifactId>
-</dependency>
-<dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
-</dependency>
-----
-Run *mvn clean install*.
-
-==== Generated java files
-
-A set of new source files divided into two groups is seen. The first group is located under the ${project.build.directory}/generated-sources/config directory, which was specified in the yang-maven-plugin configuration. The second group is located under the src/main/java directory. Both groups then define the package org.opendaylight.controller.config.yang.config.demo.impl. The first group contains code that must not be edited in any way, since this code can be regenerated by the plugin if necessary. The code that needs to be edited belongs to the second group and is located under src/main/java.
-
-===== Generated config source files examples
-
-* BarImplModuleMXBean.java
-----
-public interface BarImplModuleMXBean
-{
- public org.opendaylight.controller.config.yang.config.demo.java.DtoAttribute getDtoAttribute();
-
- public void setDtoAttribute(org.opendaylight.controller.config.yang.config.demo.java.DtoAttribute dtoAttribute);
-
-}
-----
-The BarImplModuleMXBean interface represents the getter and the setter for dtoAttribute that will be exported to the configuration registry by means of JMX. The attribute was defined in the yang model: in this case, it is the composite type which was converted to OpenType.
-
-* Attribute definition from config-demo-impl.yang
-----
-// Module implementing bar service
- identity bar-impl {
- base config:module-type;
- config:provided-service demo:foo;
- config:java-name-prefix BarImpl;
- }
-
- augment "/config:modules/config:module/config:configuration" {
- case bar-impl {
- when "/config:modules/config:module/config:type = 'bar-impl'";
-
- container dto-attribute {
- leaf int-attribute {
- type int32;
- }
-
- leaf int-attribute2 {
- type int32;
- }
-
- leaf bool-attribute {
- type boolean;
- }
- }
-
- }
- }
-----
-From the container dto-attribute, the DtoAttribute java file was generated. The Class contains the plain constructor, and the getters and setters for the attributes defined as container leaves.
-Not only is ModuleMXBean generated from this module definition, but also BarImplModuleFactory and BarImplModule stubs (in fact AbstractBarImplModuleFactory and AbstractBarImplModule are generated too.).
-
-* AbstractBarImplModule.java +
-This abstract class is almost fully generated: only the method validate() has an empty body and the method createInstance() is abstract. The user must implement both methods by user. AbstractBarImplModule implements its ModuleMXBean, Module, RuntimeBeanRegistratorAwareModule, and the dependent service interface as defined in yang. Moreover, the class contains two types of constructors: one for the module created from the old module instance, and the second for module creation from scratch.
-
-* AbstractBarImplModuleFactory.java +
-Unlike AbstractModule, AbstractFactory is fully generated, but it is still an abstract class. The factory is responsible for module instances creation, and provides two type of instantiateModule methods for both module constructor types. It implements the ModuleFactory interface.
-
-Next, create the runtime bean for FooImplModule. Runtime beans are designated to capture data about the running module.
-
-* Add runtime bean definition to config-demo-impl.yang +
-
-===== Modifying generated sources
-
-Generated source files: +
-
-* src/main/java/**/BarImplModule
-* src/main/java/**/BarImplModuleFactory
-* src/main/java/**/FooImplModule
-* src/main/java/**/FooImplModuleFactory
-
-*BarImplModule* +
-We will start by modifying BarImplModule. Two constructors and two generated methods are seen:
-----
-@Override
- public void validate(){
- super.validate();
- // Add custom validation for module attributes here.
- }
-
- @Override
- public java.lang.AutoCloseable createInstance() {
- //TODO:implement
- throw new java.lang.UnsupportedOperationException("Unimplemented stub method");
- }
-----
-In *validate*, specify the validation for configuration attributes, for example:
-----
-@Override
- public void validate(){
- super.validate();
- Preconditions.checkNotNull(getDtoAttribute());
- Preconditions.checkNotNull(getDtoAttribute().getBoolAttribute());
- Preconditions.checkNotNull(getDtoAttribute().getIntAttribute());
- Preconditions.checkNotNull(getDtoAttribute().getIntAttribute2());
- Preconditions.checkState(getDtoAttribute().getIntAttribute() > getDtoAttribute().getIntAttribute2());
- }
-----
-In *createInstance* you need to create a new instance of the bar service => Bar interface, for example:
-----
-@Override
- public java.lang.AutoCloseable createInstance() {
- return new BarImpl(getDtoAttribute().getIntAttribute(), getDtoAttribute().getIntAttribute2(), getDtoAttribute()
- .getBoolAttribute());
- }
-----
-===== Notes:
-
-* createInstance returns AutoCloseable so the returned type needs to implement it. (You can make BarImpl implement AutoCloseable, or create a Wrapper class around the BarImpl instance that implements AutoCloseable, or even extend the BarImpl class and make it implement it.)
-* You can access all the configuration attributes by means of the getter methods.
-* In config-demo-impl.yang, we defined the bar-impl configuration as a container dto-attribute. The code generator creates a transfer object DtoAttribute that you can access by means of the getDtoAttribute() method, and retrieve configuration data from it. You can even add a new constructor to BarImpl that takes this transfer object, and reduces the number of arguments.
-
-*FooImplModule* +
-We will not add any custom validation in this module. The createInstance method will look as follows: +
-----
- @Override
- public java.lang.AutoCloseable createInstance() {
- return new FooImpl(getStrAttribute(), getIntAttribute(), getBarDependencyDependency());
- }
-----
-===== Adding support for default instances
-
-In order to provide a default instance of module bar-impl, we need to further modify the generated code by the overriding method getDefaultModules in src/main/java/**/BarImplModuleFactory class. The body of this class is empty thus far, and it inherits the default behaviour from its parent abstract factory. Use the following code to replace the empty body:
-----
-public static final ModuleIdentifier defaultInstance1Id = new ModuleIdentifier(NAME, "defaultInstance1");
-
- @Override
- public Set<BarImplModule> getDefaultModules(DependencyResolverFactory dependencyResolverFactory, BundleContext bundleContext) {
- DependencyResolver depResolver1 = dependencyResolverFactory.createDependencyResolver(defaultInstance1Id);
- BarImplModule defaultModule1 = new BarImplModule(defaultInstance1Id, depResolver1);
- defaultModule1.setDtoAttribute(getDefaultConfiguration(bundleContext));
-
- return Sets.newHashSet(defaultModule1);
- }
-
- private DtoAttribute getDefaultConfiguration(BundleContext bundleContext) {
- DtoAttribute defaultConfiguration = new DtoAttribute();
-
- String property = bundleContext.getProperty("default.bool");
- defaultConfiguration.setBoolAttribute(property == null ? false : Boolean.parseBoolean(property));
-
- property = bundleContext.getProperty("default.int1");
- defaultConfiguration.setIntAttribute(property == null ? 55 : Integer.parseInt(property));
-
- property = bundleContext.getProperty("default.int2");
- defaultConfiguration.setIntAttribute2(property == null ? 0 : Integer.parseInt(property));
-
- return defaultConfiguration;
- }
-----
-The _getDefaultModules_ method now produces an instance of the bar-impl module with the name _defaultInstance1_. (It is possible to produce multiple default instances since the return type is a Set of module instances.) Note the getDefaultConfiguration method. It provides the default configuration for default instances by trying to retrieve system properties from bundleContext (or provides hardcoded values in case the system property is not present).
-
-For the controller distribution, system properties can be fed by means of _config.ini_ file.
-
-The method _getDefaultModules_ is called automatically after a bundle containing this factory is started in the OSGi environment. Its default implementation returns an empty Set.
-
-The default instances approach is similar to the Activator class approach in OSGi with the advantage of default instances being managed by the configuration subsystem. This approach can either replace the Activator class approach, or be used along with it.
-
-*Verifying the default instances in distribution* +
-
-If we add the config-demo bundle to the opendaylight distribution, we can verify the presence of the default instance. The file pom.xml under the opendaylight/distribution/opendaylight folder needs to be modified by adding the config-demo dependency:
-----
-<dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>config-demo</artifactId>
- <version>0.1.1-SNAPSHOT</version>
-</dependency>
-----
-Now we need to rebuild the conf-demo module using mvn clean install. Then, we can build the distribution using the same mvn command under the _opendaylight/distribution/opendaylight_ folder. If we go to the _opendaylight/distribution/opendaylight/target/distribution.opendaylight-osgipackage/opendaylight_ folder, and execute run.sh, the opendaylight distribution should start.
-
-We can check the presence of the default instances by means of JMX using a tool such as _jvisualvm_.
-
-=== OpenDaylight Controller:Configuration examples user guide
-==== Configuring thread pools with yangcli-pro
-Requirements: yangcli-pro version 13.04-9.2 or later +
-
-===== Connecting to plaintext TCP socket and ssh
-Currently SSH is exposed by the controller. The network interface and port are configured in configuration/config.ini . The current configuration of netconf is as follows: +
-----
-# Netconf startup configuration
-#netconf.tcp.address=127.0.0.l
-#netconf.tcp.port=8383
-
-netconf.ssh.address=0.0.0.0
-netconf.ssh.port=1830
-----
-To connect the yangcli-pro client, use the following syntax: +
-----
-yangcli-pro --user=admin --password=admin --transport=ssh --ncport=1830 --server=localhost
-----
-If the plaintext TCP port is not commented out, one can use the following: +
-----
-yangcli-pro --user=a --password=a --transport=tcp --ncport=8383 --server=localhost
-----
-Authentication in this case is ignored.
-
-For better debugging, include following arguments: +
-----
---log=/tmp/yuma.log --log-level=debug4 --log-console
-----
-
-NOTE: When the log file is set, the output will not appear on stdout.
-
-===== Configuring threadfactory
-The threadfactory is a service interface that can be plugged into threadpools, defined in config-threadpool-api (see the https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blob;f=opendaylight/config/threadpool-config-api/src/main/yang/threadpool.yang;h=8f3064822be319dfee6fd7c7061c8bee14db268f;hb=refs/heads/master[yang file].
-The implementation to be used is called threadfactory-naming. This implementation will set a name for each thread created using a configurable prefix and auto incremented index. See the https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blob;f=opendaylight/config/threadpool-config-impl/src/main/yang/threadpool-impl.yang;h=a2366f285a0c0b8682b1093f18fb5ee184c9cde3;hb=refs/heads/master[Yang file].
-
-. Launch yangcli-pro and connect to the server.
-. Enter *get-config source=running* to see the current configuration. +
-Example output: +
-----
-rpc-reply {
- data {
- modules {
- module binding-broker-singleton {
- type binding-impl:binding-broker-impl-singleton
- name binding-broker-singleton
- }
- }
- services {
- service md-sal-binding:binding-broker-osgi-registry {
- type md-sal-binding:binding-broker-osgi-registry
- instance ref_binding-broker-singleton {
- name ref_binding-broker-singleton
- provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
- }
- }
- }
- }
-}
-----
-[start=3]
-. Enter the merge /modules/module.
-. At the prompt, enter the string value for the leaf <name>. This is the name of the config module. Enter threadfactory-bgp.
-. Set the identityref for the leaf <type>. Press Tab to see a list of available module names. Enter threadfactory-naming.
-. At the prompt, choose the case statement. Example output:
-----
- 1: case netty-threadgroup-fixed:
- leaf thread-count
- 2: case netty-hashed-wheel-timer:
- leaf tick-duration
- leaf ticks-per-wheel
- container thread-factory
- 3: case async-eventbus:
- container threadpool
- 4: case threadfactory-naming:
- leaf name-prefix
- 5: case threadpool-fixed:
- leaf max-thread-count
- container threadFactory
- 6: case threadpool-flexible:
- leaf max-thread-count
- leaf minThreadCount
- leaf keepAliveMillis
- container threadFactory
- 7: case threadpool-scheduled:
- leaf max-thread-count
- container threadFactory
- 8: case logback:
- list file-appenders
- list rolling-appenders
- list console-appenders
- list loggers
-----
-In this case, we chose 4. +
-[start=7]
-. Next fill in the string value for the leaf <name-prefix>. Enter bgp.
-: (You should get an OK response from the server.)
-[start=8]
-. Optionally issue get-config source=candidate to verify the change.
-. Issue commit.
-. Issue get-config source=running. Example output: +
-----
-rpc-reply {
- data {
- modules {
- module binding-broker-singleton {
- type binding-impl:binding-broker-impl-singleton
- name binding-broker-singleton
- }
- module threadfactory-bgp {
- type th-java:threadfactory-naming
- name threadfactory-bgp
- name-prefix bgp
- }
- }
- services {
- service th:threadfactory {
- type th:threadfactory
- instance ref_threadfactory-bgp {
- name ref_threadfactory-bgp
- provider /modules/module[type='threadfactory-naming'][name='threadfactory-bgp']
- }
- }
- service md-sal-binding:binding-broker-osgi-registry {
- type md-sal-binding:binding-broker-osgi-registry
- instance ref_binding-broker-singleton {
- name ref_binding-broker-singleton
- provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
- }
- }
- }
- }
-}
-----
-==== Configuring fixed threadpool
-
-Service interface threadpool is defined in the config-threadpool-api. The implementation used is called threadpool-fixed that is defined in config-threadpool-impl. This implementation creates a threadpool of fixed size. There are two mandatory attributes: size and dependency on a threadfactory.
-
-. Issue get-config source=running. As you can see in the last step of configuring threadfactory, /services/service, the node associated with it has instance name ref_threadfactory-bgp.
-. Issue merge /modules/module.
-. Enter the name bgp-threadpool.
-. Enter the type threadpool.
-. Select the appropriate case statement.
-. Enter the value for leaf <max-thread-count>: 100.
-. Enter the threadfactory for attribute threadfactory/type. This is with reference to /services/service/type, in other words, the service interface.
-. Enter ref_threadfactory-bgp.
-Server response must be an OK message.
-[start=9]
-. Issue commit.
-. Issue get-config source=running.
-Example output: +
-----
-rpc-reply {
- data {
- modules {
- module binding-broker-singleton {
- type binding-impl:binding-broker-impl-singleton
- name binding-broker-singleton
- }
- module bgp-threadpool {
- type th-java:threadpool-fixed
- name bgp-threadpool
- threadFactory {
- type th:threadfactory
- name ref_threadfactory-bgp
- }
- max-thread-count 100
- }
- module threadfactory-bgp {
- type th-java:threadfactory-naming
- name threadfactory-bgp
- name-prefix bgp
- }
- }
- services {
- service th:threadpool {
- type th:threadpool
- instance ref_bgp-threadpool {
- name ref_bgp-threadpool
- provider /modules/module[type='threadpool-fixed'][name='bgp-threadpool']
- }
- }
- service th:threadfactory {
- type th:threadfactory
- instance ref_threadfactory-bgp {
- name ref_threadfactory-bgp
- provider /modules/module[type='threadfactory-naming'][name='threadfactory-bgp']
- }
- }
- service md-sal-binding:binding-broker-osgi-registry {
- type md-sal-binding:binding-broker-osgi-registry
- instance ref_binding-broker-singleton {
- name ref_binding-broker-singleton
- provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
- }
- }
- }
- }
-}
-----
-To see the actual netconf messages, use the logging arguments described at the top of this page. To validate that a threadpool has been created, a tool like VisualVM can be used.
-
-==== Logback configuration - Yuma
-This approach to configure logback will utilize a 3rd party cli netconf client from Yuma. We will modify existing console appender in logback and then call reset rpc on logback to clear its status list.
-
-For initial configuration of the controller and startup parameters for yuma, see the threadpool example: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Threadpool[Threadpool configuration using Yuma].
-
-Start the controller and yuma cli client as in the previous example.
-
-There is no need to initialize the configuration module wrapping logback manually, since it creates a default instance. Therefore you should see the output containing logback configuration after the execution of get-config source=running command in yuma:
-----
-rpc-reply {
- data {
- modules {
- module singleton {
- type logging:logback
- name singleton
- console-appenders {
- threshold-filter ERROR
- name STDOUT
- encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{36} - %msg%n'
- }
- file-appenders {
- append true
- file-name logs/audit.log
- name audit-file
- encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n'
- }
- loggers {
- level WARN
- logger-name org.opendaylight.controller.logging.bridge
- }
- loggers {
- level INFO
- logger-name audit
- appenders audit-file
- }
- loggers {
- level ERROR
- logger-name ROOT
- appenders STDOUT
- appenders opendaylight.log
- }
- loggers {
- level INFO
- logger-name org.opendaylight
- }
- loggers {
- level WARN
- logger-name io.netty
- }
- rolling-appenders {
- append true
- max-file-size 10MB
- file-name logs/opendaylight.log
- name opendaylight.log
- file-name-pattern logs/opendaylight.%d.log.zip
- encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n'
- clean-history-on-start false
- max-history 1
- rolling-policy-type TimeBasedRollingPolicy
- }
- }
- module binding-broker-singleton {
- type binding-impl:binding-broker-impl-singleton
- name binding-broker-singleton
- }
- }
- services {
- service md-sal-binding:binding-broker-osgi-registry {
- type md-sal-binding:binding-broker-osgi-registry
- instance ref_binding-broker-singleton {
- name ref_binding-broker-singleton
- provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
- }
- }
- }
- }
-}
-----
-
-===== Modifying existing console appender in logback
-. Start edit-config with merge option:
-----
-merge /modules/module
-----
-[start=2]
-. For Name of the module, enter *singleton*.
-. For Type, enter *logback*.
-. Pick the corresponding case statement with the name logback.
-We do not want to modify file-appenders, rolling-appenders and loggers lists, so the answer to questions from yuma is N (for no):
-----
-Filling optional case /modules/module/configuration/logback:
-Add optional list 'file-appenders'?
-Enter Y for yes, N for no, or C to cancel: [default: Y]
-----
-[start=5]
-. As we want to modify console-appenders, the answer to the question from Yuma is Y:
-----
-Filling optional case /modules/module/configuration/logback:
-Add optional list 'console-appenders'?
-Enter Y for yes, N for no, or C to cancel: [default: Y]
-----
-[start=6]
-. This will start a new configuration process for console appender and we will fill following values:
-
-* <encoder-pattern> %date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n
-* <threshold-filter> INFO
-* <name> STDOUT
-[start=7]
-. Answer N to the next question.
-----
-Add another list?
-Enter Y for yes, N for no, or C to cancel: [default: N]
-----
-Notice that we changed the level for threshold-filter for STDOUT console appender from ERROR to INFO. Now issue a commit command to commit the changed configuration, and the response from get-config source=running command should look like this:
-----
-rpc-reply {
- data {
- modules {
- module singleton {
- type logging:logback
- name singleton
- console-appenders {
- threshold-filter INFO
- name STDOUT
- encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{36} - %msg%n'
- }
- file-appenders {
- append true
- file-name logs/audit.log
- name audit-file
- encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} %msg %n'
- }
- loggers {
- level WARN
- logger-name org.opendaylight.controller.logging.bridge
- }
- loggers {
- level INFO
- logger-name audit
- appenders audit-file
- }
- loggers {
- level ERROR
- logger-name ROOT
- appenders STDOUT
- appenders opendaylight.log
- }
- loggers {
- level INFO
- logger-name org.opendaylight
- }
- loggers {
- level WARN
- logger-name io.netty
- }
- rolling-appenders {
- append true
- max-file-size 10MB
- file-name logs/opendaylight.log
- name opendaylight.log
- file-name-pattern logs/opendaylight.%d.log.zip
- encoder-pattern '%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n'
- clean-history-on-start false
- max-history 1
- rolling-policy-type TimeBasedRollingPolicy
- }
- }
- module binding-broker-singleton {
- type binding-impl:binding-broker-impl-singleton
- name binding-broker-singleton
- }
- }
- services {
- service md-sal-binding:binding-broker-osgi-registry {
- type md-sal-binding:binding-broker-osgi-registry
- instance ref_binding-broker-singleton {
- name ref_binding-broker-singleton
- provider /modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']
- }
- }
- }
- }
-}
-----
-==== Invoking RPCs
-*Invoking Reset RPC on logback* +
-The configuration module for logback exposes some information about its current state(list of logback status messages). This information can be accessed using get netconf operation or get command from yuma. Example response after issuing get command in yuma:
-----
-rpc-reply {
- data {
- modules {
- module singleton {
- type logging:logback
- name singleton
- status {
- message 'Found resource [configuration/logback.xml] at
-[file:/.../controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-
-osgipackage/opendaylight/configuration/logback.xml]'
- level INFO
- date 2479534352
- }
- status {
- message 'debug attribute not set'
- level INFO
- date 2479534441
- }
- status {
- message 'Will scan for changes in
-[[/.../controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-
-osgipackage/opendaylight/configuration/logback.xml]]
-every 60 seconds.'
- level INFO
- date 2479534448
- }
- status {
- message 'Adding ReconfigureOnChangeFilter as a turbo filter'
- level INFO
- date 2479534448
- }
- ...
-----
-Logback also exposes an rpc called reset that wipes out the list of logback status messages and to invoke an rpc with name reset on module named singleton of type logback, following command needs to be issued in yuma:
-----
-reset context-instance="/modules/module[type='logback' and name='singleton']"
-----
-After an ok response, issuing get command should produce response with empty logback status message list:
-----
-rpc-reply {
- data {
- modules {
- module singleton {
- type logging:logback
- name singleton
- }
- }
- }
-}
-----
-This response confirms successful execution of the reset rpc on logback.
-
-*Invoking shutdown RPC* +
-This command entered in yuma will shut down the server. If all bundles do not stop correctly within 10 seconds, it will force the process to exit.
-----
-shutdown context-instance="/modules/module[type='shutdown' and name='shutdown']",input-secret="",max-wait-time="10000",reason="reason"
-----
-=== OpenDaylight Controller Configuration: Logback Examples
-==== Logback Configuration Example
-
-The Logback logger configuration is part of the config subsystem. This module allows changes to the Logback configuration at runtime. It is used here as an example to demonstrate the YANG to Java code generator and to show how the configuration transaction works.
-
-==== Java code generation
-The logging configuration YANG module definition can be found in the config-logging.yang file. The code is generated by the yang-maven-plugin and yang-jmx-generator-plugin. The output java files are located as defined in the plugin configuration, where additional configuration parameters can be set. The logback module is defined as identity, with the base "config:module-type"; it does not provide or depend on any service interface.
-----
-identity logback {
- description
- "Actual state of logback configuration.";
- base config:module-type;
- config:java-name-prefix Logback;
-}
-----
-The next logback module attributes are defined in the "/config:modules/config:module/config:configuration" augment as the snippet below shows.
-----
-augment "/config:modules/config:module/config:configuration" {
- case logback {
- when "/config:modules/config:module/config:type = 'logback'";
-
- list console-appenders {
-
- leaf encoder-pattern {
- type string;
- mandatory true;
- }
-
- leaf threshold-filter {
- type string;
- default 'ALL';
- }
-
- leaf name {
- type string;
- mandatory true;
- }
- config:java-name-prefix ConsoleAppenderTO;
- }
- ...
-----
-Now LogbackModule and LogbackModuleFactory can be generated. In fact, three more java files related to this module will be generated. By the augment definition, TypeObjects too are generated (that is to say, ConsoleAppenderTO). They are regular java classes with getters and setters for arguments defined as leaves.
-
-* *LogbackModuleMXBean* is the interface containing getters and setters for attributes defined in the configuration augment.
-* *AbstractLogbackModule* is the abstract java class, which implements Module, RuntimeBeanRegistratorAwareModule, and LogbackModuleMXBean. It contains almost all functionality, except validate and createInstance methods.
-* *AbstractLogbackModuleFactory* is the abstract java class responsible for creating module instances. It implements the ModuleFactory interface.
-* *LogbackModule* class extends AbstractLogbackModule. It is located in a different place (source/main/java) and can be modified by the user, so that the abstract method is implemented and the validate method is overridden.
-* *LogbackModuleFactory* class extends AbstractLogbackModuleFactory and overrides its instantiateModule methods.
-Next, the runtime bean is defined in the "/config:modules/config:module/config:state" augment. +
-----
-augment "/config:modules/config:module/config:state" {
- case logback {
- when "/config:modules/config:module/config:type = 'logback'";
-
- rpcx:rpc-context-instance "logback-rpc";
-
- list status {
- config:java-name-prefix StatusTO;
-
- leaf level {
- type string;
- }
-
- leaf message {
- type string;
- }
-
- leaf date {
- type uint32;
- }
- }
- }
-}
-----
-* The *Generator* plugin creates another set of java files.
-* *LogbackRuntimeMXBean* is the interface extending RuntimeBean. It contains the getter method for the argument defined in the augment.
-* *LogbackRuntimeRegistrator* class serves as the registrator for runtime beans.
-* *LogbackRuntimeRegistration* class serves as the registration ticket. An instance is returned after registration.
-
-The Logback config also defines logback-rpc with the reset method. It is also defined in the state augment, owing to the context.
-----
-identity logback-rpc;
-rpc reset {
- input {
- uses rpcx:rpc-context-ref {
- refine context-instance {
- rpcx:rpc-context-instance logback-rpc;
- }
- }
- }
-}
-----
-The Reset method is defined in the LogbackRuntimeMXBean interface.
-
-==== Logback configuration: Jolokia
-
-To create configuration on the running OSGi server: Jolokia (http://www.jolokia.org/) is used as a JMX-HTTP bridge, which listens at http://localhost:8080/controller/nb/v2/jolokia and curl to request over HTTP.
-
-. Start the controller. Find more here: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Pulling,_Hacking,_and_Pushing_the_Code_from_the_CLI
-. Request Jolokia:
-----
-curl http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
-----
-The response must resemble the following: +
-----
-{
- "timestamp": 1382425537,
- "status": 200,
- "request": {
- "type": "version"
- },
- "value": {
- "protocol": "7.0",
- "agent": "1.1.1",
- "info": {
- "product": "equinox",
- "vendor": "Eclipse",
- "version": "3.8.1.v20120830-144521"
- }
- }
-}
-----
-Jolokia is working.
-To configure Logback, first, create a configuration transaction. ConfigResgistryModule offers the operation beginConfig(), and to invoke it:
-----
-curl -X POST -H "Content-Type: application/json" -d '{"type":"exec","mbean":"org.opendaylight.controller:type=ConfigRegistry","arguments":[],"operation":"beginConfig"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
-----
-The configuration transaction was created. The response received: +
-----
-{
- "timestamp": 1383034210,
- "status": 200,
- "request": {
- "operation": "beginConfig",
- "mbean": "org.opendaylight.controller:type=ConfigRegistry",
- "type": "exec"
- },
- "value": {
- "objectName": "org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,type=ConfigTransaction"
- }
-}
-----
-At this stage, the transaction can be aborted, but we want to create the module bean to be configured. In the created ConfigTransaction call createModule method, the module identifier is logback, and the name must be singleton as only one instance of the Logback configuration is needed.
-----
-curl -X POST -H "Content-Type: application/json" -d '{"type":"exec","mbean":"org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,type=ConfigTransaction","arguments":["logback","singleton"],"operation":"createModule"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
-----
-The LogbackModule bean was created. The response returned:
-----
-{
- "timestamp": 1383034580,
- "status": 200,
- "request": {
- "operation": "createModule",
- "mbean": "org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,type=ConfigTransaction",
- "arguments": [
- "logback",
- "singleton"
- ],
- "type": "exec"
- },
- "value": {
- "objectName": "org.opendaylight.controller:TransactionName=ConfigTransaction-1-2,instanceName=singleton,moduleFactoryName=logback,type=Module"
- }
-}
-----
-* The configuration bean attributes are set to values obtained from the loggers configuration, with which the server was started. To see attributes, request:
-----
-curl -X POST -H "Content-Type: application/json" -d '{"type":"read", "mbean":"org.opendaylight.controller:instanceName=singleton,TransactionName=ConfigTransaction-1-2,type=Module,moduleFactoryName=logback"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
-----
-In the response body, the value contains all attributes (CompositeData) and its nested attribute values.
-* Now, the proposed configuration can be committed.
-----
-curl -X POST -H "Content-Type: application/json" -d '{"type":"exec","mbean":"org.opendaylight.controller:type=ConfigRegistry","arguments":["org.opendaylight.controller:instanceName=singleton,TransactionName=ConfigTransaction-1-2,type=Module,moduleFactoryName=logback"],"operation":"commitConfig"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
-----
-The configuration was successfully validated and committed, and the module instance created.
-----
-{
- "timestamp": 1383034793,
- "status": 200,
- "request": {
- "operation": "commitConfig",
- "mbean": "org.opendaylight.controller:type=ConfigRegistry",
- "arguments": [
- "org.opendaylight.controller:instanceName=singleton,TransactionName=ConfigTransaction-1-2,type=Module,moduleFactoryName=logback"
- ],
- "type": "exec"
- },
- "value": {
- "newInstances": [
- {
- "objectName": "org.opendaylight.controller:instanceName=singleton,moduleFactoryName=logback,type=Module"
- }
- ],
- "reusedInstances": [],
- "recreatedInstances": []
- }
-}
-----
-* The runtime bean was registered, and can provide the status information of the configuration and rpc operation reset. To see the status, try requesting:
-----
-curl -X POST -H "Content-Type: application/json" -d '{"type":"read","mbean":"org.opendaylight.controller:instanceName=singleton,type=RuntimeBean,moduleFactoryName=logback"}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
-----
-The entire logback status is in the response body.
-
-* To invoke the rpc method reset:
-----
-curl -X POST -H "Content-Type: application/json" -d '{"type":"exec",
-"mbean":"org.opendaylight.controller:instanceName=singleton,type=RuntimeBean,moduleFactoryName=logback",
-"operation":"reset","arguments":[]}' http://localhost:8080/controller/nb/v2/jolokia --user admin:admin
-----
-The answer:
-----
-{
- "timestamp": 1383035001,
- "status": 200,
- "request": {
- "operation": "reset",
- "mbean": "org.opendaylight.controller:instanceName=singleton,moduleFactoryName=logback,type=RuntimeBean",
- "type": "exec"
- },
- "value": null
-}
-----
-Now, the runtime bean status attribute will be empty:
-----
-{
- "timestamp": 1383035126,
- "status": 200,
- "request": {
- "mbean": "org.opendaylight.controller:instanceName=singleton,moduleFactoryName=logback,type=RuntimeBean",
- "type": "read"
- },
- "value": {
- "StatusTO": []
- }
-}
-----
-==== Logback configuration: Netconf
-
-In this case, NETCONF RPCs are used to configure logback. The Netconf server listens at port 8383. To communicate over TCP, telnet is used. More about NETCONF is available at: http://tools.ietf.org/html/rfc6241. Netconf implementation is a part of the Controller - netconf-subsystem. The RPCs of Netconf are XML, and the operations are mapped to JMX operations.
-* A server re-start is required. The procedure is the same as above.
-* Open a terminal and connect to the server:
-----
-telnet localhost 8383
-----
-A Hello message received from the server contains the server capabilities and session-id. To establish connection to the client,send a hello message:
-----
-<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <capabilities>
- <capability>urn:ietf:params:netconf:base:1.0</capability>
- </capabilities>
-</hello>
-]]>]]>
-----
-* With the connection created, the client and server can communicate. To see the running modules and services, send an RPC to the server:
-----
-<rpc id="a" a="64" xmlnx="a:b:c:d" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
- <get-config>
- <source>
- <running/>
- </source>
- </get-config>
-</rpc>
-]]>]]>
-----
-
-* To configure logback, create a configuration transaction, and create a configuration module. It can be done in one step (in client point of view):
-----
-<rpc message-id="a" a="64" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <edit-config>
- <target>
- <candidate/>
- </target>
- <default-operation>merge</default-operation>
- <config>
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <name>singleton</name>
- <type xmlns:logging="urn:opendaylight:params:xml:ns:yang:controller:logback:config">
- logging:logback
- </type>
- </module>
- </modules>
- </config>
- </edit-config>
-</rpc>
-]]>]]>
-----
-
-If the configuration worked, the client receives a positive response:
-
-----
-<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
-<ok/>
-</rpc-reply>
-]]>]]>
-----
-
-* The Logback configuration bean attributes contain values loaded from the running Logback configuration. Send a request to the server with an RPC:
-----
-<rpc id="a" a="64" xmlnx="a:b:c:d" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
- <get-config>
- <source>
- <candidate/>
- </source>
- </get-config>
-</rpc>
-]]>]]>
-----
-
-* The reply includes the entire configuration that started the server. Assume that we want to change the RollingFileAppender named opendaylight.log attributes - maxFileSize, filename, and maxHistory. ( attribute of TimeBasedRollingPolicy). The proposed configuration:
-
-----
-<rpc message-id="a" a="64" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <edit-config>
- <target>
- <candidate/>
- </target>
- <default-operation>merge</default-operation>
- <config>
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <name>singleton</name>
- <type xmlns:logging="urn:opendaylight:params:xml:ns:yang:controller:logback:config">
- logging:logback
- </type>
- <rolling-appenders xmlns="urn:opendaylight:params:xml:ns:yang:controller:logback:config">
- <append>true</append>
- <max-file-size>5MB</max-file-size>
- <file-name>logs/opendaylight-new.log</file-name>
- <name>opendaylight.log</name>
- <file-name-pattern>logs/opendaylight.%d.log.zip</file-name-pattern>
- <encoder-pattern>%date{"yyyy-MM-dd HH:mm:ss.SSS z"} [%thread] %-5level %logger{35} - %msg%n</encoder-pattern>
- <clean-history-on-start>false</clean-history-on-start>
- <max-history>7</max-history>
- <rolling-policy-type>TimeBasedRollingPolicy</rolling-policy-type>
- </rolling-appenders>
- </module>
- </modules>
- </config>
- </edit-config>
-</rpc>
-]]>]]>
-----
-This configuration is merged with the proposed module configuration. If it passes the validation process successfully, an "ok" reply is received.
-
-* The configuration bean is ready to be committed:
-----
-<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
- <commit></commit>
-</rpc>
-]]>]]>
-----
-If successful, the ok message is received obtained, and the logback configuration is set. To verify, look into the logs directory to find a new log file named opendaylight-new.log
-
-* Correctly close the session with the session-id:
-----
-<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <close-session xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"/>
-</rpc>
-]]>]]>
-----
-===== Logback configuration - Yuma
-
-For a yangcli-pro example, see the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:User_guide[user guide].
-
-=== Opendaylight Controller: Configuration Logback.xml
-Logging in ODL container is done by means of http://logback.qos.ch/[Logback]. Comprehensive documentation is available at http://logback.qos.ch/documentation.html.
-
-By default, logging messages are appended to stdout of the java process and to file logs/opendaylight.log. When debugging a problem it might be useful to increase logging level:
-----
-<logger name="org.opendaylight.controller" level="DEBUG"/>
-----
-Logger tags can be appended under root node <configuration/>. Name of logger is used to select all loggers to which specified rules should apply. Loggers are usually named after class in which they reside. The example above matches all loggers in controller - they all are starting with org.opendaylight.controller . There are 5 logging levels: TRACE,DEBUG,INFO, WARN, ERROR. Additionally one can specify which appenders should be used for given loggers. This might be helpful to redirect certain log messages to another file or send them to syslog or over SMTP.
-== OpenDaylight Controller Configuration: Examples of Threadpool
-
-=== Configuration example of thread pools using yangcli-pro
-
-For a yangcli-pro example, see the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:User_guide[Examples User Guide].
-
-=== Configuration example of thread pools using telnet
-It is also possible to manipulate the configuration without the yuma cli. With just a telnet or ssh connection, it is possible to send the plain text containing netconf rpcs encoded in the xml format and achieve the same results as with yuma cli.
-
-This example reproduces the configuration of a threadpool and a threadfactory from the previous example using just a telnet connection. We can also use ssh connection, with the netconf rpcs sending procedure remaining the same. For detailed information about initial configuration for the controller as well as the configuration process, see the example using yuma cli.
-
-=== Connecting to plaintext TCP socket
-
-. Open a telnet connection:
-----
-telnet 127.0.0.1 8383
-----
-[start=2]
-. Open an ssh connection:
-----
-ssh netconf@127.0.0.1 -p 1830 -s netconf
-----
-The password for user netconf is : netconf, and the separator for the messages is: +
-----
-]]>]]>
-----
-Every message needs end with these 6 characters.
-
-The server sends a hello message: +
-----
-<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
-<capabilities>
-<capability>urn:ietf:params:netconf:base:1.0</capability>
-<capability>urn:ietf:params:netconf:capability:exi:1.0</capability>
-<capability>urn:opendaylight:l2:types?module=opendaylight-l2-types&revision=2013-08-27</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:netty:threadgroup?module=threadgroup&revision=2013-11-07</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding?module=opendaylight-md-sal-binding&revision=2013-10-28</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:threadpool?module=threadpool&revision=2013-04-09</capability>
-<capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:config?module=config&revision=2013-04-05</capability>
-<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring?module=ietf-netconf-monitoring&revision=2010-10-04</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:netty:eventexecutor?module=netty-event-executor&revision=2013-11-12</capability>
-<capability>urn:ietf:params:xml:ns:yang:rpc-context?module=rpc-context&revision=2013-06-17</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl?module=opendaylight-sal-binding-broker-impl&revision=2013-10-28</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:netty:timer?module=netty-timer&revision=2013-11-19</capability>
-<capability>urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2010-09-24</capability>
-<capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl?module=threadpool-impl&revision=2013-04-05</capability>
-<capability>urn:ietf:params:xml:ns:yang:ietf-yang-types?module=ietf-yang-types&revision=2010-09-24</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:logback:config?module=config-logging&revision=2013-07-16</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:iana?module=iana&revision=2013-08-16</capability>
-<capability>urn:opendaylight:yang:extension:yang-ext?module=yang-ext&revision=2013-07-09</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:controller:netty?module=netty&revision=2013-11-19</capability>
-<capability>http://netconfcentral.org/ns/toaster?module=toaster&revision=2009-11-20</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:ieee754?module=ieee754&revision=2013-08-19</capability>
-<capability>urn:opendaylight:params:xml:ns:yang:nps-concepts?module=nps-concepts&revision=2013-09-30</capability>
-</capabilities>
-
-<session-id>4</session-id>
-</hello>
-]]>]]>
-----
-[start=3]
-. As the client, you must respond with a hello message:
-----
-<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <capabilities>
- <capability>urn:ietf:params:netconf:base:1.0</capability>
- </capabilities>
-</hello>
-]]>]]>
-----
-Although there is no response to the hello message, the session is already established.
-
-=== Configuring threadfactory
-
-. The following is the Xml equivalent to *get-config source=running*: +
-----
-<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
- <get-config>
- <source>
- <running/>
- </source>
- </get-config>
-</rpc>
-]]>]]>
-----
-The response containing the current configuration: +
-----
-<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
- <data>
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-broker-impl-singleton</type>
- <name>binding-broker-singleton</name>
- </module>
- </modules>
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
- <instance>
- <name>ref_binding-broker-singleton</name>
- <provider>/modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']</provider>
- </instance>
- </service>
- </services>
- </data>
-</rpc-reply>]]>]]>
-----
-[start=2]
-. To create an instance of threadfactory-naming with the name threadfactory-bgp, and the attribute name-prefix set to bgp, send the message:
-----
-<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <edit-config>
- <target>
- <candidate/>
- </target>
- <default-operation>merge</default-operation>
- <config>
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" nc:operation="merge">
- <name>threadfactory-bgp</name>
- <type xmlns:th-java="urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl">th-java:threadfactory-naming</type>
- <name-prefix xmlns="urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl">bgp</name-prefix>
- </module>
- </modules>
- </config>
- </edit-config>
-</rpc>]]>]]>
-----
-[start=3]
-. To commit the threadfactory instance, send a commit message:
-----
-<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <commit/>
-</rpc>]]>]]>
-----
-The Netconf endpoint should respond with ok to edit-config, as well as the commit message: +
-
-----
-<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
- <ok/>
-</rpc-reply>]]>]]>
-----
-[start=4]
-. The response to the get-config message (the same as the first message sent in this example) should contain the commited instance of threadfactory-naming:
-----
-<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
- <data>
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding:impl">prefix:binding-broker-impl-singleton</type>
- <name>binding-broker-singleton</name>
- </module>
-
- <module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl">prefix:threadfactory-naming</type>
- <name>threadfactory-bgp</name>
- <name-prefix xmlns="urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl">bgp</name-prefix>
- </module>
- </modules>
-
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:threadfactory</type>
- <instance>
- <name>ref_threadfactory-bgp</name>
- <provider>/modules/module[type='threadfactory-naming'][name='threadfactory-bgp']</provider>
- </instance>
- </service>
- <service>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
- <instance>
- <name>ref_binding-broker-singleton</name>
- <provider>/modules/module[type='binding-broker-impl-singleton'][name='binding-broker-singleton']</provider>
- </instance>
- </service>
- </services>
- </data>
-</rpc-reply>]]>]]>
-----
-=== Configuring fixed threadpool
-
-* To create an instance of *threadpool-fixed* , with the same configuration and the same dependency as before, send the following message:
-
-----
-<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
- <edit-config>
- <target>
- <candidate/>
- </target>
- <default-operation>merge</default-operation>
- <config>
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <module xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" nc:operation="merge">
- <name>bgp-threadpool</name>
- <type xmlns:th-java="urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl">th-java:threadpool-fixed</type>
- <max-thread-count xmlns="urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl">100</max-thread-count>
- <threadFactory xmlns="urn:opendaylight:params:xml:ns:yang:controller:threadpool:impl">
- <type xmlns:th="urn:opendaylight:params:xml:ns:yang:controller:threadpool">th:threadfactory</type>
- <name>ref_th-bgp</name>
- </threadFactory>
- </module>
- </modules>
-
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:threadfactory</type>
- <instance>
- <name>ref_th-bgp</name>
- <provider>/modules/module[type='threadfactory-naming'][name='threadfactory-bgp']</provider>
- </instance>
- </service>
- </services>
- </config>
- </edit-config>
-</rpc>]]>]]>
-----
-Notice the _services_ tag. If an instance is to be referenced as a dependency by another module, it needs to be placed under this tag as a service instance with a unique reference name. Tag _provider_ points to a unique instance that is already present in the config subsystem, or is created within the current edit-config operation.
-The tag _name_ contains the reference name that can be referenced by other modules to create a dependency. In this case, a new instance of threadpool uses this reference in its configuration under the _threadFactory_ tag).
-
-You should get an ok response again, and the configuration subsystem will inject the dependency into the threadpool. Now you can commit the configuration (ok response once more) and the process is finished. The config subsystem is now in the same state as it was at the end of the previous example.
-
-=== OpenDaylight Controller MD-SAL: Model reference
-
-A full list of models, with links to the yang, descriptions, JavaDoc and REST APIs, see the OpenDaylight wiki page here: https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Model_Reference
-
-////
-==== Model reference
-
-===== Yang extensions
-[cols="5*",^]
-|===
-| Model | Description | ODL component 2+^| API definition
-
-|https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/yang-ext/src/main/yang/yang-ext.yang;a=blob[yang-ext.yang] | Yang Extensions for OpenDaylight | https://wiki.opendaylight.org/view/YANG_Tools:Main[YANG Tools]
-| https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/yang-ext/target/apidocs/index.html[Javadoc] | https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/yang-ext/target/site/restconf/yang-ext.html[REST]
-|===
-===== Base types
-
-[options="header"]
-|===
-| Model | Description | ODL component | API definition
-| https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=concepts/src/main/yang/iana.yang;a=blob[iana.yang] | IANA definition of private enterprise number | https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS\PCEP] | --| --
-| https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/iana/iana-afn-safi/src/main/yang/iana-afn-safi@2013-07-04.yang;a=blob[iana-afn-safi yang] | Definitions for the 'AFN' and 'SAFI' IANA-registered enumerations http://datatracker.ietf.org/doc/draft-ietf-netmod-iana-afn-safi/[Draft] | https://wiki.opendaylight.org/view/YANG_Tools:Main[Yang tools] | https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/iana/iana-afn-safi/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/iana/iana-afn-safi/target/site/restconf/iana-afn-safi.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/iana/iana-if-type/src/main/yang/iana-if-type@2013-07-04.yang;a=blob[iana-if-type yang] | Definitions for IANA-registered interface types http://datatracker.ietf.org/doc/rfc7224/[Draft-ietf-netmod-iana-if-type]| https://wiki.opendaylight.org/view/YANG_Tools:Main[Yang tools]| https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/iana/iana-if-type/target/apidocs/index.html[JavaDoc]| https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/iana/iana-if-type/target/site/restconf/iana-if-type.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=concepts/src/main/yang/ieee754.yang;a=blob[ieee754.yang] | Definitions of IEEE754 floating point types | https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]| --| --
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=concepts/src/main/yang/network-concepts.yang;a=blob[network-concepts.yang] | Base network types | https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS\PCEP] | --| --
-|===
-===== Configuration subsystem
-[cols="5*",^]
-|===
-| Model | Description | ODL component 2+^| API definition
-
-5+^|Base types
-
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/config-api/src/main/yang/config.yang;a=blob[config.yang] | Base YANG definitions for configuration subsystem | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller] | https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/config-api/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/config-api/target/site/models/config.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/config-api/src/main/yang/rpc-context.yang;a=blob[rpc-context.yang]| Base YANG definitions for rpc context reference used for rpc routing | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/config-api/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/config-api/target/site/models/rpc-context.html[REST]
-5+^|Base modules
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/netty-threadgroup-config/src/main/yang/netty-threadgroup.yang;a=blob[netty-threadgroup.yang]| Base YANG definitions for netty threadgroup implementation | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller] | https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/netty-threadgroup-config/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/netty-threadgroup-config/target/site/models/threadgroup.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/threadpool-config-impl/src/main/yang/threadpool-impl-flexible.yang;a=blob[threadpool-impl-flexible.yang] |Base YANG definitions for thread services pure Java implementation| https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller] | https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/threadpool-config-impl/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/threadpool-config-impl/target/site/models/threadpool-impl-flexible.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/threadpool-config-impl/src/main/yang/threadpool-impl-scheduled.yang;a=blob[threadpool-impl-scheduled.yang] | Base YANG definitions for thread services pure Java implementation | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/threadpool-config-impl/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/threadpool-config-impl/target/site/models/threadpool-impl-scheduled.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/threadpool-config-impl/src/main/yang/threadpool-impl.yang;a=blob[threadpool-impl.yang] | Base YANG definitions for thread services pure Java implementation | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/threadpool-config-impl/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/threadpool-config-impl/target/site/models/threadpool-impl.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/threadpool-config-impl/src/main/yang/threadpool-impl-fixed.yang;a=blob[threadpool-impl-fixed.yang] |Base YANG definitions for thread services pure Java implementation | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/threadpool-config-impl/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/threadpool-config-impl/target/site/models/threadpool-impl-fixed.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/netty-config-api/src/main/yang/netty.yang;a=blob[netty.yang] | Base YANG definitions for netty services | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| JavaDoc| https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config/netty-config-api/target/site/models/netty.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/threadpool-config-api/src/main/yang/threadpool.yang;a=blob[threadpool.yang]| Base YANG definitions for thread-related services | https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/threadpool-config-api/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config//threadpool-config-api/target/site/models//threadpool.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/logback-config/src/main/yang/config-logging.yang;a=blob[config-logging.yang]| Base YANG definitions for logging service|https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/logback-config/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config//logback-config/target/site/models//config-logging.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/shutdown-api/src/main/yang/shutdown.yang;a=blob[shutdown.yang]| Base YANG definitions for shutdown service| https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/shutdown-api/target/apidocs/index.html[JavaDoc] | https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config//shutdown-api/target/site/models//shutdown.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/shutdown-impl/src/main/yang/shutdown-impl.yang;a=blob[ shutdown-impl.yang]|Base YANG definitions for shutdown implementation|https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/shutdown-impl/target/apidocs/index.html[JavaDoc] |https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config//shutdown-impl/target/site/models//shutdown-impl.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/netty-timer-config/src/main/yang/netty-timer.yang;a=blob[ netty-timer.yang]| Base YANG definitions for netty timer implementation| https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]| https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/netty-timer-config/target/apidocs/index.html[JavaDoc]| https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config//netty-timer-config/target/site/models//netty-timer.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/config/netty-event-executor-config/src/main/yang/netty-event-executor.yang;a=blob[ netty-event-executor.yang]| Base YANG definitions for netty event executor implementation| https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/config/netty-event-executor-config/target/apidocs/index.html[JavaDoc]| https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/config//netty-event-executor-config/target/site/models//netty-event-executor.html[REST]
-|===
-===== MD-SAL modules
-[cols="5*",^]
-|===
-| Model | Description | ODL component 2+^| API definition
-
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-dom-api/src/main/yang/opendaylight-md-sal-common.yang;a=blob[opendaylight-md-sal-common.yang]|Common definition for MD-SAL| https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/md-sal/sal-dom-api/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/sal-dom-api/target/site/models/opendaylight-md-sal-common.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-dom-api/src/main/yang/opendaylight-md-sal-dom.yang;a=blob[ opendaylight-md-sal-dom.yang]| Service definition for Binding Aware MD-SAL| https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/md-sal/sal-dom-api/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/sal-dom-api/target/site/models/opendaylight-md-sal-dom.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-remote/src/main/yang/opendaylight-md-sal-remote.yang;a=blob[ opendaylight-md-sal-remote.yang]|Definition of types related to Internet Assigned Numbers Authority|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|JavaDoc| REST
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-binding-config/src/main/yang/opendaylight-md-sal-binding.yang;a=blob[opendaylight-md-sal-binding.yang]| Service definition for Binding Aware MD-SAL| https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--| https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/sal-binding-config/target/site/models/opendaylight-md-sal-binding.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-netconf-connector/src/main/yang/odl-sal-netconf-connector-cfg.yang;a=blob[odl-sal-netconf-connector-cfg.yang]|Service definition for Binding Aware MD-SAL| https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/md-sal/sal-netconf-connector/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/sal-netconf-connector/target/site/models/odl-sal-netconf-connector-cfg.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-binding-broker/src/main/yang/opendaylight-binding-broker-impl.yang;a=blob[ opendaylight-binding-broker-impl.yang]|Service definition for Binding Aware MD-SAL|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/md-sal/sal-binding-broker/target/apidocs/index.html[JavaDoc]|--
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/sal-dom-broker/src/main/yang/opendaylight-dom-broker-impl.yang;a=blob[ opendaylight-dom-broker-impl.yang]|Service definition for Binding Aware MD-SAL| https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/md-sal/sal-dom-broker/target/apidocs/index.html[JavaDoc]|--
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/samples/toaster/src/main/yang/toaster.yang;a=blob[toaster.yang]|YANG version of the TOASTER-MIB|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL] |--|--
-|===
-===== Netconf endpoint
-[cols="5*",^]
-|===
-| Model | Description | ODL component 2+^| API definition
-
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/netconf/ietf-netconf-monitoring/src/main/yang/ietf-netconf-monitoring.yang;a=blob[ietf-netconf-monitoring.yang]|NETCONF Monitoring Module (http://datatracker.ietf.org/doc/rfc6022/[RFC 6022]|https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]|https://jenkins.opendaylight.org/controller/job/controller-daily/ws/opendaylight/netconf/ietf-netconf-monitoring/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/netconf//ietf-netconf-monitoring/target/site/models//ietf-netconf-monitoring.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/netconf/ietf-netconf-monitoring-extension/src/main/yang/ietf-netconf-monitoring-extension.yang;a=blob[ietf-netconf-monitoring-extension.yang]|NETCONF Monitoring Module extension for tcp transport type|https://wiki.opendaylight.org/view/OpenDaylight_Controller:Main[Controller]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/netconf//ietf-netconf-monitoring-extension/target/site/models//ietf-netconf-monitoring-extension.html[REST]
-|===
-===== Services
-[cols="5*",^]
-|===
-| Model | Description | ODL component 2+^| API definition
-
-5+^|Inventory
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-inventory/src/main/yang/opendaylight-inventory.yang;a=blob[opendaylight-inventory.yang]| The base (abstract) inventory model |https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-topology/target/site/models/opendaylight-topology.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-inventory/src/main/yang/netconf-node-inventory.yang;a=blob[ netconf-node-inventory.yang]|The netconf-specific augmentation of the base inventory model |https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-inventory/target/site/models/netconf-node-inventory.html[REST]
-5+^|Topology
-
-|https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/ietf/ietf-topology/src/main/yang/network-topology@2013-10-21.yang;a=blob[network-topology.yang]|The base (abstract) network topology model http://datatracker.ietf.org/doc/draft-clemm-netmod-yang-network-topo/[Draft-clemm]|https://wiki.opendaylight.org/view/YANG_Tools:Main[Yang tools]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology/target/site/restconf/network-topology.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/ietf/ietf-topology-l3-unicast-igp/src/main/yang/l3-unicast-igp-topology@2013-10-21.yang;a=blob[ l3-unicast-igp-topology.yang]|The base L3 IGP network topology model http://datatracker.ietf.org/doc/draft-clemm-netmod-yang-network-topo/[Draft-clemm]|https://wiki.opendaylight.org/view/YANG_Tools:Main[Yang tools]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology-l3-unicast-igp/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology-l3-unicast-igp/target/site/restconf/l3-unicast-igp-topology.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/ietf/ietf-topology-isis/src/main/yang/isis-topology@2013-10-21.yang;a=blob[isis-topology.yang]|Network topology data types specific to IS-IS (http://datatracker.ietf.org/doc/draft-clemm-netmod-yang-network-topo/[Draft clemm])|https://wiki.opendaylight.org/view/YANG_Tools:Main[Yang tools]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology-isis/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology-isis/target/site/restconf/isis-topology.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/ietf/ietf-topology-ospf/src/main/yang/ospf-topology@2013-10-21.yang;a=blob[ospf-topology.yang]|Network topology data types specific to OSPF (http://datatracker.ietf.org/doc/draft-clemm-netmod-yang-network-topo/[Draft clemm])|https://wiki.opendaylight.org/view/YANG_Tools:Main[Yang tools]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology-ospf/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-topology-ospf/target/site/restconf/ospf-topology.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=yangtools.git;f=model/ietf/ietf-ted/src/main/yang/ted@2013-10-21.yang;a=blob[ted.yang]|Data types for the Traffic Engineering Database (http://datatracker.ietf.org/doc/draft-clemm-netmod-yang-network-topo/[Draft clemm])|https://wiki.opendaylight.org/view/YANG_Tools:Main[Yang tools]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-ted/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/yangtools/job/yangtools-merge/lastSuccessfulBuild/artifact/model/ietf/ietf-ted/target/site/restconf/ted.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=topology/segment-routing/src/main/yang/topology-tunnel-sr.yang;a=blob[topology-tunnel-sr.yang]|Segment Routing extensions to base tunnel topology model.|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS\PCEP] |--|--
-5+^|Model topology
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-topology/src/main/yang/opendaylight-topology.yang;a=blob[opendaylight-topology.yang]|Opendaylight-topology|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-topology/target/site/models/opendaylight-topology.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-topology/src/main/yang/opendaylight-topology.yang;a=blob[opendaylight-topology.yang]|Opendaylight-topology-inventory|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-topology/target/site/models/opendaylight-topology-inventory.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-topology/src/main/yang/opendaylight-topology.yang;a=blob[opendaylight-topology.yang]|Opendaylight-topology-view|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-topology/target/site/models/opendaylight-topology-view.html[REST]
-|===
-===== OpenFlow services
-[cols="5*",^]
-|===
-| Model | Description | ODL component 2+^| API definition
-
-5+^|Flow base types
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-action-types.yang;a=blob[opendaylight-action-types.yang]|Data types for OpenFlow action structures(https://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-spec-v1.3.1.pdf[O.F 1.3.1 Section A 3.4.2]|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-action-types.html[REST]
-| https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-flow-types.yang;a=blob[ opendaylight-flow-types.yang]|Data types for programming flows (match, action, instruction, group, meter)|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-flow-types.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-group-types.yang;a=blob[opendaylight-group-types.yang]|Data types for OpenFlow groups (https://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-spec-v1.3.1.pdf[OF 1.3.1 Section 5.6])|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-group-types.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-match-types.yang;a=blob[opendaylight-match-types.yang]|Opendaylight-match-types|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-match-types.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-meter-types.yang;a=blob[opendaylight-meter-types.yang]|Data types for OpenFlow meter structures (https://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-spec-v1.3.1.pdf[OF 1.3.1 Section 5.7])|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-meter-types.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-port-types.yang;a=blob[opendaylight-port-types.yang]|Data types for OpenFlow port structures (https://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-spec-v1.3.1.pdf[OF 1.3.1 Section A.2.1])|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-port-types.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-queue-types.yang;a=blob[opendaylight-queue-types.yang]|Data types for OpenFlow action structures (https://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-spec-v1.3.1.pdf[OF 1.3.1 Section A 3.6])|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-queue-types.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-base/src/main/yang/opendaylight-table-types.yang;a=blob[opendaylight-table-types.yang]|Data types for table programming (https://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-spec-v1.3.1.pdf[OF 1.3.1 Section 5])|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-base/target/site/models/opendaylight-table-types.html[REST]
-5+^|Flow service
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-service/src/main/yang/flow-capable-transaction.yang;a=blob[flow-capable-transaction.yang]|flow-capable-transaction| https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-service/target/site/models/flow-capable-transaction.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-service/src/main/yang/flow-errors.yang;a=blob[flow-errors.yang]|Flow errors|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-service/target/site/models/flow-errors.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-service/src/main/yang/flow-node-inventory.yang;a=blob[flow-node-inventory.yang]|flow-node-inventory |https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-service/target/site/models/flow-node-inventory.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-service/src/main/yang/flow-topology-discovery.yang;a=blob[flow-topology-discovery.yang]|flow-topology-discovery |https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-service/target/site/models/flow-topology-discovery.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-service/src/main/yang/packet-processing.yang;a=blob[packet-processing.yang]|packet-processing |https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-service/target/site/models/packet-processing.html[REST]
-5+^|Flow statistics
-
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-statistics/src/main/yang/opendaylight-flow-statistics.yang;a=blob[opendaylight-flow-statistics.yang]|individual and aggregate flow statistics APIs and notification interfaces | https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-statistics/target/site/models/opendaylight-flow-statistics.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-statistics/src/main/yang/opendaylight-flow-table-statistics.yang;a=blob[opendaylight-flow-table-statistics.yang]|Flow table statistics collection APIs and notification interfaces |https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-statistics/target/site/models/opendaylight-flow-table-statistics.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-statistics/src/main/yang/opendaylight-group-statistics.yang;a=blob[opendaylight-group-statistics.yang]|Group stats collection APIs and notification interfaces|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-statistics/target/site/models/opendaylight-group-statistics.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-statistics/src/main/yang/opendaylight-meter-statistics.yang;a=blob[opendaylight-meter-statistics.yang]|Meter collection APIs and notification interfaces |https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-statistics/target/site/models/opendaylight-meter-statistics.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-statistics/src/main/yang/opendaylight-port-statistics.yang;a=blob[opendaylight-port-statistics.yang]|Node connector stats collection APIs and notification interfaces|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-statistics/target/site/models/opendaylight-port-statistics.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-statistics/src/main/yang/opendaylight-queue-statistics.yang;a=blob[opendaylight-queue-statistics.yang]|Queue statistics collection APIs and notification interfaces|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-statistics/target/site/models/opendaylight-queue-statistics.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=controller.git;f=opendaylight/md-sal/model/model-flow-statistics/src/main/yang/opendaylight-statistics-types.yang;a=blob[opendaylight-statistics-types.yang]|Generic stats type definitions (Node Connector, Flow, Group, Meter, Queue etc.)|https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL[MD-SAL]|--|https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/md-sal/model/model-flow-statistics/target/site/models/opendaylight-statistics-types.html[REST]
-|===
-===== Affinity services
-[cols="5*",^]
-|===
-| Model | Description | ODL component 2+^| API definition
-
-|https://git.opendaylight.org/gerrit/gitweb?p=affinity.git;f=affinity/yang/src/main/yang/affinity.yang;a=blob[affinity.yang]|Affinity|https://wiki.opendaylight.org/view/Project_Proposals:Affinity_Metadata_Service[Affinity metadata services]|--|--
-|===
-===== BGPPCEP
-[cols="5*",^]
-|===
-5+^|BGP models
-| Model | Description | ODL component 2+^| API definition
-
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=bgp/concepts/src/main/yang/bgp-types.yang;a=blob[bgp-types.yang]|Contains the base concepts contained in http://datatracker.ietf.org/doc/rfc4271/[RFC 4271] and http://datatracker.ietf.org/doc/rfc4760/[RFC 4760]|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=bgp/parser-api/src/main/yang/bgp-message.yang;a=blob[bgp-message.yang]|Contains the base data model of a BGP message (http://datatracker.ietf.org/doc/rfc4271/[RFC 4271] and (http://datatracker.ietf.org/doc/rfc4893/[RFC 4893]|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=bgp/parser-api/src/main/yang/bgp-multiprotocol.yang;a=blob[bgp-multiprotocol.yang]|Base data model of a BGP message (http://datatracker.ietf.org/doc/rfc4271/[RFC 4271]|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=bgp/linkstate/src/main/yang/bgp-linkstate.yang;a=blob[bgp-linkstate.yang]|Base data model of a BGP message (http://datatracker.ietf.org/doc/rfc4271/[RFC 4271]|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=bgp/rib-api/src/main/yang/bgp-rib.yang;a=blob[bgp-rib.yang]|Contains the concept of a Routing Information Base, as defined by http://datatracker.ietf.org/doc/rfc4271/[RFC 4271]|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-5+^|PCEP models
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=pcep/ietf-stateful02/src/main/yang/odl-pcep-crabbe-initiated00.yang;a=blob[odl-pcep-crabbe-initiated00.yang]|Data model for PCEP extensions defined in http://tools.ietf.org/html/draft-crabbe-pce-pce-initiated-lsp-00[Draft Crabbe]|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=pcep/api/src/main/yang/pcep-message.yang;a=blob[pcep-message.yang]|Base data model the the PCEP message http://datatracker.ietf.org/doc/rfc5440/[RFC 5440], https://datatracker.ietf.org/doc/rfc5520/[RFC 5520], and http://datatracker.ietf.org/doc/rfc6006/[1]|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=pcep/api/src/main/yang/pcep-message.yang;a=blob[pcep-message.yang[pcep-message.yang]|Base data types for the PCEP message (http://datatracker.ietf.org/doc/rfc5440/[RFC 5440], https://datatracker.ietf.org/doc/rfc5520/[RFC 5520], and http://datatracker.ietf.org/doc/rfc6006/[2])|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-5+^|RSVP models
-
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=rsvp/api/src/main/yang/rsvp.yang;a=blob[rsvp.yang]|Contains the definition of types related to Resource Reservation Protocol (RSVP)|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-5+^|PCEP topology models
-
-| https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=pcep/topology-api/src/main/yang/network-topology-pcep.yang;a=blob[network-topology-pcep.yang]|PCEP extensions to base topology model|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=pcep/topology-api/src/main/yang/network-topology-pcep-programming.yang;a=blob[network-topology-pcep-programming.yang]|PCEP extensions to base topology model|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-5+^|PCEP tunnel topology models
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=pcep/tunnel-api/src/main/yang/topology-tunnel-pcep.yang;a=blob[topology-tunnel-pcep.yang]|PCEP extensions to base tunnel topology model|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=pcep/tunnel-api/src/main/yang/topology-tunnel-pcep-programming.yang;a=blob[topology-tunnel-pcep-programming.yang]|Programming extensions for tunnel topologies|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-5+^|Programming models
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=programming/api/src/main/yang/programming.yang;a=blob[programming.yang]|The basic tunnel programming model|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]
-|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=programming/topology-api/src/main/yang/network-topology-programming.yang;a=blob[network-topology-programming.yang]|Programming extensions for tunnel topologies|https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|https://git.opendaylight.org/gerrit/gitweb?p=bgpcep.git;f=programming/tunnel-api/src/main/yang/topology-tunnel-programming.yang;a=blob[topology-tunnel-programming.yang]|Programming extensions for tunnel topologies|
-https://wiki.opendaylight.org/view/BGP_LS_PCEP:Main[BGP-LS PCEP]|--|--
-|===
-===== Plugins
-[cols="5*",^]
-|===
-5+^|OpenFlow protocol library
-| Model | Description | ODL component 2+^| API definition
-
-|https://git.opendaylight.org/gerrit/gitweb?p=openflowjava.git;f=openflow-protocol-api/src/main/yang/openflow-action.yang;a=blob[openflow-action.yang]|Base Openflow actions|https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main[OpenFlowJava]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-merge/org.opendaylight.openflowjava$openflow-protocol-api/ws/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-verify/ws/openflow-protocol-api/target/site/restconf/openflow-action.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=openflowjava.git;f=openflow-protocol-api/src/main/yang/openflow-augments.yang;a=blob[openflow-augments.yang]|Object augmentations|https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main[OpenFlow Java]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-merge/org.opendaylight.openflowjava$openflow-protocol-api/ws/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-verify/ws/openflow-protocol-api/target/site/restconf/openflow-augments.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=openflowjava.git;f=openflow-protocol-api/src/main/yang/openflow-extensible-match.yang;a=blob[openflow-extensible-match.yang]|Openflow OXM match|
-https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main[OpenFlow Java]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-merge/org.opendaylight.openflowjava$openflow-protocol-api/ws/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-verify/ws/openflow-protocol-api/target/site/restconf/openflow-extensible-match.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=openflowjava.git;f=openflow-protocol-api/src/main/yang/openflow-instruction.yang;a=blob[openflow-instruction.yang]|Base Openflow instructions|https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main[OpenFlowJava]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-merge/org.opendaylight.openflowjava$openflow-protocol-api/ws/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-verify/ws/openflow-protocol-api/target/site/restconf/openflow-instruction.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=openflowjava.git;f=openflow-protocol-api/src/main/yang/openflow-protocol.yang;a=blob[openflow-protocol.yang]|Openflow Protocol messages|https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main[OpenFlowJava]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-merge/org.opendaylight.openflowjava$openflow-protocol-api/ws/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-verify/ws/openflow-protocol-api/target/site/restconf/openflow-protocol.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=openflowjava.git;f=openflow-protocol-api/src/main/yang/openflow-types.yang;a=blob[openflow-types.yang]|Common Openflow specific types|https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main[OpenFlowJava]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-merge/org.opendaylight.openflowjava$openflow-protocol-api/ws/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-verify/ws/openflow-protocol-api/target/site/restconf/openflow-types.html[REST]
-|https://git.opendaylight.org/gerrit/gitweb?p=openflowjava.git;f=openflow-protocol-api/src/main/yang/system-notifications.yang;a=blob[system-notifications.yang]|System notification objects|https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main[OpenFlowJava]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-merge/org.opendaylight.openflowjava$openflow-protocol-api/ws/target/apidocs/index.html[JavaDoc]|https://jenkins.opendaylight.org/openflowjava/job/openflowjava-verify/ws/openflow-protocol-api/target/site/restconf/system-notifications.html[REST]
-|===
-////
\ No newline at end of file
+++ /dev/null
-== Defense4all\r
-\r
-=== Defense4All Design\r
-\r
-Defense4All is a security SDN application for detecting and driving mitigation of DoS and DDoS attacks in different SDN topologies. It realizes anti-DoS in OOP mode for the ProgrammableFlow SDN environment. Administrators can configure Defense4All to protect certain networks \r
-and servers, known as protected networks or Protected Objects (POs). Defense4All exploits SDN capabilities to count specified traffic, and installs traffic counting flows for each protocol of \r
-each configured PO in every network location (VTN Vexternals) through which traffic of the subject PO flows. Defense4All then monitors traffic of all configured POs, summarizing readings, rates, \r
-and averages from all relevant network locations. If it detects a deviation from normal learned traffic behavior in a protocol (such as TCP, UDP, ICMP, or the rest of the traffic) of a particular \r
-PO, Defense4All declares an attack against that protocol in the subject PO. The Defense4All learning period has a minimum of one week from the installation of the counting flows in \r
-which Defense4All does not detect attacks. +\r
-\r
-To mitigate a detected attack, Defense4All performs the following procedure: +\r
-\r
-. Validates that the DefensePro device is alive and selects a live connection to it (if DefensePro is not alive or does not have a live connection from a PFS, then no traffic diversion is performed. For more information, refer to the Continuity section. \r
-. Configures DefensePro with a security policy and normal rates of the attacked traffic. The latter speeds up DefensePro’s efficient mitigation of the attack. \r
-. Starts monitoring and logging syslogs arriving from DefensePro for the subject traffic. As long as it continues receiving syslog attack notifications from DefensePro regarding this attack, Defense4All continues attack mitigation through traffic diversion even if the Vexternal FlowFilter counters do not indicate any more attacks. \r
-. Maps the selected physical DefensePro connection to the relevant VTN by creating a pair of Vexternals and mapping them to the selected pair of physical PFS ports connected to DefensePro. Automatically learns and preserves VLAN tagging if it exists. If Defense4All has already created and mapped a pair of Vexternals with the same VLAN in the VTN, then the same pair is also reused for diversion of the new traffic (rather than creating new Vexternals for the same VTN and VLAN). \r
-. Installs higher priority flow filter entries in every north Vexternal through which the attacked traffic flows in order to redirect traffic to the “north DP-In Vexternal”. It also selects one of the live north interfaces of the Vbr connected to all those Vexternals (there can be exactly one Vbr with the same VLAN). Defense4All re-injects traffic from the “DP-Out Vexternal” to the selected interface of the Vbr. When Defense4All decides that the attack is over (no indication from either PFC FlowFilter counters or from DefensePro) it reverts the previous actions: it stops monitoring for DefensePro syslogs about the subject traffic, it removes the traffic diversion FlowFilters, removes the “DP-In and DP-Out Vexternals” (if this is the last attack in this VTN and VLAN), and removes the security configuration from DefensePro. Defense4All then returns to peacetime monitoring. \r
-\r
-In this version, Defense4All runs as a single instance (non-clustered), but integrates the following main fault tolerance features: \r
-\r
-* Runs as a Linux service that is automatically restarted should it fail. \r
-* State entirely persisted in stable storage, and upon restart Defense4All obtains the latest state. \r
-* Carries a health tracker with restart and reset capabilities to overcome certain logical and aging bugs. \r
-\r
-Defense4All monitors the status of DefensePro, switch connections to DefensePro, relevant Vbrs in various VTNs, northbound interfaces of those Vbrs, and north Vexternals and adjusts, cancels, and (re)initiates attack traffic diversion accordingly. \r
-\r
-The following figure illustrates the possible state of any given PO. Radware’s DefensePro (DP) is an example of an incorporated AMS. \r
-image::Pn_possible_states.jpg[Workflow of Defense4All Attack Mitigation]\r
-\r
-=== Defense4All in an ODL Environment\r
-Defense4All comprises of an SDN application framework and the Defense4All application itself, packaged as a single entity. \r
-Application integration into the framework is pluggable, so any other SDN application can benefit from the common framework services. \r
-\r
-The main advantages of this architecture are:\r
-\r
-* Faster application development and changes - The Framework contains common code for multiple applications, complex elements (such as clustering and repository services) are implemented once for the benefit of any application.\r
-* Faster, flexible deployment in different environments, form-factors, satisfying different NFRs – The Framework masks from SDN application factors such as required data survivability, scale and elasticity, availability, security.\r
-* Enhanced robustness - Complex framework code is implemented and tested once, cleaner separation of concerns leads to more stable code, and the framework can increase robustness proactively with no additional code in the application logic (such as periodic application recycle).\r
-* Unified management of common aspects – Common look and feel.\r
-\r
-=== Framework View\r
-\r
-The following figure illustrates the framework view.\r
-image::800px-Framework_view.jpg[Framework View]\r
-\r
-The framework contains the following elements:\r
-\r
-*FrameworkMain* – The Framework root point contains references to all Framework modules and global repositories, as well as the roots of deployed SDN applications (in the current version, the framework can accommodate only one application). This is also the point to start, stop, or reset the framework (along with its hosted application) Web server, Jetty Web server running the Jersey RESTful Web services framework, with Jackson parser for JSON encoded parameters. The REST Web server runs a servlet for the framework and another servlet for each deployed application (currently only one). All REST and CLI APIs are supported through this REST Web server. \r
-\r
-*FrameworkRestService* – A set of classes constituting the framework servlet that responds to framework REST requests ( get latest Flight Recorder records, perform factory reset, and so on). The FrameworkRestService invokes control and configuration methods against the FrameworkMgmtPoint, and for reporting it retrieves information directly from the relevant repositories. For flight recordings, it invokes methods against the FlightRecorder. \r
-\r
-*FrameworkMgmtPoint* – The point to drive control and configuration commands (start, stop, reset, set address of the hosting machine, and so on). FrameworkMgmtPoint in turn invokes methods against other relevant modules in the correct order. It forwards lifecycle requests (start, stop, reset) directly to FrameworkMain to drive them in the correct order. \r
-\r
-*Defense4All Application* – The AppRoot object that should be implemented/extended by any SDN application (in this case, Defense4All). SDN applications do not have “main,” and their lifecycle (start, stop, reset) is managed by the framework operating against the application root object, which then drives all lifecycle operations in the application. This module also contains references back to the framework, allowing the application to use framework services (such as create a Repo and log a flight record) and common utilities. \r
-\r
-*Common classes and Utilities* – A library of convenient classes and utilities from which any framework or SDN application module can benefit. Examples include wrapped threading services (for asynchronous, periodic, or background execution), short hash of a string, and confirmation by user. \r
-\r
-*Repository services* – One of the key elements in the framework philosophy is decoupling the compute state from the compute logic. All durable states should be stored in a set of repositories that can be then replicated, cached, distributed under the covers, with no awareness of the compute logic (framework or application). Repository services comprise the RepoFactory and Repo or its annotations-friendly equivalent – the EntityManager. The RepoFactory is responsible for establishing connectivity with the underlying repository plugged-in service, instantiate new requested repositories, and return references to existing ones. The chosen underlying repository service is Hector Client over Cassandra NoSQL DB. Repo presents an abstraction of a single DB table. It enables reading the whole table, only table keys (tables are indexed by only the single primary key), records or single cells, as well as writing records or single cells with controlled eagerness. A sub-record (with only a portion of cells) may be written. In this case, the displayed cells override existing ones in the repository. Other cells in the repository remain unchanged. In contrast to a relational DB, in which all columns must be specified up-front (in a schema design), Repo leverages the underlying Cassandra support to contain rows (records) in the same table with different sets of columns, some of which may not being even defined up-front. Furthermore, cells with new columns can be added or removed on the fly. RepoFactory and Repo (as well as its Entity Manager annotation-friendly equivalent) constitute a convenient library targeted to framework and SDN applications goals on top of the Hector client library communicating with Cassandra Repository cluster. Scaling the Cassandra cluster, distributing data shards across Cassandra cluster members, and configuring read/write eagerness and consistency are for the most part encapsulated in this layer. \r
-\r
-*Logging and Flight Recorder services* – The logging service uses Log4J library to log error, warning, trace, or informational messages. These logs are mainly for Defense4All developers. Administrators can obtain additional details about failures from the error log. FlightRecorder records all flight records recorded by any Defense4All module, including information received from external network elements such as ODC and AMSs. It then allows a user or administrator to obtain that information through the REST API or the CLI. Flight records can be filtered by categories (zero or more can be specified) and by time ranges. FlightRecorder stores all flight records in its own Repo (with another repo holding time ranges for efficient time ranges retrieval from the records repo). Because all flight records are stored in Cassandra, the number of flight records Defense4All can keep is limited only by the size of the underlying persistent storage capacity of all Cassandra servers, and so even on a single Cassandra instance, months of historical information can be kept. \r
-\r
-*HealthTracker* – The point to hold the aggregated runtime health of Defense4All and to act in response to severe deteriorations. Any module, upon sensing unexpected and/or faulty behavior in it or in any other module can record a “health issue” in the HealthTracker, providing health issue significance. This is instead of directly triggering a Defense4All termination. This means that numerous health issues in a short period with high aggregated significance are likely to indicate a significant wide-spread Defense4All problem, but sporadic and/or intermittent operational “hiccups” can be neglected, even if Defense4All remains less than 100% operational (the administrator can always reset it to fully recover). As a result, every non-permanent health issue has a gradually diminished effect over time. If Defense4Al health deteriorates below a predefined threshold, HealthTracker triggers responsive actions depending on the nature of the health issues. A restart can heal transient problems, and so the HealthTracker triggers Defense4All termination (running as a Linux service, Defense4All is automatically restarted). To recover from more permanent problems, HealthTracker may additionally trigger a Defense4All reset. If this does not help, the next time the HealthTracker attempts a more severe reset. As a last resort, the administrator can be advised to perform a factory reset. \r
-\r
-*ClusterMgr* – Currently not implemented. This module is responsible for managing a Defense4All cluster (separate from Cassandra or ODC clusters, modeled as separate tier clusters). A clustered Defense4All carries improved high availability and scalability. Any module in the Defense4All framework or application can register with ClusterMgr for a clustered operation, specifying whether its functionality should be carried out by a single or by multiple/all active instances (running on different Defense4All cluster members). When cluster membership changes, ClusterMgr notifies each instance in each module about its role in the clustered operation of that module. If there is a single active instance, that instance is notified of its role in the cluster, while all other instances are notified that they are in standby mode. If there are multiple active instances, each active instance is notified about the number of active instances and its logical enumeration in that range. All states are stored in a globally accessible and shared repository, so any instance of a module is stateless, and can perform any role after every membership change. For example, following membership change N, an instance can be enumerated as 2 out of 7, as a result performing the relevant portion of the work. At membership change N+1, the same instance can be enumerated 5 out of 6, and perform the work portion allocated for 5 and not for 2. Peer messaging services are skipped which the ClusterMgr can provide for a more coordinated cross-instance operation. \r
-\r
-The Defense4All application is highly pluggable. It can accommodate different attack detection mechanisms, different attack mitigation drivers, and drivers (called reps [representative]) to different versions of the ODC and different AMSs. The Defense4All application comprises “core” modules and “pluggable” modules implementing well-defined Defense4All application APIs. \r
-\r
-=== Application View\r
-\r
-The following figure illustrates the application view.\r
-image::800px-D4a_application_view.jpg[Application View]\r
-\r
-The following is a description of the Defense4All application modules: +\r
-\r
-*DFAppRoot* – The root module of the Defense4All application. The Defense4All application does not have “main,” and its lifecycle (start, stop, reset) is managed by the Framework operating against this module, which in turn drives all lifecycle operations in the Defense4All application. DFAppRoot also contains references to all Defense4All application modules (core and pluggable), global repositories, and references back to the framework, allowing the Defense4All application modules to use framework services (such as create a Repo and log a flight record) and common utilities. \r
-\r
-\r
-*DFRestService* – A set of classes constituting the Defense4All application servlet that responds to Defense4All application REST requests. The DFRestService invokes control and configuration methods against the DFMgmtPoint, and for reporting it retrieves information directly from the relevant repositories. For flight recordings, it invokes methods against the FlightRecorder. \r
-\r
-\r
-*DFMgmtPoint* – The point to drive control and configuration commands (such as addams and addpn). DFMgmtPoint in turn invokes methods against other relevant modules in the right order. \r
-\r
-\r
-*ODL Reps* – A pluggable module-set for different versions of the ODC. Comprises two functions in two sub-modules: stats collection for, and traffic diversion of, relevant traffic. These two sub-modules adhere to StatsCollectionRep DvsnRep APIs. ODL Reps is detailed in Figure 6 and the description that follows it. \r
-\r
-\r
-*SDNStatsCollector* – Responsible for setting “counters” for every PN at specified network locations (physical or logical). A counter is a set of OpenFlow flow entries in ODC-enabled network switches and routers. The SDNStatsCollector periodically collects statistics from those counters and feeds them to the SDNBasedDetectionMgr (see the description below). The module uses the SDNStatsCollectionRep to both set the counters and read latest statistics from those counters. A stat report consists of read time, counter specification, PN label, and a list of trafficData information, where each trafficData element contains the latest bytes and packet values for flow entries configured for <protocol,port,direction> in the counter location. The protocol can be {tcp,udp,icmp,other ip}, the port is any Layer 4 port, and the direction can be {inbound, outbound}. \r
-\r
-\r
-*SDNBasedDetectionMgr* – A container for pluggable SDN-based detectors. It feeds stat reports received from the SDNStatsCollector to plugged-in SDN based detectors. It also feeds all SDN based detectors notifications from the AttackDecisionPoint (see the description below) about ended attacks (so as to allow reset of detection mechanisms). \r
-\r
-\r
-*RateBasedDetector sub-module* – This detector learns for each PN its normal traffic behavior over time, and notifies AttackDecisionPoint (see the description below) when it detects traffic anomalies. For each protocol {TCP, UDP, ICMP, other IPs} of each PN, the RateBasedDetector maintains latest rates and exponential moving averages (baselines) of bytes and packets, as well as last reading time. The detector maintains those values both for each counter as well as the aggregation of all counters for each PN. The organization at two levels of calculations (counter and PN aggregate) allows for better scalability (such as working with clustered ODCs, where each instance is responsible for obtaining statistics from a portion of network switches, and bypassing the ODC single instance image API). Such organizations also enable a more precise stats collection (avoiding the difficulty of collecting all stats during a very small time interval). Stats are processed at the counter level, and periodically aggregated at the PN level. Continuous detections of traffic anomalies cause the RateBasedDetector to notify AttackDecisionPoint about attack detection. Then, absence of anomalies for some period of time causes the detector to stop notifying the AttackDecisionPoint about attack detection. The detector specifies a detection duration within which the detection is valid. After that time, the detection expires but can be “prolonged” with another notification about the same attack. \r
-\r
-\r
-*AttackDecisionPoint* – This module is responsible for maintaining attack lifecycles. It can receive attack detections from multiple detectors. Defense4All supports the RateBasedDetector, external detectors (scheduled for future versions), and AMS-based detector reference implementation (over Radware’s DefensePro). In the current version, AttackDecisionPoint fully honors each detection (max detector confidence and max detection confidence). It declares a new attack for every detection of a newly attacked traffic (PN, protocol, and port), and adds more detections for existing (already declared) attacks. The module periodically checks the statuses of all attacks. As long as there is at least one unexpired detection (each detection has an expiration time), the attack is kept declared. If all detections are expired for a given attack the AttackDecisionPoint declares the attack has ended. The module notifies the MitigationMgr (see description below) to start mitigating any new declared attack. It notifies the MitigationMgr to stop mitigating ended attacks, and also notifies the detectionMgr to reset stats calculations for traffic on which an attack has just ended. \r
-\r
-\r
-*MitigationMgr* - A container for pluggable mitigation drivers. The MitigationMgr maintains the lifecycle of all mitigations as a result of mitigation notifications from AttackDecisionPoint. It holds a pre-ordered list of the MitigationDriver sub-modules, and attempts to satisfy each mitigation in that order. If MitigationDriveri indicates to MitigationMgr that it does not mitigate a mitigation (because of per PN preferences, unavailability of AMS resources, network problems, and so on) MitigationMgr will attempt mitigation by MitigationDriveri+1. If none of the plugged-in MitigationDrivers handle mitigation, it remains at the status ‘not-mitigated.’ \r
-\r
-\r
-*MitigationDriverLocal* – This mitigation driver is responsible for driving attack mitigations using AMSs in their sphere of management. \r
-When requested to mitigate an attack, this mitigator performs the following sequence of steps: +\r
-\r
-. Consults with the plugged in DvsnRep (see description below) about topologically feasible options of diversion for each of the managed AMSs from each of the relevant network locations. In this version, the diversion is always performed from the location where the stats counters are installed. \r
-. The MitigationDriverLocal selects an AMS out of all feasible options (in the first release, the selection is trivial—it is the first in list). \r
-. Optionally configures all the AMSs (each diversion source may have a different AMS associated with it) prior to instructing to divert traffic to each. This is done through the plugged in AMSRep. \r
-. MitigationDriverLocal instructs the DvsnRep to divert traffic from each source NetNode (in this version, NetNode is modeled over an SDN switch) to the AMS associated with that NetNode. Diversion can be either for inbound traffic only or both for inbound and outbound traffic. \r
-. Mitigation driver notifies the AMSBasedDetector to optionally start monitoring the attack status in all the AMSs, and feed attack detections to the AttackDecisionPoint. \r
-. In future versions, the MitigationDriverLocal is scheduled to monitor health of all AMSs and relevant portions of network topologies, re-selecting AMSs should some fail, or should network topologies changes require that. \r
-When mitigation should be ended, the MitigationDriverLocal notifies AMSBasedDetector to stop monitoring the attack status for the ended attack, notifies DvsnRep to stop traffic diversions to all AMSs for this mitigation, and finally notifies the AMSRep to optionally clean all mitigation-related configuration sets in each relevant AMS. \r
-\r
-*AMSBasedDetector* – This optional module (which can be packaged as part of the AMSRep) is responsible for monitoring/querying attack mitigation by AMSs. Registering as a detector, this module can then notify AttackDecisionPoint about attack continuations and endings. It monitors only specified AMSs and only for specified (attacked) traffic. \r
-\r
-\r
-*AMSRep* - A pluggable module for different AMSs. The module adheres to AMSRep APIs. It can support configuration of all introduced AMSs (permanently or before/after attack mitigations). It can also receive/query security information (attack statuses), as well as operational information (health, load). AMSRep module is entirely optional – AMSs can be configured and monitored externally. In many cases, attacks can continue be monitored solely via SDN counters. Defense4All contains a reference implementation AMSRep that communicates with Radware’s DefensePro AMSs. \r
-\r
-=== ODL Reps View\r
-\r
-The following figure illustrates the Defense4All application ODL Reps module-set structure. \r
-image::D4a_odl_reps_view.jpg[ODL Reps View]\r
-\r
-Different versions of OFC may be represented by different versions of the ODL Reps module-set. ODLReps comprises two functions: stats collection for, and traffic diversion of, relevant traffic. Both or either of the functions may be utilized in a given deployment. \r
-As such, they have a common point to communicate with the ODC and hold all general information for the ODC. \r
-\r
-ODL Reps supports two types of SDN switches: sdn-hybrid, which supports both SDN and legacy routing, and sdn-native, which supports SDN only routing. Counting traffic on the sdn-hybrid switch is done by programming a flow entry with the desired traffic selection criteria and the action “send to normal”, that is, to continue with legacy routing. Counting traffic on sdn-native switch requires an explicit routing action (which output port to send the traffic to). Defense4All avoids learning all routing tables by requiring an sdn-native switch which is more or less a bump-in the wire with respect to traffic routing (that is, traffic entering port 1 normally exits port 2 and traffic entering port 3 normally exits port 4 and vice versa). Such a switch allows for easy programming of flow entries just to count traffic or to divert traffic to/from the attached AMS. When Defense4All programs a traffic counting flow entry with selection criteria that includes port 1, its action is output to port 2, and similarly with 3 to 4. In future versions, this restriction is scheduled to be lifted. \r
-\r
-The following is a description of the sub-modules: +\r
-\r
-StatsCollectionRep - The module adheres to StatsCollectionRep APIs. Its main tasks are: \r
-\r
-* Offer counter placement NetNodes in the network. The NetNodes offered are all NetNodes defined for a PN. This essentially maps which of SDN switches the traffic of the given PN flows. \r
-* Add a peacetime counter in selected NetNodes to collect statistics for a given PN. StatsCollectionRep creates a single counter for a PN in each NetNode. (Overall, a NetNode can have multiple counters for different PNs; and a PN can have multiple counters in NetNodes as specified for the given PN). StatsCollectionRep translates the installation of a counter in a NetNode to programming four flow entries (for TCP, UDP, ICMP, and the rest of the IPs) for each “north traffic port” in that NetNode port from which traffic from a client to a protected PN enters the SDN switch. For example, StatsCollectionRep adds for a given PN 12 flow entries in an SDN switch with three ports through that PN’s inbound traffic enters the OFS. And, if another NetNode (SDN switch) was specified to have that PN’s inbound traffic entering it through two ports, then StatsCollectionRep programs for this PN eight flow entries in that second NetNode. \r
-* Remove a peacetime counter. \r
-* Read latest counter values for a specified counter. StatsCollectionRep returns a vector of latest bytes and packets counted for each protocol-port in each direction (currently only “north to south” is supported), along with the time it received the reading from the ODC. \r
-\r
-*DvsnRep* - The module adheres to DvsnRep APIs. Its main tasks are: \r
-\r
-* Return diversion properties from a given NetNode to a given AMS. In this version, an empty property is returned if such a diversion is topologically feasible (AMS is directly attached to the SDN switch over which the specified NetNode is modeled. Otherwise no properties are returned. This leaves room for remote diversions in future versions, and topological costs to each distant AMS, such as latency, bandwidth reservation, and cost). \r
-* Divert (attacked) traffic from a specified NetNode through an AMS. As such, the new flow entries take precedence over the peacetime ones. DvsnRep programs flow entries to divert inbound attacked traffic (or all traffic, if so specified for the PN) from every “north traffic port” into the AMS “north” port. If “symmetric diversion” (for both inbound and returning, outbound traffic) has been specified for that PN, DvsnRep programs another set of flow entries to divert attacked (or all) traffic from every “south traffic port” into the AMS “south” port. In an sdn-hybrid switch deployment, DvsnRep adds a flow entry for inbound traffic that returns from the AMS south port, with the action sent to normal, and similarly it adds a flow entry for outbound returning traffic from the AMS north port, with action of also sent to normal. In an SDN-native switch, the action is to send to the correct output port, however if this scenario the process is more complex for determining the correct port. North port MAC learning is used to determine from the source/destination MAC in the packet the correct output port. This scheme of flow entries works well for TCP, UDP and ICMP attacks. For “other IP” attacks, the flow entries programming is more complex, and is suppressed here for clarity. The set of flow entries programmed to divert (but still count) traffic comprises the “attack traffic floor”. There may be many attack traffic floors, all of which take precedence over the peacetime stats collection floor (by programming higher priority flow entries). Additional attacks (except “other IP” attacks, which is a special case, and is suppressed here) are created with higher priority traffic floors over previously set attack traffic floors. Attacks may fully or partially “eclipse” earlier attacks (for example, TCP port 80 over TCP, or vice versa), or be disjointed (such as TCP and UDP). Stats collection is taken from all traffic floors, both peacetime and attacks. An SDN-based detector aggregates all statistics into overall rates, thus determining if the attack is still in progress. (Note that eclipsed peacetime counted traffic may show zero rates, and that counting is complemented by the higher priority floor counters.) \r
-* End diversion. DvsnRep removes the relevant attack traffic floor (removing all of its flow entries from the NetNode). Note that this affects neither traffic floors “above” the removed floor nor the traffic floors “below.” In addition, the SDN-based detector receives the same aggregated rates from counters of remaining floors, so its operation also is not affected. \r
-\r
-*ODLCommon* – This module contains all common elements needed to program flow entries in the ODC. This allows for coherent programming of configured ODCs (in this version, at most one) by StatsCollectionRep and DvsnRep. For instance ODLCommon instantiates connectivity with the ODCs, maintains a list of programmed flow entries and cookies assigned to each. It also maintains references to DFAppRoot and FrameworkMain. When an sdn-native NetNode is added ODLCommon programs 2 flow entries per each protected link (pair of input-to-output ports) to transfer traffic between the two ports (traffic entering north port is routed to south port and vice versa). ODLCommon adds two more flow entries for each port connecting to an AMS to block returning ARP traffic (so as to avoid ARP floods if the AMSs are not configured to block them). This “common traffic floor” flow entries are set with the lowest priority. Their counters are accounted for neither stats collections nor traffic diversion. When a NetNode is removed, ODLCommon removes this common traffic floor flow entries. \r
-\r
-\r
-*FlowEntryMgr* – This module provides an API to perform actions on flow entries in an SDN switch managed by an ODC, and retrieves information about all nodes managed by an ODC. Flow entries actions include adding a specified flow entry in a specified NetNode (SDN switch/router), removing a flow entry, toggling a flow entry, getting details of a flow entry, and reading statistics gathered by the flow entry. FlowEntryMgr uses the connector modules to communicate with the ODC. \r
-\r
-\r
-*Connector* – This module provides the basic API calls to communicate with the ODC, wrapping REST communications. After initializing connection details with a specified ODC, the connector allows getting or deleting data from the ODC, as well as posting or putting data to the ODC. \r
-\r
-\r
-*ODL REST Pojos* – This set of Java classes are part of the ODC REST API, specifying the Java classes of the parameters and the results of interaction with the ODC. \r
-\r
-=== Basic Control Flow\r
-\r
-Control flows are logically ordered according to module runtime dependencies, so if module A depends on module B then module B should be initialized before module A, and terminate after it. Defense4All application modules depend on most Framework modules, except WebServer. \r
-\r
-*Startup* — Defense4All initializes all its modules and re-applies previously configured infrastructure and security set-ups, obtaining them from persistent repositories. At the end of the Startup process, Defense4All resumes its prior operation. +\r
-*Termination* - restart — Defense4All persists any relevant data into stable storage repositories, and terminates itself. If the termination is for restart, the automatic restart mechanism restarts Defense4All. Otherwise (such as upgrading) Defense4All does not automatically restart. +\r
-*Reset* — In this flow, all modules are reset to factory level. This means that all dynamically obtained data as well as user configurations are deleted +\r
-\r
-=== Configurations and Setup Flow\r
-\r
-*OFC (OpenFlowController = ODC)* – When DFMgmtPoint receives from DFRestService a request to add an OFC, it first records the added OFC in the OFC’s Repo, and then notifies ODLStatsCollectionRep and ODLDvsnRep, which in turn notify the ODL to initiate a connection to the added OFC (ODC). ODL instantiates a REST client for communication with the ODC. \r
-\r
-\r
-*NetNode* - Multiple NetNodes can be added. Each NetNode models a switch or similar network device, along with its traffic ports, protected links, and connections to AMSs. When DFMgmtPoint receives from DFRestService a request to add a NetNode, it first records the added NetNode in NetNodes Repo, and then notifies ODLStatsCollectionRep and ODLDvsnRep, followed by MitigationMgr. ODLStatsCollectionRep and ODLDvsnRep then notify the ODL, and the ODL installs low priority flow entries to pass traffic between the protected links’ port pairs. MitigationMgr notifies MitigationDriverLocal, which updates its NetNode-AMS connectivity groups for consistent assignment of AMSs to diversion from given NetNodes. \r
-\r
-\r
-*AMS* – Multiple AMSs can be added. When DFMgmtPoint receives from DFRestService a request to add an AMS, it first records the added AMS in the AMS’s Repo, and then notifies AMSRep. AMSRep can optionally pre-configure protection capabilities in the added AMS, and start monitoring its health. \r
-\r
-\r
-*PN* - Multiple PNs can be added. When DFMgmtPoint receives from DFRestService a request to add a PN, it first records the added PN in the PN’s Repo, notifies MitigationMgr, and then finally notifies the DetectionMgr. MitigationMgr notifies MitigationDriverLocal, which then notifies AMSRep. AMSRep can preconfigure the AMS for this PN, as well its EventMgr to accept events related to this PN’s traffic. DetectionMgr notifies RateBasedDetector, which then notifies StatsCollector. StatsCollector queries ODLStatsCollectionRep about possible placement of stats collection counters for this PN. ODLStatsCollectionRep returns all NetNodes configured for this PN (and if none are configured, it returns all NetNodes currently known to Defense4All). StatsCollector “chooses” the counter locations option (the only available option in this version). For each of the NetNodes, it then asks ODLStatsCollectionRep to create a counter for the subject PN. The counter is essentially a set of flow entries set for the protocols of interest (TCP, UDP, ICMP, and the rest of the IPs) on each north traffic port. The counter is given a priority and this constitutes the peacetime traffic floor (to monitor traffic by periodically reading all counter flow entry traffic count values). Because the PN may be re-introduced at restart or a change in network topology may require re-calculation of counter locations, it is possible that some/all counters may already be in place. Only new counters are added. Counters that are no longer are removed. ODLStatsCollectionRep configures the flow entries according to the NetNode type. For hybrid NetNodes, the flow entry action is “send to normal” (proceed to legacy routing), while for native NetNodes, the action is to match the output port (in each protected link). OdlStatsCollectionRep invokes the ODL to create each specified flow entry. The latter invokes FlowEntryMgr and Connector to send the request to the ODC. \r
-\r
-=== Attack Detection Flow\r
-Periodically, the StatsCollector requests the ODL StatsCollectionRep to query the ODC for the latest statistics for each set counter for each configured PN. ODLStatsCollectionRep invokes FlowEntryMgr to obtain statistics for each flow entry in a counter. The latter invokes the connector to obtain the desired statistics from the ODC. \r
-\r
-ODLStatsCollectionRep aggregates the obtained results in a vector of stats (latest bytes and packets readings per each protocol) and returns that vector. StatsCollector feeds each counter stats vector to DetectionMgr, which then forwards the stats vector to the RateBasedDetector. The RateBasedDetector maintains stats information for every counter as well as aggregated counter stats for every PN. Stats information includes the time of previous reading, and for every protocol the latest rates and exponential averages. \r
-\r
-The RateBasedDetector checks for significant and prolonged latest rate deviations from the average, and if such deviations are found in the PN aggregated level, it notifies the AttackDecisionPoint about attack detection. As long as deviations continue, the RateBasedDetector continues notifying the AttackDecisionPoint about the detections. It sets an expiration time for every detection notification, and repeatable notifications essentially prolong the detection expiration. \r
-\r
-AttackDecisionPoint honors all detections. If it has already declared an attack on that protocol-port, then the AttackDecisionPoint associates the additional detection with that existing attack. Otherwise, it creates a new attack and notifies the MitigationMgr to mitigate that attack (as described below). Periodically, AttackDecisionPoint checks the status of all detections of each live attack. If all detections have expired, AttackDecisionPoint declares the end of the attack and notifies MitigationMgr to stop mitigating the attack. \r
-\r
-=== Attack Mitigation Flow\r
-\r
-MitigationMgr, upon receiving mitigate notification from yhe AttackDecisionPoint, attempts to find a plugged-in MitigationDriver to handle the mitigation. Currently, it requests only its plugged-in MitigationDriverLocal. \r
-\r
-MitigationDriverLocal checks if there are known, live, and available AMSs to which attacked (or all) traffic can be diverted from NetNodes through which attacked traffic flows. It selects one of the suitable AMSs and configures it prior to diverting attack traffic to the selected AMS. For example, MitigationDriverLocal retrieves from Repo the relevant protocol averages, and configures them in AMS through the AMSRep. \r
-\r
-MitigationDriverLocal then requests ODLDvsnRep to divert the attacked PN protocol-port (or all PN) traffic from each of the NetNodes through which the PN traffic flows to the selected AMS. \r
-\r
-ODLDvsnRep creates a new highest priority traffic-floor (that contains flow entries with a priority higher than any flow entry in the previously set traffic floors). The traffic floor contains all flow entries to divert and count traffic from every ingress/northbound traffic port into the AMS, and back from the AMS to the relevant output (southbound) ports. Optionally, diversion can be “symmetric” (in both directions), in which case flow entries are added to divert traffic from southbound ports into the AMS, and back from the AMS to northbound ports. Note that the StatsCollector treats this added traffic floor as any other, and passes obtained statistics from this floor to the DetectionMgr/RateBasedDetector. Because traffic floors are aggregated (in the same NetNode as well as across NetNodes) for a given PN the combined rates remain the same as prior to diversion. Just like ODLStatsCollectionRep, ODLDvsnRep also utilizes lower level modules to install the flow entries in desired NetNodes. \r
-\r
-Finally, MitigationDriverLocal notifies AMSRep to optionally start monitoring this attack and notify the AttackDecisionPoint if the attack continues or new attacks develop. AMSRep can do that through the AMSBasedDetector module. \r
-\r
-If MitigationDriverLocal finds no suitable AMSs, or fails to configure any of its mitigation steps, it aborts the mitigation attempt, asynchronously notifying MitigationMgr. The mitigation then remains in status “no-resources.” \r
-\r
-When MitigationMgr receives a notification to stop mitigating an attack, it forwards this notification to the relevant (and currently the only) MitigationDriver, MitigationDriverLocal. MitigationDriverLocal reverses the actions in at the start of the mitigation. It notifies AMSRep to stop monitoring for this attack, it cancels diversion for the attacked traffic, and finally notifies AMSRep to optionally remove pre-mitigation configurations. \r
-\r
-=== Continuity\r
-\r
-Service Continuity, as opposed to High Availability, is defined here as the ability to deliver a required level of service, at tolerable cost, \r
-in the presence of disrupting events, where:\r
-\r
-* Disrupting events can be load, changes, logical errors, failures and disasters, administrative actions (such as an upgrade), external attacks, and so on. \r
-* The level of service can include response time, throughput, survivability of data/operations, security/privacy, and so on. The required level of service may differ for every service function, for every type of event, at different event handling phases. \r
-* The cost can include people (number, expertise), equipment (hardware, software), facilities (space, power). +\r
-\r
-*Clustering and Fault-tolerance* - Clusters help to address both Scalability and High Availability. If one of the cluster members fails, another cluster member can quickly assume its responsibilities. This overcomes member failures, member hosting machine failures, and member network connectivity failures. Defense4All clustering is scheduled for future releases. In version 1.0, Defense4All runs as a Linux restartable service, so if it fails, the hosting Linux OS revives Defense4All. This enables overcoming intermittent/sporadic Defense4All failures. Failure of the Defense4All hosting machine means longer time and modest additional human effort to revive the machine and its hosted Defense4All. If the machine cannot be brought up, Defense4All can be started on another machine in the network. To ensure that Defense4All resumes its operation (rather that restart from scratch) you must pre-load the Defense4All (latest or earlier) state snapshot on that machine. A non-clustered environment affects the time and the human effort to recover from machine failures. The time factor is less critical, as Defense4All runs out-of-path, so its longer non-availability period means a longer time to detect and mitigate new attacks. \r
-\r
-*State Persistence* - Defense4All persists the state in the Cassandra DB running on the same machine. In version 1.0, only one Cassandra instance cluster is configured. As long as local stable storage does not crash, a Linux restart of the Defense4All service enables Defense4All to quickly retrieve its latest state from Cassandra and resume its latest operation. The same happens at failure and restart of the machine hosting Defense4All. Taking the Defense4All state backup, and restoring on another machine allows for resuming the Defense4All operation on that machine. Multi-node Cassandra clusters (scheduled for future versions) will increase state persistence while reducing recovery time and effort. \r
-\r
-*Restart Process* - When Defense4All (re)starts, it first checks for saved configuration data, and re-plays the configuration steps against all its relevant modules, driving any relevant external programming and/ or configuration actions (such as against the PFC or AMS devices), for example, re-adding a PO. The only difference between this configuration replay and original configuration is that any dynamically obtained data is preserved, for example, all PO statistics. This allows for easily reaching internal consistency, especially in cases where Defense4All or its hosting machine has crashed. When configuration action derivatives are replayed against external entities, for example adding missing PO stats counters, and removing no longer necessary ones, consistency with external entities is also reached. Defense4All becomes operational (launching its Web server), lets you or some other component to complete Defense4All missing configurations according to possible changes while Defense4All was down. This results in reaching end-to-end consistency. \r
-\r
-*Reset* - Defense4All lets you reset its dynamically obtained data and configuration information (factory reset). This enables you to overcome many logical errors and mis-configurations. Note that a Defense4All restart or failover would not overcome such problems. This mechanism is therefore complementary to the restart-failover mechanism, and should typically be applied as a last resort. \r
-\r
-*Failure Isolation and Health Tracker* - In Defense4All, failure isolation takes place in the form of a failure of immediate recovery or compensation (as much as possible), and a failure recording in a special module called Health Tracker. Except for a handful of substantial failures (such as a failure to start the Framework), no failure in any module immediately causes Defense4All to stop. Instead, each module records each failure in its scope, providing severity specifications and an indication of failure permanence. If the combined severity (permanent or temporary) of all failures exceeds a globally set threshold, the HealthTracker triggers Defense4All shutdown (and revival by Linux). Later on, permanent or repeating temporary faults will cause HealthTracker to trigger Defense4All soft and dynamic reset (of dynamically obtained data) or suggest to the administrator to perform a factory reset (that also includes configuration information). \r
-\r
-*State Backup and Restore* - The administrator can snapshot the Defense4All state, save the backup in a different location, and restore to the original or new Defense4All location. This allows overcoming certain logical bugs and mis-configurations, as well as the permanent failure of the machine hosting Defense4All. To snapshot the Defense4All state, do the following: \r
-\r
-. Quiesce (shutdown) Defense4All, causing the current state to flush to stable storage). Avoid performing any configurations changes when it is brought back up, avoiding new state changes. \r
-. Take the Cassandra snapshot for Defense4All DB - "DF": For backup-restore guidelines, refer to http://www.datastax.com/docs/1.0/operations/backup_restore. \r
-. Copy the snapshot files to the desired storage archive. \r
-\r
-To restore a Defense4All backup to a target machine, do the following: \r
-\r
-. Restore the desired saved snapshot in the target machine (same as backup or different). For Cassandra backup-restore guidelines, refer to http://www.datastax.com/docs/1.0/operations/ backup_restore. \r
-. Bring up Cassandra on that machine. \r
-. Bring up Defense4All on that machine. \r
-\r
-\r
+++ /dev/null
-== DLUX
-=== Setup and Run
-==== Required Technology Stack
-
-* NodeJS (Http Server, http://www.nodejs.org )
-* Bower (JavaScript Package Manager, http://bower.io )
-* GruntJS (JavaScript Task Runner, http://gruntjs.com )
-* AngularJS (JavaScript client-side framework, http://www.angularjs.org )
-* Karma (JavaScript Test Runner, http://karma-runner.github.io/ )
-* Other AngularJS/Third-party JS libraries
-
-==== Install NodeJS
-
-===== For Windows and Mac without brew:
-
-. Go to http://www.nodejs.org
-. Download and install NodeJS
-
-===== For Mac with brew installed:
-
- $ brew update
- $ brew install node
-
-===== Verify NodeJS is installed:
-
- $ npm --version
-
-==== Install required Node libraries
-
-Install the following node components using npm. For Mac, you may have to use "sudo"
-
- $ sudo npm -g install grunt-cli
- $ sudo npm -g install bower
- $ sudo npm -g install karma
- $ sudo npm -g install karma-cli
-
-
-==== Get latest DLUX code from git
-
-.Anonymous clone
-
- $ git clone http://git.opendaylight.org/gerrit/p/dlux.git
-
-.If you have a opendaylight.org account
-
- $ git clone ssh://<username>@git.opendaylight.org:29418/dlux.git
-
-==== Build the DLUX code
-
-----
- $ cd dlux/dlux-web
-
- #installs the necessary NodeJS related components for the project - will create a node_modules directory
- $ sudo npm install
-
- #installs necessary components provided by bower
- $ bower install
-
- # update dlux-web with all DLUX static resources for each module by running maven
- $ mvn clean install
-
- # run the unit tests and start karma test runner
- # this will open up the default browser pointing to karma test running and run the unit tests
- $ grunt watch
-----
-
-Hit Ctrl-C to quit
-
-==== Build DLUX Karaf feature and distribution
-
-Once you have installed all necessary modules mentioned above such as nodesjs, bower etc.. You should be able to build the DLUX feature and distribution. Run following command at DLUX home directory +/dlux+. Once successful,
-It will create DLUX Karaf distribution and DLUX Karaf feature. You can find Karaf distribution at dlux/distribution-dlux.
-
- $ mvn clean install
-
-
-==== Enable DLUX Karaf Feature
-
-Get the Opendaylight official helium distribution or use Karaf distribution of DLUX project created above.
-Unzip the Karaf distribution and go to bin directory of your distribution and run following command to start Karaf. It will start the Karaf console, which may not have any feature installed by default.
-
- $ ./karaf
-
-Install basic MD-SAL controller features on the Karaf console. I would recommend installing the following features before starting the DLUX feature.
-L2Switch feature internally enables MD-SAL data broker and openflow plugin service. L2Switch also makes sure that in topology UI, hosts are also visible along with switches. We need the mdsal-apidocs feature for yangUI in DLUX.
-
- $ feature:install odl-restconf
- $ feature:install odl-l2switch-switch
- $ feature:install odl-mdsal-apidocs
-
-Install the AD-SAL features on the Karaf console.
-
- $ feature:install odl-adsal-all
- $ feature:install odl-adsal-northbound
-
-Then, install the DLUX feature
-
- $ feature:install odl-dlux-core
-
-Once done, you should be able to access DLUX UI at
-
- http://<IP of your controller machine>:8181/dlux/index.html
-
-For login, use admin as both the username and the password. Before login, just make sure that MD-SAL features are enabled. you can check what all features are installed
-by running following command -
-
- $ feature:list -i
-
-
-==== Run standalone DLUX against the controller
-
-* Start Karaf distribution with installed MD-SAL and AD-SAL features.
-* Goto mininet VM and create a topology for the controller
-
-Based on where you controller is running, Update baseUrl in file dlux/dlux-web/config/development.json.
-
-Back in the DLUX terminal, run
-
- $ grunt live
-
-Open a browser and go to the URL
-
- http://localhost:9000/dlux/index.html
-
-This should bring up the DLUX UI and pull data from the controller. Use admin as the username and password to access the UI.
-
-=== DLUX Modules
-
-DLUX modules are the individual features such as nodes, topology etc. Each module has a defined structure and you can find all existing modules under
-/dlux/modules directory of code.
-
-==== 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
-
-First, create an empty file with the module name.
-Next, we need to surround our module with a define function. This allows RequireJs to see our module.js files. The first argument is an array who contain all the module dependencies. The second is a callback function whose body contain the AngularJs code base. The function parameters correspond with the order of dependencies. Each dependences is injected into a parameter if it is provided. Finally, we return the angular module to be able to inject it as a parameter in our others modules.
-
-For each new module, you must have at least those two dependencies :
-
-* angularAMD : It's a wrapper arround angularjs to provide an AMD (Asynchronous Module Definition) support. Which is used by RequireJs. For more information click https://github.com/amdjs/amdjs-api/blob/master/AMD.md[here].
-* 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
-
-
- 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
-If your module is only required by the main application, you will need register your angular components because the app will be already bootstrapped. Otherwise, it won't see your components on the runtime.
-
-TIP: If your module is only use by an other module, you don't have to do this step.
-
- 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 our 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. This helper has a method to easily add an item to the menu. The first parameter is an id that refers to the level of your menu and the second is a object.
-
- 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 ID parameter supports, for now, two levels of depth. So 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 controller file
-
-To include the controller file, we will use the NavHelperProvider. It contain a method who will load the given file.
-
- [...]
- NavHelperProvider.addControllerUrl('<path_to_module_folder>/<module_name>.controller');
-
-The module.js file is now complete.
-
-
-==== Create the Controllers, factory, directive, etc
-
-Creating the controller and other components are 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
-
- define(['<relative_path_to_module>/<module_name>.module'], function(module) {
- module.register.controller('ModuleCtrl', function($rootScope, $scope) {
- });
- });
-
-
-==== Append to the main file
-
-The last thing to do is to add the path of the module definition file and add the name of the angular module.
-So, edit the file app.module.js as the follows.
-
- //----Temporary-------\\
- var module = [
- [...]
- '<relative_path_module>/<module_name>.js',
- [...]
- var e = [
- [...]
- 'a_module',
- [...]
- //--------------------\\
-
-=== Yang Utils
-Yang Utils are used by yang UI to perform all CRUD operations. All of these utilities are present in yangutils.services.js file. It has following 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 ODL 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* – creates object builder = request built from filled inputs on page in JSON format. It is possible with “show preview” button. This request is sent to ODL when button PUT or POST is clicked.
-* *yinParser* – factory for reading of .xml files of yang models and creating objects hierarchy. Every statement from yang is represented by 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
-== Group-Based Policy
-
-This chapter describes the Group-Based Policy project. The Group-Based Policy project defines an application-centric policy model for OpenDaylight that separates information about application connectivity requirements from information about the underlying details of the network infrastructure.
-
-=== Group-Based Policy Architecture Overview
-
-.Group-Based Policy Architecture
-
-image::Group-based_policy_architecture.png[Group-Based Policy Architecture]
-
-State repositories (blue) communicate using MD-SAL (orange) with external orchestration systems as well as internally with renderers (green) through the renderer common framework (red).
-
-The components of the architecture are divided into two main categories. First, there are components that are responsible for managing the policy, configuration, and related state. These are the components that deal with the higher-order group-based policy that exists independent of the underlying infrastructure. Second, the renderer components that are responsible for applying the policy model to the underlying network infrastructure. The system can support potentially a variety of renderers that may have very different sets of features and different approaches for enabling the policy that the user has requested.
-
-The key to understanding the architecture is to first understand the policy model -- much of the design of the system flows directly from the design of the policy model.
-
-=== Policy Model
-
-The policy model is built around the idea of placing endpoints into groups that share the same semantics, and then defining what other groups those endpoints need to communicate, and then finally defining how these endpoints need to communicate. In this way, we represent the requirements of the application and then force the infrastructure to figure out how to meet these requirements, rather than defining the policy in terms of the underlying infrastructure.
-
-==== Policy Model UML Diagrams
-
-[NOTE]
-========
-The UML diagrams included here are *not* normative. They attempt to provide a pictorial representation of the group-based policy model. In the event of any conflicts, the RESTful interfaces that are generated dynamically from the group-based policy yang models are normative. The group-based policy yang models can be found at './groupbasedpolicy/groupbasedpolicy/src/main/yang/model/'.
-========
-
-.Policy Model: Contract Selection
-
-image::GBP-model-contract-selection.png[width="46%"]
-
-.Policy Model: Clauses and Subject Selection
-
-image::GBP-model-clauses.png[width="30%"]
-
-.Policy Model: Subject Contents
-
-image::GBP-model-subjects.png[width="50%"]
-
-.Policy Model: Forwarding
-
-image::GBP-model-forwarding.png[width="57%"]
-
-
-==== Policy Concepts
-
-This section describes some of the most important concepts in the policy model. See the next section on <<policy_resolution,Policy Resolution>> for a description of how these fit together to determine how to apply the policy to the network.
-
-Endpoint::
-An _endpoint_ is a specific device in the network. It could be a VM interface, a physical interface, or other network device. Endpoints are defined and assigned to endpoint groups through mechanisms that are not specified by the policy model (See <<endpoint_repository,Endpoint Repository>> for more information). Endpoints can have associated _conditions_ that are just labels that represent some potentially-transient status information about an endpoint.
-Endpoint Group::
-_Endpoint groups_ are sets of endpoints that share a common set of policies. Endpoint groups can participate in _contracts_ that determine the kinds of communication that is allowed. They also expose both _requirements_ and _capabilities_, which are labels that help to determine how contracts will be applied. An endpoint group is allowed to specify a parent endpoint group from which it inherits.
-Contract::
-_Contracts_ determine which endpoints can communicate and in what way. Contracts between pairs of endpoint groups are selected by the contract selectors defined by the endpoint group. Contracts expose _qualities_, which are labels that can help endpoint groups to select contracts. Once the contract is selected, contracts have _clauses_ that can match against requirements and capabilities exposed by endpoint groups, as well as any conditions that may be set on endpoints, in order to activate _subjects_ that can allow specific kinds of communication. A contracts is allowed to specify a parent contract from which it inherits.
-Clause::
-_Clauses_ are defined as part of a contract. Clauses determine how a contract should be applied to particular endpoints and endpoint groups. Clauses can match against requirements and capabilities exposed by endpoint groups, 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.
-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.
-
-[[policy_resolution]]
-==== Introduction to Policy Resolution
-
-There are a lot of concepts to unpack and it can be difficult to see how this all fits together. Let's imagine that we want to analyze a particular flow of traffic in the network and walk through the policy resolution process for that flow. The key here is that the policy resolution process happens logically in three phases. First, we need to select the contracts that are in scope for the endpoint groups of the endpoints of the flow. Next, we select the set of subjects that apply to the endpoints of the flow. Finally, we apply the rules from the applicable subjects to the actual network traffic in the flow.
-
-Note that this description gives a semantic understanding of how the policy model should be applied. The steps described here may or may not correspond to an actual efficient implementation of this policy model.
-
-===== Contract Selection
-
-The first step in policy resolution is to select the contracts that are in scope. For a particular flow, we look up the endpoint groups for each of the endpoints involved in the flow.
-
-Endpoint groups participate in contracts either as a _provider_ or as a _consumer_. Each endpoint group 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 endpoint group to select a contract: either with a _named selector_ or with a _target selector_. Named selectors simply select a specific contract by its contract ID. 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.
-
-So to determine which contracts are in scope for our flow, we must find contracts where either the source endpoint group selects a contract as either a provider or consumer, while the destination endpoint group matches against the same contract in the corresponding role. So if endpoint _x_ in endpoint group _X_ is communicating with endpoint _y_ in endpoint group _Y_, a contract _C_ is in scope if either _X_ selects _C_ as a provider and _Y_ selects _C_ as a consumer, or _X_ selects _C_ as a consumer and _Y_ selects _C_ as a provider.
-
-The details of how quality matchers work are described further below in <<matchers,Matchers>>. For now, we can simply state that quality matchers provide a flexible mechanism for selecting the contract 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 endpoint group ID
-* The name of the selector in the provider endpoint group that was used to select the contract, which we'll call the _matching provider selector_.
-* The consumer endpoint group ID
-* The name of the selector in the consumer endpoint group that was used to select the contract, which we'll call the _matching consumer selector_.
-
-===== Subject Selection
-
-The second phase in policy resolution is to determine which subjects are in scope. The subjects allow us to define what kinds of communication are allowed between endpoints in the endpoint groups. For each of the selected contract scopes from the contract selection phase, we'll need to apply the subject selection procedure.
-
-Before we can discuss how the subjects are matched, we need to first examine what we match against to bring those subjects into scope. We match against labels called, capabilities, requirements and conditions. Endpoint groups have capabilities and requirements, while endpoints have conditions.
-
-====== Requirements and Capabilities
-
-When acting as a provider, endpoint groups expose _capabilities_, which are labels representing specific pieces of functionality that can be exposed to other endpoint groups that may meet functional requirements of those endpoint groups. When acting as a consumer, endpoint groups expose _requirements_, which are labels that represent that fact that the endpoint group requires some specific piece of functionality. As an example, we might create a capability called "user-database" which indicates that an endpoint group contains endpoints that implement a database of users. We might create a requirement also called "user-database" to indicate an endpoint group 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.
-
-We examine the matching provider selector (that was used by the provider endpoint group to select the contract) to determine the capabilities exposed by the provider endpoint group 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 endpoint group (See <<inheritance,Inheritance>> below). 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." We'll be able to use these conditions 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.
-
-Conditions do not actually appear in the policy configuration model other than as a named reference. To determine the set of conditions that apply to a particular endpoint, the endpoint will need to be looked up in the endpoint registry, and it associated condition labels retrieved from there.
-
-====== Clauses
-
-Clauses are what will do the actual selection of subjects. A clause has four lists of matchers in two categories. In order for a clause to become active, all four 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 endpoint group and endpoints. The consumer matchers are:
-
-Requirement matchers::
-matches against requirements in the matching consumer selector.
-Consumer condition matchers::
-matches against conditions on endpoints in the consumer endpoint group
-
-The second category is the provider matchers, which match against the provider endpoint group and endpoints. The provider matchers are:
-
-Capability matchers::
-matches against capability in the matching provider selector.
-Provider condition matchers::
-matches against conditions on endpoints in the provider endpoint group
-
-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]]
-===== Rule Application
-
-Now that we have a list of subjects that apply to the traffic between a particular set of endpoints, we're ready to describe how we actually apply policy to allow those 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 some service chain. For more information on how classifiers and actions are defined, see below under <<subject_features,Subject Features>>.
-
-If and only if _all_ classifiers on a rule matches, _all_ the actions on that rule are applied (in order) to the traffic. Only the first matching rule will apply.
-
-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.
-
-We've now reached final phase in the three-phases policy resolution process. First, we found the set of contract scopes to apply. Second, we found the set of subjects to apply. Finally, we saw how we apply the subjects to traffic between pairs of endpoints in order to realize the policy. The remaining sections will fill in additional detail for the policy resolution process.
-
-[[matchers]]
-==== Matchers
-
-Matchers have been mentioned a few times now without really explaining what they are. 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 are 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 matchers and capability matchers are used in clauses during the subject selection phase to match against requirements and capabilities on endpoint groups
-* Condition matchers are 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, or "none," which means the matcher matches when none of its labels match. Note that a matcher which always matches 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.
-
-There are some additional semantics related to inheritance. Please see the section for <<inheritance,Inheritance>> for more details.
-
-===== Quality Matchers
-
-A contract contains _targets_ that are just a set of quality labels. A target selector on an endpoint group matches against these targets using quality matchers. A quality matcher is a matcher where the label it matches is a quality, and the name field is a target name.
-
-===== Requirement and Capability Matchers
-
-The matching selector from the contract selection phase will define either requirements or capabilities for the consumer and provider endpoint groups, respectively. Clauses can match against these labels using requirement and capability matchers. Requirements matchers match against requirements while capability matchers match against capabilities. In both cases, the name field is a selector.
-
-===== Condition Matcher
-
-Endpoints can have condition labels. The condition matcher can be used in a clause to match against endpoints with particular combinations of conditions.
-
-==== Tenants
-The system allows multiple tenants that are designed to allow separate domains of administration. Contracts and endpoint groups are defined within the context of a particular tenant. Endpoints that belong to endpoint groups in separate tenants cannot communicate with each other except through a special mechanism to allow cross-tenant contracts called _contract references_.
-
-While it would be be possible to define semantics for tenant inheritance, as currently defined there is no way for tenants to inherit from each other. There is, however, a limited mechanism through the special _common tenant_ (see <<common_tenant,Common Tenant>> below). All references to names are within the scope of that particular tenant, with the limited exceptions of the common tenant and contract references.
-
-===== Contract References
-Contract references are the mechanism by which endpoints in different tenants can communicate. This is especially useful for such common use cases as gateway routers or other shared services. In order to for an endpoint group to select a contract in a different tenant, there must first exist a contract reference defined in the endpoint group's local tenant. The contract reference is just a tenant ID and a contract ID; this will bring that remote contract into the scope of the local contract. Note that this reference may be subject to additional access control mechanisms.
-
-Endpoint groups can participate in such remotely-defined contracts only as consumers, not as providers.
-
-Once the contract reference exists, endpoint groups can now select that contract using either named or target selectors. By defining a contract reference, the qualities and targets in that contract are imported into the namespace of the local tenant for the contract selection phase. Similarly, the requirements and conditions from the local tenant will be used when performing the consumer matches in the subject selection phase.
-
-[[common_tenant]]
-===== Common Tenant
-
-The common tenant is an area where definitions that are useful for all tenants can be created. Everything defined in the common tenant behaves exactly as though it were defined individually in every tenant. This applies to resolution of labels for the purposes of contract selection, as well as subject feature instances (see <<subject_features,Subject Features>> below).
-
-If a name exists in both the common tenant and another tenant, then when resolving names within the context of that tenant the definition in the common tenant will be masked. One special case to consider is if a definition in a tenant defines the common tenant definition as its parent and uses the same name as the parent object. This works as you might expect: the name reference from the child definition will extend the behavior of the definition in the common tenant, but then mask the common tenant definition so that references to the name within the tenant will refer to the extended object.
-
-[[subject_features]]
-==== Subject Features
-
-Subject features are objects that can be used as a part of a subject to affect the communication between pairs of endpoints. This is where the policy model meets the underlying infrastructure. Because different networks will have different sets of features, we need some way to represent to the users of the policy what is possible. Subject features are the answer to this.
-
-There are two kinds of subject features: classifiers and actions. Classifiers match on traffic between endpoints, and actions perform some operation on that traffic (See <<rule_application,Rule Application>> above for more information on how they are used).
-
-Subject features are defined with a subject feature definition. The definition defines a name and description for the feature, along with a set of parameters that the item can take. This is the most general description for the subject feature, and this definition is global and applies across all tenants. As an example, a classifier definition might be called "tcp_port", and would take an integer parameter "port".
-
-Next, there are subject feature instances. Subject feature instances are scoped to a particular tenant, and reference a subject feature definition, but fill in all required parameters. To continue our example, we might define a classifier instance called "http" that references the "tcp_port" classifier and species the parameter "port" as 80.
-
-Finally, there are subject feature references, which are references to subject feature instances. Subjects contain these subject feature references in order to apply the feature. These references also contain, as appropriate an order field to determine order of operations and fields for matching the direction of the traffic.
-
-If the underlying network infrastructure is unable to to implement a particular subject, then it must raise an exception related to that subject. It may then attempt to relax the constraints in a way that allows it to implement the policy. However, when doing this it must attempt to avoid allowing traffic that should not be allowed. That is, it should "fail closed" when relaxing constraints.
-
-==== Forwarding Model
-
-Communication between endpoint groups can happen at layer 2 or layer 3, depending on the policy configuration. We define our model of the forwarding behavior in a way that supports very flexible semantics including overlapping layer 2 and layer 3 addresses.
-
-We define several kinds of _network domains_, which represent some logical grouping or namespace of network addresses:
-
-L3 Context::
-A layer 3 context represents a namespace for layer 3 addresses. It represents a domain inside which endpoints can communicate without requiring any address translation. A subtype of a forwarding context, which is a subtype of a network domain.
-L2 Bridge Domain::
-A layer 2 bridge domain represents a domain in which layer 2 communication is possible when allowed by policy. Bridge domains each have a single parent L3 context. A subtype of an L2 domain, which is a subtype of a forwarding context.
-L2 Flood Domain::
-A layer 2 flood domain represents a domain in which layer 2 broadcast and multicast is allowed. L2 flood domains each have a single parent L2 bridge domain. A subtype of an L2 domain.
-Subnet::
-An IP subnet associated with a layer 2 or layer 3 context. Each subnet has a single parent forwarding context. A subtype of a network domain.
-
-Every endpoint group references a single network domain.
-
-[[inheritance]]
-==== Inheritance
-
-This section contains information on how inheritance works for various objects in the system. This is covered here to avoid cluttering the main sections with a lot of details that would make it harder to see the big picture.
-
-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.
-
-===== Endpoint Groups
-
-Endpoint groups will inherit all their selectors from their parent endpoint groups. Selectors with the same names as selectors in the parent endpoint groups 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 endpoint group, then they will inherit from and override the behavior of the selector in the parent endpoint group.
-
-[red]*Named Selectors*
-
-Named selectors will add to the set of contract IDs that are selected by the parent named selector.
-
-[red]*Target Selectors*
-
-A target selector in the child endpoint group with the same name as a target selector in the parent endpoint group 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. There is no meaningful overriding possible here; it's just a union operation. Note of course though that 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 <<inheritance_matchers,Matchers>> for more information.
-
-[[inheritance_matchers]]
-===== 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.
-
-===== Subject Feature Definitions
-
-Subject features definitions, including classifier definitions and subject definitions can also inherit from each other by specifying a parent object. These are a bit different from the other forms of override because they do not merely affect the policy resolution process, but rather affect how the policy is applied in the underlying infrastructure.
-
-For the purposes of policy resolution, a subject feature will inherit from its parent any named parameters. However, unlike in other cases, if a named parameter with the same name exists in the child as in the parent, this is an invalid parameter and will be ignored in the child. That is, the child _cannot_ override the type of a named parameter in a child subject feature.
-
-For the purposes of applying the subject in the underlying infrastructure, the child subject feature is assumed to add some additional functionality to the parent subject feature such that the child feature is a specialization of that parent feature. For example, there might be a classifier definition for matching against a TCP port, and a child classifier definition that allowed for deep packet inspection for a particular protocol that extended the base classifier definition. In this case, the child classifier would be expected to match the TCP port as well as apply its additional deep packet inspection semantics.
-
-If the underlying infrastructure is unable to apply a particular subject feature, it can attempt to fall back to implementing instead the parent subject feature. The parameter fallback-behavior determines how this should apply. If this is set to "strict" then a failure to apply the child is a fatal error and the entire subject must be ignored. If the fallback behavior is "allow-fallback" then the error is nonfatal and it is allowed to apply instead only the parent subject feature.
-
-=== State Repositories
-
-The state repositories are distributed data stores that provide the configuration and operational data required for renderers to apply the policy as specified by the user. The state repositories all model their state as yang models, and store that state in the MD-SAL data store as either operational or configuration data, as appropriate. The state repositories implement a minimum amount of actual functionality and instead focus on defining the models and supporting the correct querying and subscription semantics. The intelligence is expected to be in the renderers.
-
-==== Querying and Subscription
-
-State repositories support both simple queries on the data but more important allow subscriptions to the data, so that systems that are responsible for applying the policy model are informed about changes to that policy configuration or operational state that might affect the policy. Those subsystems are expected to continuously reevaluate the policy as these changes come in make the required changes in the underlying infrastructure.
-
-[[endpoint_repository]]
-==== Endpoint Repository
-
-The endpoint repository is responsible for storing metadata about endpoints, including how they are mapped into endpoint groups. Information about endpoints can be added to the repository either by a central orchestration system or by a renderer that performs discovery to learn about new endpoints. In either case, the semantics of how an endpoint is mapped to an endpoint group are not defined here; the system that sets up the information in the endpoint repository must have its own method for assigning endpoints to endpoint groups.
-
-==== Policy Repository
-
-The policy repository stores the policies themselves. This includes endpoint groups, selectors, contracts, clauses, subjects, rules, classifiers, actions, and network domains (everything in the policy model except endpoints and endpoint-related metadata). The policy repository is populated through the northbound APIs.
-
-==== Status Repository
-
-The status repository will be added in a future release of group-based policy.
-
-=== Renderers
-
-One of the key design features of the group-based policy architecture is that it can support a variety of renderers based on very different underlying technology. This is possible because the policy model is based only on high-level user intent, and contains no information about the details of how the network traffic is actually forwarded. However, one consequence of this design choice is that the renderers actually contain most of the complexity in the design of the system, and most of the real problems in building a software-defined virtual network solution will need to be solved by the renderers themselves.
-
-==== Renderer Common Framework
-
-The renderers have available to them some service and libraries that collectively make up the _renderer common framework_. These are not actually required to implement a renderer, but where convenient functionality that would be generally useful should be placed here.
-
-===== `InheritanceUtils`
-
-This class provides a convenient utility to resolve all the complex inheritance rules into a normalized view of the policy for a tenant.
-
-[source,java]
-----
- /**
- * Fully resolve the specified {@link Tenant}, returning a tenant with all
- * items fully normalized. This means that no items will have parent/child
- * relationships and can be interpreted simply without regard to inheritance
- * rules
- * @param tenantId the {@link TenantId} of the {@link Tenant}
- * @param transaction a {@link DataModificationTransaction} to use for
- * reading the data from the policy store
- * @return the fully-resolved {@link Tenant}
- */
- public static Tenant resolveTenant(TenantId tenantId,
- DataModificationTransaction transaction)
-----
-
-===== `PolicyResolverService`
-
-The policy resolver service resolves the policy model into a representation suitable for rendering to an underlying network. It will run through the contract resolution and
-
-The policy resolver is a utility for renderers to help in resolving group-based policy into a form that is easier to apply to the actual network.
-
-For any pair of endpoint groups, there is a set of rules that could apply to the endpoints on that group based on the policy configuration. The exact list of rules that apply to a given pair of endpoints depends on the conditions that are active on the endpoints.
-
-In a more formal sense: Let there be endpoint groups _G~n~_, and for each _G~n~_ a set of conditions _C~n~_ that can apply to endpoints in _G~n~_. Further, let _S_ be the set of lists of rules defined in the policy. Our policy can be represented as a function _F_: (_G~n~_, 2 _^C~n~^_, _G~m~_, 2 _^C~m~^_) \-> _S_, where 2 _^C~n~^_ represents the power set of _C~m~_. In other words, we want to map all the possible tuples of pairs of endpoints along with their active conditions onto the right list of rules to apply.
-
-We need to be able to query against this policy model, enumerate the relevant classes of traffic and endpoints, and notify renderers when there are changes to policy as it applies to active sets of endpoints and endpoint groups.
-
-The policy resolver will maintain the necessary state for all tenants in its control domain, which is the set of tenants for which policy listeners have been registered.
-
-[[ovs_overlay]]
-==== Open vSwitch-Based Overlay Renderers
-
-This section describes a data plane architecture for building a network virtualization solution using Open vSwitch. This data plane design is used by two renderers: the <<openflow_renderer,OpenFlow Renderer>> and the <<opflex_renderer,OpFlex Renderer>>.
-
-The design implements an overlay design and is intended to meet the following use cases:
-
-* Routing when required between endpoint groups, including serving as a distributed default gateway.
-* Optional broadcast within a bridge domain.
-* Management of L2 broadcast protocols including ARP and DHCP to avoid broadcasting.
-* Layer 2-4 classifiers for policy between endpoint groups, including connection tracking/reflexive ACLs.
-* Service insertion/redirection
-
-===== Network Architecture
-
-====== Network Topology
-
-The network architecture is an overlay network based on VXLAN or similar encapsulation technology, with an underlying IP network that provides connectivity between hypervisors and the controller. The overlay network is a full-mesh set of tunnels that connect each pair of vSwitches.
-
-The "underlay" IP network has no special requirements though it should be set up with ECMP to the top-of-rack switch for the best performance, but this is not a strict requirement for correct behavior. Also, the underlay network should be configured with a path MTU that's large enough to accommodate the overlay tunnel headers. For a typical overlay network with a 1500 byte MTU, a 1600 byte MTU in the underlay network should be sufficient. If this is not configured correctly, the behavior will be correct but it will result in fragmentation which could have a severe negative effect on performance.
-
-Physical devices such as routers on the IP network are trusted entities in the system since these devices would have the ability to forge encapsulated packets.
-
-[[network_topology_example]]
-.GBP OVS Network Topology Example
-
-image::gbp_overlay_design_red_tunnel.png[width="80%"]
-
-The <<network_topology_example,Network Topology Example>> figure shows an example of a supported network topology, with an underlying IP network and hypervisors with Open vSwitch. Infrastructure components and elements of the underlay network are shown in grey. Three endpoint groups exist with different subnets in the same layer 3 context, which are show in red, green, and blue. A tunneled path (dotted red line) is shown between two red virtual machines on different VM hosts.
-
-====== Control Network
-
-The security of the system depends on keeping a logically isolated control network separate from the data network, so that guests cannot reach the control network. Ideally, the network is kept isolated through an out-of-band control network. This can be accomplished using a separate NIC, a special VLAN, or other mechanism. However, the system is also designed to operate in the case where the control traffic and the data traffic are on the same layer 2 network and isolation is still enforced.
-
-In the <<network_topology_example,Network Topology Example>> figure above, the control network is shown as 172.16/16. The VM hosts, and controllers all have addresses on this network, and communicate using OpenFlow and OVSDB on this network. In the example, the router is shown with an interface configured on this network as well; this works but in practice it is preferable to isolate this network by accessing it through a VPN or jump box if needed. Note that there is no requirement that the control network be all in one subnet.
-
-The router is also shown with an interface configured on the 10/8 network. This network will be used for routing traffic destined for internet hosts. Both the 172.16/16 and 10/8 networks here are isolated from the guest address spaces.
-
-====== Overlay Network
-
-Whenever traffic between two guests is in the network, it will be encapsulated using a VXLAN tunnel (though supporting additional encapsulation formats could be configured in the future). A packet encapsulated as VXLAN contains:
-
-* Outer ethernet header, with source and destination MAC
-* Outer IP header, with source and destination IP address
-* Outer UDP header
-* VXLAN header, with a virtual network identifier (VNI). The virtual network identifier is a 24-bit field that uniquely identifies an endpoint group in our policy model.
-* Encapsulated original packet, which includes:
-** Inner ethernet header, with source and destination MAC
-** (Optional) Inner IP header, with source and destination IP address
-
-====== Delivering Packets
-
-Endpoints can communicate with each other in a number of different ways, and each is processed slightly differently. Endpoint groups exist inside a particular layer 2 or layer 3 context which represents a namespace for their network identifiers. It's only possible for endpoints to address endpoints within the same context, so no communication is possible for endpoints in different layer 3 contexts, and only layer 3 communication is possible for endpoints in different layer 2 contexts.
-
-[red]*Overlay Tunnels*
-
-The next key piece of information is the location of the destination endpoint. For destinations on the same switch, we can simply apply policy (see below), perform any routing action required (see below), then deliver it to the local port.
-
-When the endpoints are located on different switches, we need to use the overlay tunnel. This is the case shown as a dotted red line in the <<network_topology_example,Network Topology Example>> figure. After policy is applied to the packet, we encapsulated it in a tunnel with the tunnel ID set to a unique ID for the destination endpoint group. The outer packet is addressed to the IP address of the OVS host that hosts the destination endpoint. This encapsulated packet is now sent out to the underlay network, which is just a regular IP network that can deliver the packet to the destination switch.
-
-When the encapsulated packet arrives on the other side, the destination vSwitch inspects the metadata of the encapsulation header to see if the policy has been applied already. If the policy has not been applied or if the encapsulation protocol does not support carrying of metadata, the policy must be applied at the destination vSwitch. The packet can now be delivered to the destination endpoint.
-
-[red]*Bridging and Routing*
-
-The system will transparently handle bridging or routing as required. Bridging occurs between endpoints in the same layer 2 context, while routing will generally be needed for endpoints in different layer 2 contexts. More specifically, a packet needs to be routed if it is addressed to the gateway MAC address. We can simply use a fixed MAC address to serve as the gateway everywhere. Packets addressed to any other MAC address can be bridged.
-
-Bridged packets are easy to handle, since we don't need to do anything special to them to deliver them to the destination. They can be simply delivered unmodified.
-
-Routing is slightly more complex, though not massively so. When routing locally on a switch, we simply rewrite the destination MAC address to the MAC of the destination endpoint, and set the source MAC to the gateway MAC, decrement the TTL, and then deliver it to the correct local port.
-
-When routing to an endpoint on a different switch, we'll actually perform routing in two steps. On the source switch, we will decrement TTL and rewrite the source MAC address to the MAC of the gateway router (so that both the source and the destination MAC are set to the gateway router's MAC). It's then delivered to the destination switch using the appropriate tunnel. On the destination switch, we perform a second routing action by now rewriting the destination MAC as the MAC address of the destination endpoint and decrementing the TTL again. The reason why do the routing as two hops is that this avoids the need to maintain on every switch the correct MAC address for every endpoint on the network. Each switch needs the mappings only for endpoints that are directly attached to that switch. An example of a communication pathway requiring this routing is shown in the figure below.
-
-.GBP OVS Routing Example
-
-image::gbp_overlay_design_blue_to_red_tunnel.png[width="80%"]
-
-In this example, we show the path of traffic from the blue guest 192.168.2.3 and the red guest 192.168.1.2. The traffic is encapsulated in a tunnel marked with the blue endpoint group's VNI while in transit between the two switches. Because two endpoints are in different subnets, the traffic is routed in two hops: one the source switch and one on the destination switch.
-
-The vSwitch on each host must respond to local ARP requests for the gateway IP address and return a logical MAC address representing the L3 gateway.
-
-[red]*Communicating with Outside Hosts*
-
-Everything up until now is quite simple, but it's possible to conceive of situations where endpoints in our network need to communicate over the internet or with other endpoints outside the overlay network. There are two broad approaches for handling this. In both cases, we allow such access only via layer 3 communication.
-
-First, we can map physical interfaces on an OVS system into the overlay network. If a router interface is attached either directly to a physical interface or indirectly via an isolated network, then the router interface can be easily exposed as an endpoint in the network. Endpoints can then communicate with this router interface (perhaps after some intermediate routing via the distributed routing scheme described above) and from there get to the rest of the world. Dedicated OVS systems can be thus configured as gateway devices into the overlay network which will then be needed for any of this north/south communication. This has the advantage of being very conceptually simple but requires special effort to load balance the traffic effectively.
-
-Second, we can use a DNAT scheme to allow access to endpoints that are reachable via the underlay network. In this scheme, for every endpoint that is allowed to communicate to these outside hosts, we allocate an IP address from a dedicated set of subnets on the underlay (each network segment in the underlay network will require a separate DNAT range for switches attached to that subnet). We can perform the DNAT translation on the OVS switch and then simply deliver the traffic to the underlay network to deliver to the internet host or other host, and perform the reverse translation to get back into the overlay network.
-
-.GBP OVS Example of Communication With Outside Endpoints
-
-image::gbp_overlay_design_red_to_outside.png[width="80%"]
-
-An example of communication with outside endpoints using the DNAT scheme is shown in the figure above. In this example, the red endpoint is communicating with an endpoint on the internet through a gateway router. The traffic goes through a DNAT translation to an IP allocated to the endpoint for this purpose. The IP communication can then be delivered through the IP underlay network.
-
-For the first implementation, we'll stick with the DNAT scheme and consider implementing the gateway-based or other solution.
-
-===== Packet Processing Pipeline
-
-.GBP OVS Packet Processing Pipeline
-
-image::gbp_ovs_pipeline.png[width="65%"]
-
-Here is a simplified high-level view of what happens to packets in this network when it hits an OVS instance:
-
-. If data and management network are shared, determine whether packet is targeted for the host system. If so, reinject into host networking stack.
-. Apply port security rules if enabled on the port to determine if the source identifiers (MAC and IP) are allowed on the port
- * For packets received from the overlay: Determine the source endpoint group (sEPG) based on the tunnel ID from the outer packet header.
- * For packets received from local ports: Determine sEPG based on source port and source identifiers as configured.
- * As an sEPG can only be associated with a single L2 and L3 context, the context is determined in this step as well.
- * Unknown source identifiers may result in a packet-in if the network is doing learning.
-. Handle broadcast and multicast packets while respecting broadcast domains.
-. Catch any special packet types that are handled specially. This could include ARP, DHCP, or LLDP. How these are handled may depend on the specific renderer implementation.
-. Determine whether the packet will be bridged or routed. If the destination MAC address is the default gateway MAC, then the packet will be routed, otherwise it will be bridged.
-. Determine the destination endpoint group (dEPG) and outgoing port or next hop while respecting the L2/L3 context.
- * For bridged packets (L2): Determine based on the destination MAC address.
- * For routed packets (L3): Determine based on the destination IP address.
-. Apply the appropriate set of policy rules based on the active subjects for that flow. We can bypass this step if the tunnel metadata indicates hat the policy has been applied at the source.
-. Apply a routing action if needed by modifying the destination and source MAC and decrementing the TTL.
- * For local destination: Rewrite the destination MAC to the MAC address for the connected endpoint, source MAC to the MAC of the default gateway.
- * For remote destinations: Rewrite the destination MAC to the MAC of the next hop, source MAC to the MAC of the default gateway.
-. If the next hop is a local port, then it is delivered as-is. If the next hop is not local, then the packet is encapsulated and the tunnel ID is set to the network identifier for the source endpoint group (sEPG). If the packet is a layer 2 broadcast packet, then it will need to be written to the correct set of ports, which might be a combination of local and multiple remote tunnel endpoints.
-
-====== Register Usage
-
-The processing pipeline needs to store metadata such as the sEPG, dEPG, and broadcast domain. This metadata can be stored in any way supported by the switch. OpenFlow provides a dedicated 64 bit metadata field, Open vSwitch additionally provides multiple 32 bit registers in form of Nicira Extensions. The following examples will use Nicira extensions for simplicity. The choice of register usage is an implementation detail of the renderer.
-
-*Option 1: Register allocation using Nicira Extensions*
-
-[cols="1m,4",options="header"]
-|====
-|Register|Value
-|NXM_NX_REG1 |Source Endpoint Group (sEPG) ID
-|NXM_NX_REG2 |L2 context (BD)
-|NXM_NX_REG3 |Destination Endpoint Group (dEPG) ID
-|NXM_NX_REG4 |Port number to send packet to after policy enforcement. This is required because port selection occurs before policy enforcement in the pipeline.
-|NXM_NX_REG5 |L3 context ID (VRF)
-|====
-
-*Option 2: Register allocation using OpenFlow metadata*
-
-OpenFlow offers a single 64 bit register which can be used to store sEPG, dEPG, and BD throughout the lookup process alternatively. The advantage over using Nicira extensions is better portability and offload capability to hardware.
-
-[cols="1,4",options="header"]
-|====
-|Register|Value
-|metadata[0..15] |Source Endpoint Group (sEPG) ID
-|metadata[16..31] |Destination Endpoint Group (dEPG) ID
-|metadata[32..39] |L2 context (BD)
-|metadata[40..47] |L3 context (VRF)
-|metadata[48..63] |Port number to send packet to after policy enforcement. This is required because port selection occurs before policy enforcement in the pipeline.
-|====
-
-====== Table/Pipeline Names and Order
-
-In order to increase readability, the following table names are used in the following sections. Their order in the pipeline is as follows:
-
-[cols="1,3,3,5,4",options="header"]
-|=======================================
-|Table|ID|Description|Flow Hit|Flow Miss
-|1|+PORT_SECURITY+|Optional port security table|Proceed to +SEPG_FILTER+|Drop
-|2|+SEPG_FILTER+|sEPG selection|Remember sEPG, BD, and VRF. Then proceed to +DEPG_FILTER+|Trigger policy resolution (send to controller)
-|3|+DPEG_FILTER+|dEPG selection|Remember dEPG and output coordinates, proceed to +POLICY_ENFORCER+|Trigger policy resolution (send to controller)
-|4|+POLICY_ENFORCER+|Policy enforcement|Forward packet|Drop
-|=======================================
-
-OpenFlow >=1.1 capable switches can implement the flow miss policy for each table directly. Pure OpenFlow 1.0 switches will need to have a catch-all flow inserted to enforce the specified policy.
-
-====== Port Security
-
-An optional port security table can be inserted at the very beginning of the pipeline. It enforces a list of valid sMAC and sIP addresses for a specific port.
-
-----
-priority=30, in_port=TUNNEL_PORT, actions=goto_table:SEPG_FILTER
-priority=30, in_port=PORT1, dl_src=MAC1, action=goto_table:SEPG_FILTER
-priority=30, in_port=PORT2, dl_src=MAC2, ip, nw_src=IP2, actions=goto_table:SEPG_FILTER
-priority=20, in_port=PORT2, dl_src=MAC2, ip, actions=drop
-priority=10, in_port=PORT2, dl_src=MAC2, actions=goto_table:SEPG_FILTER
-priority=30, in_port=PORT3, actions=goto_table:SEPG_FILTER
-----
-
-The port-security flow-miss policy is set to drop in order for packets received on an unknown port or with an unknown sMAC/sIP to be rejected.
-
-The following modes of enforcement are defined:
-
-. Whitelisted: The port is allowed to use any addresses. All tunnel ports must be whitelisted. The filter is enforced with a single flow matching on in_port and redirects to the next table.
-. L2 enforcement: Any packet from the port must use a specific sMAC. The filter is enforced with a single flow matching on the in_port and dl_src and redirects to the next table.
-. L3 enforcement: Same as L2 enforcement. Additionally, any IP packet from the port must use a specific sIP. The filter is enforced with three flows with different priority.
-.. Any IP packet with correct sMAC and sIP is redirected to the next table.
-.. Any IP packet left over is dropped.
-.. Any non-IP packet with correct sMAC is redirected to the next table.
-
-====== Source EPG & L2/L3 Domain Selection
-
-The sEPG is determined based on a separate flow table which maps known OpenFlow port numbers and tunnel identifiers to a locally unique sEPG ID. The sEPG ID is stored in register NXM_NX_REG1 for later use in the pipeline. At the same time, the L2 and L3 context is determined and stored in register NXM_NX_REG2.
-
-[cols="1m,2",width="75%",options="header"]
-|====
-|Field|Description
-|table=SEPG_TABLE|Flow must be in sEPG selection table
-|in_port=$OFPORT|Flow must match on incoming port
-|tun_id=$VNI|If in_port is a tunnel, flow must match on tunnel ID
-|====
-
-The actions performed are:
-
-. Write sEPG ID corresponding to incoming port or tunnel ID to register
-. Write L2/L3 context ID corresponding to incoming port or tunnel ID to registers
-. Proceed to dEPG selection
-
-An example flow to map a local port to an sEPG:
-----
-table=SEPG_FILTER, in_port=$OFPORT
-actions=load:$SEPG->NXM_NX_REG1[],
- load:$BD->NXM_NX_REG2[],
- load:$VRF->NXM_NX_REG5[],
- goto_table:$DEPG_FILTER
-----
-
-An example flow to map a tunnel ID to an sEPG:
-----
-table=SEPG_FILTER, in_port=TUNNEL_PORT, tun_id=$VNI1,
-actions=load:$SEPG1->NXM_NX_REG1[],
- load:$BD->NXM_NX_REG2[],
- load:$VRF->NXM_NX_REG5[],
- goto_table:$DEPG_FILTER
-----
-
-A flow hit means that the sEPG is known and the pipeline should proceed to the next stage.
-
-A flow miss means that we have received a packet from an unknown EPG:
-
-. If the packet was received on a local port then this corresponds to the discovery of a new EP for which the Port to EPG mapping has not been populated yet. If the network is learned, generate a packet-in to trigger policy resolution, otherwise drop the packet.
-. If the packet was received from a tunnel then this corresponds to a packet for which we have not populated the tunnel ID to EGP mapping yet. If the network is learned, generate a packet-in to trigger policy resolution, otherwise drop the packet.
-
-====== Broadcasting / Multicasting
-
-Packets sent to the MAC broadcast address (+ff:ff:ff:ff:ff:ff+) must be flooded to all ports belonging to the broadcast domain. This is *not* equivalent to the OVS flood action as multiple broadcast domains reside on the same switch. The respective broadcast domains are modeled using OpenFlow group tables as follows:
-
-. Upon addition of a new broadcast domain to the local vSwitch:
- * Create a new OpenFlow group table, using the BD ID as group ID
-
- ovs-ofctl [...] add-group BRIDGE group_id=$BD, type=all
-
- * Create a flow in the dEPG selection table matching on broadcast packets and correctly have them flooded to all group members:
-
- priority=10, table=$DEPG_TABLE, reg2=$BD, dl_dst=ff:ff:ff:ff:ff:ff, actions=group:$BD
-
-. Upon addition/removal of a local port
- * Modify group and add/remove output action to port to account for membership change:
-
- osvs-ofctl [...] mod-group $BRIDGE [Old entry,] bucket=output:$PORT
-
-. Upon addition/removal of a non-local port to the BD
- * Modify group and add/remove output + tunnel action to start/stop flooding packets over overlay
-
-====== Special Packet Types
-
-[red]*ARP Responder*
-
-In order for the distributed L3 gateway to be reachable, the vSwitch must respond to ARP requests sent to the default gateway address. For this purpose, a flow is added which translates ARP requests into ARP replies and sends them back out the incoming port.
-
-[cols="1m,2",width="75%",options="header"]
-|====
-|Field|Description
-|priority=20|Must have higher priority than regular, non-ARP dEPG table flows.
-|table=DEPG_FILTER|Flow must be in dEPG selection table
-|reg5=2|Must match a specific L3 context (+NXM_NX_REG5+)
-|arp, arp_op=1|Packet must be ARP request
-|arp_tpa=GW_IP|ARP request must be targeted for IP of gateway
-|====
-
-The actions performed are:
-
-. Set dMAC to original sMAC of packet to reverse direction
-. Set sMAC to MAC of gateway
-. Set ARP operation to (arp-reply)
-. Set target hardware address to original source hardware address
-. Set source hardware address to MAC of gateway
-. Set target protocol address to original source protocol address
-. Set source protocol address to IP of gateway
-. Transmit packet back out the incoming port
-
-----
-priority=20, table=DEPG_FILTER, reg5=$VRF,
-arp, arp_op=1, arp_tpa=$GW_ADDRESS,
-actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],
- mod_dl_src:$GW_MAC,
- load:2->NXM_OF_ARP_OP[],
- move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],
- load:''Hex(''$GW_MAC'')''->NXM_NX_ARP_SHA[],
- move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],
- load:''Hex(''$GW_ADDRESS'')''->NXM_OF_ARP_SPA[],
- in_port
-----
-
-[red]*ARP Optimization*
-
-.GBP OVS ARP Optimization
-
-image::gbp_ovs_arp_optimization.png[width="50%"]
-
-As the MAC / IP pairing of endpoints is known in the network. ARP requests can be optimized and translated into unicasts. While it is possible to have a local vSwitch become an ARP responder directly, the unicast translation offers a minimal aliveness check within the scope of the L2 context.
-
-A flow is inserted into the sEPG selection table as follows:
-----
-priority=10, arp, arp_op=1, dl_dst=ff:ff:ff:ff:ff:ff, actions=controller
-----
-
-As the ARP request is received, the packet is sent to the controller. The controller/agent resolves the MAC address to the IP address and inserts a new DNAT flow to translate subsequent ARP requests for the same transport address directly in the vSwitch:
-----
- priority=15, table=DEPG_FILTER,
- arp, arp_op=1, dl_dst=ff:ff:ff:ff:ff:ff,
- actions=mod_dl_dst:$MAC,
- load:${DEPG}->NXM_NX_REG3[],
- load:${OFPORT}->NXM_NX_REG4[],
- goto_table:$ENFORCER_TABLE
-----
-
-The +OFPORT+ is either a local port or the tunnel port. The latter case requires to additionally set the tunnel ID as described in previous sections.
-
-[NOTE]
-========
-The controller can proactively insert ARP optimization flows for local or even remote endpoints to avoid the one time controller round trip penalty.
-========
-
-The controller/agent then reinjects the original ARP request back into the network via a packet-out OpenFlow message.
-
-====== Destination EPG Selection (L2)
-
-The dEPG selection is performed after the sEPG has been determined. The mapping occurs in its own flow table which contains both L2 and L3 flow entries. This section explains L2 processing, L3 processing is described in the next section.
-
-The purpose of flow entries in this table is to map known destination MAC addresses in a specific L2 context to a dEPG and to prepare the action set for execution after policy enforcement.
-
-[cols="1m,2",width="70%",options="header"]
-|====
-|Field|Description
-|priority=10|Must have lower priority than L3 flows
-|table=DEPG_FILTER|Flow must be in dEPG selection table
-|reg2=2|Must match on L2 context (NXM_NX_REG2)
-|dl_dst=MAC|Packet must match on destination MAC of the EP
-|====
-
-The actions performed are:
-
-. Write dEPG ID corresponding to dMAC to register to allow matching on it during policy enforcement
-. Write expected outgoing port number to register. This can be a local or a tunnel port.
-. If outgoing port is a tunnel, also include an action to set the tunnel ID and tunnel destination to map the sEPG to the tunnel ID.
-. Proceed to policy enforcement
-
-Example flow for a local endpoint mapping:
-----
-table=$DEPG_FILTER, reg2=$BD, dl_dst=$MAC,
-actions=load:$DEPG->NXM_NX_REG3[],
- load:$OFPORT->NXM_NX_REG4[],
- goto_table:$ENFORCER_TABLE
-----
-
-Example flow for a remote endpoint mapping:
-----
-table=$DEPG_FILTER, reg2=$BD, dl_dst=$MAC,
-actions=load:$DEPG->NXM_NX_REG3[],
- load:$TUNNEL_PORT->NXM_NX_REG4[],
- move:NXM_NX_REG1[]->NXM_NX_TUN_ID[],
- load:$TUNNEL_DST->NXM_NX_TUN_IPV4_DST[],
- goto_table:$ENFORCER_TABLE
-----
-
-A flow hit indicates that both the sEPG and dEPG are known at this point at the packet can proceed to policy enforcement.
-
-A flow miss indicates that the dEPG is not known. If the network is in learning mode, generate a packet-in, otherwise drop the packet.
-
-====== Destination EPG Selection (L3)
-
-Much like L2 flows in the dEPG selection table, L3 flows map known destination IP addresses to the corresponding dEPG and outgoing port number.
-
-Additionally, flow hits will result in a routing action performed.
-
-[cols="1m,2",width="70%",options="header"]
-|====
-|Field|Description
-|priority=15|Must have higher priority than L2 but lower than ARP flows.
-|table=DEPG_FILTER|Flow must be in dEPG selection table
-|reg5=2|Must match on L3 context (NXM_NX_REG5)
-|dl_dst=GW_MAC|Packet must match MAC of gateway
-|nw_dst=PREFIX|Packet must match on a IP subnet
-|====
-
-The actions performed are:
-
-. Write dEPG ID corresponding to destination subnet to register to allow matching on it during policy enforcement
-. Write expected outgoing port number to register. This can be a local or a tunnel port
-. If outgoing port is a tunnel, also include an action to set the tunnel ID and tunnel destination to map the sEPG to the tunnel ID.
-. Modify destination MAC to the nexthop. The nexthop can be the MAC of the EP or another router.
-. Set source MAC to MAC of local default gateway
-. Decrement TTL
-. Proceed to policy enforcement
-
-Example flow for a local endpoint over L3:
-
-----
-table=DEPG_TABLE, reg5=$VRF, dl_dst=$ROUTER_MAC, ip, nw_dst=$PREFIX,
-actions=load:$DEPG->NXM_NX_REG3[],
- load:$OFPORT->NXM_NX_REG4[],
- mod_dl_dst:$DST_EP_MAC,
- mod_dl_src:$OWN_ROUTER_MAC,
- dec_ttl,
- goto_table:$POLICY_ENFORCER
-----
-
-Example flow for a remote endpoint over L3:
-
-----
-table=DEPG_TABLE, reg5=$VRF, dl_dst=$ROUTER_MAC, ip, nw_dst=$PREFIX,
-actions=load:$DEPG->NXM_NX_REG3[],
- load:$TUNNEL_PORT->NXM_NX_REG4[],
- move:NXM_NX_REG1[]->NXM_NX_TUN_ID[],
- load:$TUNNEL_DST->NXM_NX_TUN_IPV4_DST[],
- mod_dl_dst:$NEXTHOP,
- mod_dl_src:$OWN_ROUTER_MAC,
- dec_ttl,
- goto_table:$POLICY_ENFORCER
-----
-
-====== Policy Enforcement
-
-Given the sEPG, BD/VRF, and dEPG are known at this point, the policy is enforced in a separate flow table by matching on the sEPG and dEPG as found in the respective registers. Additional filters may be provided as specified by the policy.
-
-[cols="1m,2",width="80%",options="header"]
-|====
-|Field|Description
-|table=POLICY_ENFORCER|Flow must be in policy enforcement table.
-|reg1=$SEPG|Must match on sEPG of packet
-|reg3=$DEPG|Must match on dEPG of packet
-|====
-
-The policy may require to match on additional fields such as L3 ports, TCP flags, labels, conditions, etc.
-
-The actions performed on flow hit depend on the specified policy and are described in the next section.
-
-Example of a flow in the policy enforcement table:
-----
-table=$POLICY_ENFORCER reg1=$SEPG, reg3=$DEPG, tcp_dst=DPORT/MASK,
-actions=output:NXM_NX_REG4[]
-----
-
-A flow miss indicates that no policy has been specified or the policy has not been populated. Depending
-on whether the policy population is proactive or reactive, the action on flow miss is either drop or
-notification of the controller/agent to trigger policy resolution.
-
-====== Policy Actions & Packet Rewrite
-
-The policy may specify multiple actions which are to be performed on matching policy classifiers.
-The following actions are supported:
-
-[red]*Accept*
-
-Forward/route the packet as previously selected in the dEPG selection table. This translates to
-executing the queued up action set and forwarding the packet to the port number stored in
-+NXM_NX_REG4+ which represents the L2 nexthop.
-
-Basic example flow to allow an sEPG talk to a dEPG:
-----
-table=$POLICY_ENFORCER reg1=$SEPG, reg3=$DEPG,
-actions=output:NXM_NX_REG4[]
-----
-
-[red]*Drop*
-
-Disregard any previous forwarding or routing decision and drop the packet:
-
-----
-table=$POLICY_ENFORCER reg1=$SEPG, reg3=$DEPG,
-actions=clear_actions, drop
-----
-
-[red]*Log*
-
-The logging action is an extension to the drop action. It will send packet to the controller for logging
-purposes. The controller will then drop the packet.
-
-----
-table=$POLICY_ENFORCER reg1=$SEPG, reg3=$DEPG,
-actions=clear_actions, controller:[...]
-----
-
-[red]*Set QoS*
-
-The *Set QoS* action allows to modify the QoS mark of a packet. This includes the DiffServ field as well as ECN information. Note that this action may only be applied to IP packets.
-
-This action is typically followed by an allow or redirect action.
-
-----
-table=$POLICY_ENFORCER reg1=$SEPG, reg3=$DEPG,
-actions=mod_nw_tos:TOS, mod_nw_ecn:ECN, ...
-----
-
-[red]*Redirect / Service Redirection*
-
-Service insertion or redirection can be defined as an action between EPGs in the policy. It may occur transparently, i.e. without changing the packet in any way, or non-transparently by explicitly redirecting the packet to the service node.
-
-*Non-transparent Service Insertion*
-
-Non-transparent service insertion is used to redirect packets to a service such as a web proxy which requires the packet to be addressed to the service. The vSwitch forwarding behavior to achieve this is identical to a L2/L3 switching/routing action to any other EP.
-
-The specific action chain will depend on whether the service is located within the same BD or whether routing is required. The controller/agent is aware of the location of both EPs and will insert the required action set. The following is an example for a L2 non-transparent service redirection:
-
-----
-table=$POLICY_ENFORCER reg1=$SEPG, reg3=$DEPG,
-actions=mod_dl_dst:$MAC_OF_SERVICE,
- load:$TUNNEL_PORT->NXM_NX_REG4[],
- move:NXM_NX_REG1[]->NXM_NX_TUN_ID[],
- load:$TUNNEL_DST->NXM_NX_TUN_IPV4_DST[],
- action:output:NXM_NX_REG4[]
-----
-
-*Transparent Service Insertion*
-
-Transparent service insertion is used to redirect packets to a service such as a firewall which does not require a packet to be specifically addressed to the service. The service will be applied to all packets on the virtual network. This requires that the service only sees packets to which the service should be applied.
-
-The required forwarding behavior is to encapsulate the packet with the appropriate VNID. There is no need to rewrite any of the L2 headers.
-
-----
-table=$POLICY_ENFORCER reg1=$SEPG, reg3=$DEPG,
-actions=load:$TUNNEL_PORT->NXM_NX_REG4[],
- move:$VNI_OF_SERVICE->NXM_NX_TUN_ID[],
- load:$TUNNEL_DST->NXM_NX_TUN_IPV4_DST[],
- output:$NXM_NX_REG4[]
-----
-
-The redirect action in the policy will specify the VNID and VTEP to be used.
-
-TBD: Does the pipeline always stop after a redirect action has been processed?
-
-[red]*Mirror*
-
-This action causes the packet to be cloned and forwarded to an additional port (port mirroring).
-
-[[openflow_renderer]]
-===== OpenFlow/OVS Renderer
-
-The OpenFlow renderer is based on the <<ovs_overlay,OVS Overlay>> design and implements a network virtualization solution for virtualized compute environments using Open vSwitch, OpenFlow and OVSDB remotely from the controller.
-
-The OpenFlow renderer architecture consists of the following:
-
-Switch Manager::
-Manage connected switch configuration using OVSDB. Maintain overlay tunnels.
-Endpoint Manager::
-Optionally learn endpoints based on simple rules that map interfaces to endpoint groups. Can add additional rules in the future. Keep endpoint registry up to date. If disabled, then an orchestration system must program all endpoints and endpoint mappings.
-ARP and DHCP Manager::
-Convert ARP and DHCP into unicast.
-Policy Manager::
-Subscribe to renderer common infrastructure, and switch and endpoint manager. Manage the state of the flow tables in OVS.
-
-[[opflex_renderer]]
-===== OpFlex Renderer
-
-The OpFlex renderer is based on the <<ovs_overlay,OVS Overlay>> design and implements a network virtualization solution for virtualized compute environments by communicating with the OpFlex Agent.
-
-The OpFlex renderer architecture consists of the following main pieces:
-
-Agent Manager::
-Manage connected agents using OpFlex.
-RPC Library::
-Manage serialization/deserialization of JSON RPC with Policy Elements.
-OpFlex Messaging::
-Provides definition of OpFlex messages and serialization/deserialization into Managed Objects.
-Endpoint manager::
-Optionally learn endpoints based on simple rules that map interfaces to endpoint groups. Can add additional rules in the future. Keep endpoint registry up to date. If disabled, then an orchestration system must program all endpoints and endpoint mappings.
-Policy manager::
-Subscribe to renderer common infrastructure and endpoint registry and provide normalized policy to agents.
-
+++ /dev/null
-== L2Switch
-The L2Switch project provides Layer2 switch functionality.
-
-=== 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
-
-=== Architecture of the L2Switch project
-* 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
-
-=== Developer's Guide for 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
-
-=== Developer's Guide for 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.
-
-=== Developer's Guide for 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.
-
-=== Developer's Guide for 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.
-
-=== Developer's Guide for 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.
-
+++ /dev/null
-== Lisp Flow Mapping
-
-// This chapter contains:
-
-//* <<OpenDaylight Locator/ID Separation Protocol (LISP) Flow Mapping Overview>>
-//* <<Installing LISP Flow Mapping>>
-
-=== OpenDaylight Locator/ID Separation Protocol (LISP) Flow Mapping Overview
-
-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 and 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 via the LISP control protocol (Map-Register, Map-Request, Map-Reply messages).
-
-The following figure depicts the described components:
-
-.Architecture Overview
-
-image::lispflow-arch-overview-helium.jpg["Architecture Overview", width=512]
-
-
-=== LISP Service Architecture
-
-The following figure shows the various LISP Flow Mapping modules.
-
-.LISP Mapping Service Internal Architecture
-
-image::lispflow-technical-arch-overview-helium.jpg["LISP Mapping Service Internal Architecture", width=460]
-
-A brief description of each module is as follows:
-
-* *DAO:* 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 DHT (Distributed Hash Table). Currently we have an implementation of this layer with the controller cluster service as a DHT, but it can be switched to any other DHT and you only need to implement the ILISPDAO interface.
-* *Map Server:* This module processes the adding or registration of 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].
-* *Northbound API:* This is part of the ODL northbound API. This module enables defining key-EID associations as well as adding mapping information through the Map Server. Key-EID associations can also be queried via this API. The Northbound API also provides capability of querying the mapping information for an EID prefix.
-* *Neutron:* This module implements the ODL Neutron Service APIs. It provides integration between the LISP service and the ODL Neutron service.
-* *NETCONF:* This module enables the LISP service to communicate to NETCONF-enabled devices through ODL's NETCONF plugin.
-* *Java API:* The API module exposes the Map Server and Map Resolver capabilities via Java API.
-* *LISP Southbound Plugin:* This plugin enables data plane devices that support LISP control plane protocol (see LISP) to register and query mappings to the LISP Flow Mapping via the LISP control plane protocol.
-
-=== LISP APIs
-
-The LISP Flow Mapping service has JAVA APIs and REST APIs. The Java API reference documentation is auto-generated from the Java build and is available at:
-
-* https://jenkins.opendaylight.org/lispflowmapping/job/lispflowmapping-merge-develop/247/artifact/target/apidocs/index.html[JAVA APIs]
-
-Below you will find the detailed information about the module's REST resources and their verbs (description, URI, parameters, responses, and status codes), schemas, example XML, example JSON, as well as programming examples.
-
-* https://jenkins.opendaylight.org/lispflowmapping/job/lispflowmapping-merge-develop/247/artifact/mappingservice/northbound/target/site/wsdocs/index.html[REST APIS]
-
-//TODO Need to update the links once the stable/helium branch is cut and the corresponding Jenkins merge job is created. For now, instead of 'lastSuccessfulBuild' let's use the merge job corresponding to the commit that's supposed to be released as Helium
-
-=== LISP Configuration Options
-
-The +etc/custom.properties+ file in the Karaf distribution allows configuration of several OpenDaylight parameters. The LISP service has two properties that can be adjusted: +lisp.mappingOverwrite+ and +lisp.smr+.
-
-*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.
-
-=== Developer Tutorial
-
-This section provides instructions to set up a LISP network of three nodes (one "client" node and two "server" nodes) using LISPmob and Open vSwitch (OVS) as data plane LISP nodes and the LISP Flow Mapping project from ODL as the LISP programmable mapping system for the LISP network. The steps shown below will demonstrate performing a failover between the two "server" nodes. The three LISP data plane nodes and the LISP mapping system are assumed to be running in Linux virtual machines using the following IPv4 addresses on their eth0 interfaces (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 | 10.33.12.32
-| *client* | LISPmob | 10.33.12.35
-| *server1* | LISPmob | 10.33.12.37
-| *server2* | Open vSwitch | 10.33.12.44
-|===
-
-NOTE: While the tutorial uses LISPmob and OVS as the data plane, they could be any LISP-enabled HW or SW router (commercial/open source).
-
-The below steps are using the command line tool cURL to talk to the LISP Flow Mapping northbound REST API. This is so that you can see the actual request URLs and body content on the page.
-
-NOTE: It is more convenient to use the Postman Chrome browser plugin 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/ODL_Summit_LISP_Demo.json+ file. You can import this file to Postman by following 'Collections->Import a collection->Import from URL' and then entering the following link: +https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/ODL_Summit_LISP_Demo.json;hb=refs/heads/develop+. 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 define some variables to point to your OpenDaylight controller instance.
-
-NOTE: It is assumed that commands are executed as the 'root' user.
-
-NOTE: To set up a basic LISP network overlay (no fail-over) without dealing with OVS, you can skip steps 7 and 8 and just use LISPmob as your dataplane. If you do want to test fail-over, but not using OVS, skip steps 7 and 8, but set up LISPmob on *server2* as well, with identical configuration.
-
-. Install and run OpenDaylight Helium release on the controller VM. Please follow the general OpenDaylight Helium Installation Guide for this step. Once the OpenDaylight controller is running install the 'odl-openflowplugin-all', 'odl-adsal-compatibility-all', 'odl-ovsdb-all', and 'odl-lispflowmapping-all' features from the CLI:
-
- feature:install odl-openflowplugin-all odl-adsal-compatibility-all odl-ovsdb-all odl-lispflowmapping-all
-+
-NOTE: If you're not planning on using OVS you can skip the first three and install 'odl-lispflowmapping-all' only.
-+
-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 is the log output winding down, and continue after that.
-
-. Install LISPmob on the *client* and *server1* 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* to 2.2.2.2/32. Set the RLOC interface in each +lispd.conf+. 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* 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, 'asdf' in this tutorial. The +resources/tutorial+ directory in the 'develop' 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=blob_plain;f=resources/tutorial/lispd.conf.client;hb=refs/heads/develop[lispd.conf.client] and https://git.opendaylight.org/gerrit/gitweb?p=lispflowmapping.git;a=blob_plain;f=resources/tutorial/lispd.conf.server1;hb=refs/heads/develop[lispd.conf.server1]. Copy the files to +/root/lispd.conf+ on the respective VMs.
-
-. Define a key and EID prefix association in ODL using the northbound API for both EIDs (1.1.1.1/32 and 2.2.2.2/32). Run the below commands 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 PUT \
- http://localhost:8080/lispflowmapping/nb/v2/default/key \
- --data @key1.json
- curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
- http://localhost:8080/lispflowmapping/nb/v2/default/key \
- --data @key2.json
-
-+
-where the content of the 'key1.json' and 'key2.json' files is the following (with different "ipAddress"):
-+
-[source,json]
-----
-{
- "key" : "asdf",
- "maskLength" : 32,
- "address" :
- {
- "ipAddress" : "1.1.1.1",
- "afi" : 1
- }
-}
-----
-
-. Verify that the key is added properly by requesting the following URL:
-
- curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/key/0/1/1.1.1.1/32
- curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/key/0/1/2.2.2.2/32
-
-. Run the lispd LISPmob daemon on the *client* and *server1* VMs:
-
- lispd -f /root/lispd.conf
-
-. Prepare the OVS environment on *server2*:
-
- .. Start the ovsdb-server and ovs-vswitchd daemons (or check that your distribution's init scripts already started them)
- .. Start listening for OVSDB manager connections on the standard 6640 TCP port:
-
- ovs-vsctl set-manager "ptcp:6640"
- ovs-vsctl show
-
-+
- .. Create a TAP port for communications with the guest VM. We'll have another VM inside the *server2* VM, that will be set up with the 2.2.2.2/24 EID. It also needs a ficticious gateway, and a static ARP entry for that gateway, with any MAC address.
-
- tunctl -t tap0
- ifconfig tap0 up
-
-+
- .. Start the guest VM:
-
- modprobe kvm
- kvm -daemonize -vnc :0 -m 128 -net nic,macaddr=00:00:0C:15:C0:A1 \
- -net tap,ifname=tap0,script=no,downscript=no \
- -drive file=ubuntu.12-04.x86-64.20120425.static_ip_2.2.2.2.qcow2
-
-+
-. Set up the OVS environment on *server2* using the ODL northbound API
- .. Connect to the OVSDB management port from ODL:
-
- curl -u "admin":"admin" -X PUT \
- http://localhost:8080/controller/nb/v2/connectionmanager/node/server2/address/10.33.12.44/port/6640
-
-+
-You can check if this and the next requests have the desired effect on OVS by running the following on *server2*
-
- ovs-vsctl show
-
-+
-It should now show the "Manager" connection as connected
-
- .. Create the bridge +br0+:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8080/controller/nb/v2/networkconfig/bridgedomain/bridge/OVS/server2/br0 -d "{}"
-
- .. Add +tap0+ to +br0+:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8080/controller/nb/v2/networkconfig/bridgedomain/port/OVS/server2/br0/tap0 -d "{}"
-
-+
- .. Add the +lisp0+ LISP tunneling virtual port to +br0+:
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X POST \
- http://localhost:8080/controller/nb/v2/networkconfig/bridgedomain/port/OVS/server2/br0/lisp0 -d @lisp0.json
-+
-where 'lisp0.json' has the following content:
-+
-[source,json]
-----
-{
- "type": "tunnel",
- "tunnel_type": "lisp",
- "dest_ip": "10.33.12.35"
-}
-----
-The *dest_ip* parameter sets the tunnel destination to the *client* VM. This has to be done manually (from the controller), since OVS doesn't have a LISP control plane to fetch mappings.
-
- .. We will now need to set up flows on +br0+ to to steer traffic received on the LISP virtual port in OVS to the VM connected to +tap0+ and vice-versa. For that we will need the node id of the bridge, which is based on its MAC address, which is generated at creation time. So we look at the list of connections on the controller:
-
- curl -u "admin":"admin" http://localhost:8080/controller/nb/v2/connectionmanager/nodes
-+
-The response should look similar to this:
-+
-[literal]
-{"id":"00:00:62:71:36:30:7b:44","type":"OF"}]},{"id":"10.33.12.35","type":"LISP"},{"id":"server2","type":"OVS"}]}
-+
-There are three types of nodes connected to ODL: one "OF" node (the OpenFlow connection to +br0+ on *server2*), one "LISP" node (the *client* VM sending LISP Map-Register control messages to the controller which is acting as a LISP Map-Server), and one "OVS" node (this is the OVSDB connection to *server2*). We will need the id of the "OF" node in order to set up flows.
-
- .. The first flow will decapsulate traffic received from the client VM on *server2* and send it to the guest VM through the +tap0+ port.
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
- http://localhost:8080/controller/nb/v2/flowprogrammer/default/node/OF/00:00:62:71:36:30:7b:44/staticFlow/Decap -d @flow_decap.json
-+
-Make sure that the bridge id after the OF path component of the URL is the id from the previous step. It should also be the same on line 6 in 'flow_decap.json' file (see below), which should have the MAC address of the KVM instance started on *server2* on line 11 (+SET_DL_DST+):
-+
-[source,json]
-----
-{
- "installInHw": "true",
- "name": "Decap",
- "node": {
- "type": "OF",
- "id": "00:00:62:71:36:30:7b:44"
- },
- "priority": "10",
- "dlDst": "02:00:00:00:00:00",
- "actions": [
- "SET_DL_DST=00:00:0c:15:c0:a1",
- "OUTPUT=1"
- ]
-}
-----
-
- .. The second flow will encapsulate traffic received from the guest VM on *server2* through the +tap0+ port.
-
- curl -u "admin":"admin" -H "Content-type: application/json" -X PUT \
- http://localhost:8080/controller/nb/v2/flowprogrammer/default/node/OF/00:00:62:71:36:30:7b:44/staticFlow/Encap -d @flow_encap.json
-+
-The 'flow_encap.json' file should look like this:
-+
-[source,json]
-----
-{
- "installInHw": "true",
- "name": "Decap",
- "node": {
- "type": "OF",
- "id": "00:00:62:71:36:30:7b:44"
- },
- "priority": "5",
- "ingressPort": "1",
- "etherType": "0x0800",
- "vlanId": "0",
- "nwDst": "1.1.1.1/32",
- "actions": [
- "OUTPUT=2"
- ]
-}
-----
-
- .. Check if the flows have been created correctly. First, in ODL
-
- curl -u "admin":"admin" http://localhost:8080/controller/nb/v2/flowprogrammer/default
-+
-And most importantly, on *server2*
-
- ovs-ofctl dump-flows br0 -O OpenFlow13
-
-. The *client* LISPmob node should now register its EID-to-RLOC mapping in ODL. To verify you can lookup the corresponding EIDs via the northbound API
-
- curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/mapping/0/1/1.1.1.1/32
-
- . 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 PUT \
- http://localhost:8080/lispflowmapping/nb/v2/default/mapping \
- -d @mapping.json
-+
-where the 'mapping.json' file looks like this
-+
-[source,json]
-----
-{
-"key" : "asdf",
-"mapregister" :
- {
- "proxyMapReply" : true,
- "eidToLocatorRecords" :
- [
- {
- "authoritative" : true,
- "prefixGeneric" :
- {
- "ipAddress" : "2.2.2.2",
- "afi" : 1
- },
- "mapVersion" : 0,
- "maskLength" : 32,
- "action" : "NoAction",
- "locators" :
- [
- {
- "multicastPriority" : 1,
- "locatorGeneric" :
- {
- "ipAddress" : "10.33.12.37",
- "afi" : 1
- },
- "routed" : true,
- "multicastWeight" : 0,
- "rlocProbed" : false,
- "localLocator" : false,
- "priority" : 126,
- "weight" : 1
- } ,
- {
- "multicastPriority" : 1,
- "locatorGeneric" :
- {
- "ipAddress" : "10.33.12.44",
- "afi" : 1
- },
- "routed" : true,
- "multicastWeight" : 0,
- "rlocProbed" : false,
- "localLocator" : false,
- "priority" : 127,
- "weight" : 1
- }
- ],
- "recordTtl" : 5
- }
- ],
- "keyId" : 0
- }
-}
-----
-+
-Here the priority of the second RLOC (10.33.12.44 - *server2*) is 127, a higher numeric value than the priority of 10.33.12.37, which is 126. This policy is saying that *server1* is preferred to *server2* for reaching EID 2.2.2.2/32. Note that lower priority has higher preference in LISP.
-
- . Verify the correct registration of the 2.2.2.2/32 EID:
-
- curl -u "admin":"admin" http://localhost:8080/lispflowmapping/nb/v2/default/mapping/0/1/2.2.2.2/32
-
- . 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 and repeat the request from step 10. You can also repeat step 11 to see if the mapping is correctly registered. Not that the previous locators are still present, so you should see a list of four locators. If you leave the ping on, and monitor the traffic using wireshark you can see that the ping traffic will be diverted from *server1* to *server2*.
-+
-With the default ODL configuration this may take some time, because the mapping stays in the *client* map-cache until the TTL expires. LISP has a 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. This is disabled by default, and is controlled by the +lisp.smr+ variable in +etc/custom.porperties+. When enabled, any mapping change from the northbound will trigger an SMR packet to all data plane elements that have requested the mapping in a certain time window.
-
-If you used the Postman collection, you will notice an "ELP" mapping. This is for supporting service chaining, but it requires a Re-encapsulating Tunnel Router (RTR). Support for RTR functionality in LISPmob is in progress, and we will update the tutorial to demonstrate service chaining when it becomes available.
-
-=== LISP Support
-
-For support please contact the lispflowmapping project at:
-
-* Lisp Flow Mapping users mailing list: lispflowmapping-users@lists.opendaylight.org
-
-* Lisp Flow Mapping dev mailing list: lispflowmapping-dev@lists.opendaylight.org
-
-You can also reach us at the following channel on IRC:
-
-* #opendaylight-lispflowmapping on irc.freenode.net
-
-Additional information is also available on the wiki:
-
-* https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Main[Lisp Flow Mapping wiki]
-
-=== Installing LISP Flow Mapping
-
-This chapter contains installation instructions for Locator ID Separation Protocol (LISP) provides guidelines for installation from the lispflowmapping repository.
-
-==== Setting up Gerritt
-
-Code reviews are enabled through Gerrit. For setting up gerritt, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Gerrit_Setup[Set up Gerrit].
->>>>>>> a8dd6f1... added installation section into the lisp doc
-
-NOTE: You will need to perform the Gerrit Setup before you can access git via ssh as described below.
-
-==== Pulling code via Git CLI
-
-Pull the code by cloning the LispFlowMapping repository.
-
-----
- git clone ssh://<username>@git.opendaylight.org:29418/lispflowmapping.git
-----
-
-or if you just want to do an anonymous git clone, you can use:
-
-----
- git clone https://git.opendaylight.org/gerrit/p/lispflowmapping.git
-----
-
-==== Setting up Gerrit Change-id Commit Message Hook
-
-This command inserts a unique Change-Id tag in the footer of a commit message. This step is optional but highly recommended for tracking changes.
-
-----
- cd lispflowmapping
- scp -p -P 29418 <username>@git.opendaylight.org:hooks/commit-msg .git/hooks/
- chmod 755 .git/hooks/commit-msg
-----
-
-Install and setup gitreview. The instaructions can be found at http://www.mediawiki.org/wiki/Gerrit/git-review#Installation%7Chere[here].
-
-==== Hacking the Code
-
-The following tasks are used to help you hack the code.
-
-*Setup Eclipse*
-
-. Run Eclipse (Kepler is the current version).
-. Open Git Repository perspective.
-. Add an existing repository and choose the Lisp Flow Mapping repository that was pulled earlier.
-. Import existing Maven projects and choose the following under the lispflowmapping directory:
-
- * api/pom.xl
- * implementation/pom.xml
-
-*Build the code*
-
-----
- mvn clean install
-----
-
-To run without unitests you can skip building those tests running the following:
-
-----
- mvn clean install -DskipTests
- /* instead of "mvn clean install" */
-----
-
-*Run the controller*
-
-----
- cd distribution-karaf/target/assembly/bin
- ./karaf
-----
-
-At this point the ODL controller is running. Open a web browser and point your browser at http://localhost:8080/
-
-For complete documentation on running the controller, see the ODL Helium Installation Guide.
-
-==== Commit the code using Git CLI
-
-NOTE: To be accepted, all code must come with a http://elinux.org/Developer_Certificate_Of_Origin[developer certificate of origin] as expressed by having a Signed-off-by. This means that you are asserting that you have made the change and you understand that the work was done as part of an open-source license.
-
-----
-Developer's Certificate of Origin 1.1
-
- By making a contribution to this project, I certify that:
-
- (a) The contribution was created in whole or in part by me and I
- have the right to submit it under the open source license
- indicated in the file; or
-
- (b) The contribution is based upon previous work that, to the best
- of my knowledge, is covered under an appropriate open source
- license and I have the right under that license to submit that
- work with modifications, whether created in whole or in part
- by me, under the same open source license (unless I am
- permitted to submit under a different license), as indicated
- in the file; or
-
- (c) The contribution was provided directly to me by some other
- person who certified (a), (b) or (c) and I have not modified
- it.
-
- (d) I understand and agree that this project and the contribution
- are public and that a record of the contribution (including all
- personal information I submit with it, including my sign-off) is
- maintained indefinitely and may be redistributed consistent with
- this project or the open source license(s) involved.
-----
-
-*Mechanically you do it this way*:
-
-----
-git commit --signoff
-----
-
-You will be prompted for a commit message. If you are fixing a buzilla bug you can add the associated bug number to your commit message and it will get linked from Gerrit:
-
-.For Example:
-
-----
-Fix for bug 2.
-
-Signed-off-by: Ed Warnicke <eaw@cisco.com>
-# Please enter the commit message for your changes. Lines starting
-# with '#' will be ignored, and an empty message aborts the commit.
-# On branch develop
-# Changes to be committed:
-# (use "git reset HEAD <file>..." to unstage)
-#
-# modified: README
-#
-----
-
-==== Pushing the Code via Git CLI
-
-Use gitreview to push your changes back to the remote repository using:
-
-----
- git review
-----
-
-You can set a topic for your patch by:
-
-----
- git review -t <topic>
-----
-
-The Jenkins Controller User will verify your code.
-
-==== Pulling the Code changes via Git CLI
-
-Use git pull to get the latest changes from the remote repository
-
-----
-git pull origin HEAD:refs/for/develop
-----
-
-==== Pushing the Code via Git CLI
-
-Use git push to push your changes back to the remote repository.
-
-----
-git push origin HEAD:refs/for/develop
-----
-
-You will get a message pointing you to your gerrit request like:
-
-----
-==========================
-remote: Resolving deltas: 100% (2/2) +
-remote: Processing changes: new: 1, refs: 1, done +
-remote: +
-remote: New Changes: +
-remote: http://git.opendaylight.org/gerrit/64 +
-remote: +
-==========================
-----
-
-==== Viewing your Changes in Gerrit
-
-Follow the link you got above to see your commit in Gerrit:
-
-.Gerritt Code Review Sample
-image::gerrit-code-review.png["Gerritt Code Review Sample",width=500]
-
-Note that the Jenkins Controller User has verified your code and at the bottom is a link to the Jenkins build.
-
-Once your code has been reviewed and submitted by a committer it will be merged into the authoritative repo, which would look like this:
-
-.Gerritt Code Merge Sample
-image::gerrit-merged.png["Gerritt Code Merge Sample",width=500]
-
-==== Troubleshooting
-
-. *What to do if your Firewall blocks port 29418*
-
-There have been reports that many corporate firewalls block port 29418. If that's the case, please follow the https://wiki.opendaylight.org/view/OpenDaylight_Controller:Setting_up_HTTP_in_Gerrit[Setting up HTTP in Gerrit] instructions and use git URL:
-
-----
-git clone https://<your_username>@git.opendaylight.org/gerrit/p/lispflowmapping.git
-----
-
-You will be prompted for the password you generated in https://wiki.opendaylight.org/view/OpenDaylight_Controller:Setting_up_HTTP_in_Gerrit[Setting up HTTP in Gerrit].
-
-All other instructions on this page remain unchanged.
-
-To download pre-built images with ODP bootstraps see the following Github project:
-
-https://github.com/nerdalert/OpenDaylight-Lab[Pre-Built OpenDaylight VM Images]
-
-
+++ /dev/null
-== Welcome to the OpenDaylight project\r
-\r
-\r
-The Open Daylight Project is a collaborative open source project under the Linux foundation that aims to accelerate adoption of Software-Defined Networking (SDN) and create a solid foundation for Network Functions Virtualization (NFV) for a more transparent approach that fosters new innovation and reduces risk. Founded by industry leaders and open to all, the OpenDaylight community is developing a common, open SDN framework consisting of code and blueprints.\r
-\r
-\r
-=== OpenDaylight project scope\r
-\r
-The projects chosen by the Technical Steering Committee (TSC) are limited to the following areas:\r
-\r
-* The OpenDaylight controller\r
-\r
-* Software for forwarding elements\r
-\r
-* Southbound plugins to enable the controller to speak to the OpenDaylight supplied and other network elements\r
-\r
-* Northbound plugins to expose interfaces to those writing applications to the controller\r
-\r
-* Network services and applications intended to run on top of the controller, integration between the controller and other elements\r
-\r
-* Support projects such as tools, infrastructure, or testing\r
-\r
-* Plugins for inter-controller communication\r
-\r
-\r
-=== OpenDaylight project goals\r
-\r
-* *Code*: To create a robust, extensible, open source code base that covers the major common components required to build an SDN solution.\r
-\r
-* *Acceptance*: To get broad industry acceptance amongst vendors and users.\r
-\r
-* *Community*: To have a thriving and growing technical community contributing to the code base, using the code in commercial products, and adding value above, below and around. \r
-\r
-=== Additional information for the OpenDaylight project\r
-\r
-* For frequently asked questions about the OpenDaylight project, see the http://www.opendaylight.org/project/faq[FAQ].\r
-\r
-\r
-* You can join OpenDaylight as a user, developer, or as a member of the project. See the http://www.opendaylight.org/resources/getting-started-guide[ Getting Started with OpenDaylight].\r
-\r
-\r
-* Exhaustive information about OpenDaylight is available in the https://wiki.opendaylight.org/view/Main_Page[OpenDaylight Wiki].\r
-\r
-\r
-\r
-\r
+++ /dev/null
-== ODL-SDNi
-
-Content on using ODL SDNi can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/ODL-SDNiApp:Developer_Guide
-
+++ /dev/null
-== OpenFlow Plugin
-
-.OpenFlow plugin: Component map
-[options="header"]
-|===
-| Artifact ID | Component | Description
-| openflowplugin | openflowplugin | Main implementation of OFPlugin
-| openflowplugin-it test-provider drop-test test-scripts | test | Support for end-to-end, integration, and regression testing
-| openflowplugin-controller-config | configSubsystem | Default configuration files for config subsystem
-| distributions-openflowplugin-base | distribution | OFPlugin distribution, based on the distribution of the controller,
-but the old (OF-1.0 only) plugin is replaced with the new plugin(OF-1.0+1.3)
-| learning-switch sample-consumer | sample | Sample projects demonstrating MD-SAL usage
-| vagrant | util | Materialize testing virtual machine containing mininet+ovs
-|===
-
-=== OpenFlow Plugin: Sequence diagrams
-
-.Message Lifecycle
-image::MessageLifecycle.jpg[width=500]
-
-.Handshake Scenario
-image::Handshake.png[width=500]
-
-.Connection Sequence (Handshake) Flow Diagram
-image::OF1_0_Switch_Handshake_Sequence.png[width=500]
-
-.Message Order Preservation
-image::MessageOrderPreservation.jpg[width=500]
-
-.Add Flow Sequence
-image::Add_flow.png[width=500]
-
-.Generic Notification Sequence
-image::Generic_notification.png[width=500]
-
-=== OpenFlow Plugin:Config subsystem
-==== Model provided modules by yang
-*General model (interfaces)* - openflow-plugin-cfg.yang. +
-
-* The provided module is defined (identity openflow-provider)
-
-* The target implementation is assigned (...OpenflowPluginProvider)
-----
-module openflow-provider {
- yang-version 1;
- namespace "urn:opendaylight:params:xml:ns:yang:openflow:common:config";
- prefix "ofplugin-cfg";
-
- import config {prefix config; revision-date 2013-04-05; }
- description
- "openflow-plugin-custom-config";
- revision "2014-03-26" {
- description
- "Initial revision";
- }
- identity openflow-provider{
- base config:service-type;
- config:java-class "org.opendaylight.openflowplugin.openflow.md.core.sal.OpenflowPluginProvider";
- }
-}
-----
-*Implementation model* - openflow-plugin-cfg-impl.yang +
-
-* The implementation of module is defined (+identity openflow-provider-impl+).
-
-** The class name of the generated implementation is defined (ConfigurableOpenFlowProvider).
-
-* The configuration of the module is defined through augmentation:
-** This module requires an instance of a binding-aware-broker (container binding-aware-broker).
-** Also required is a list of openflow-switch-connection-providers. (Those are provided by openflowjava: one plugin instance will orchester multiple openflowjava modules.)
-----
-module openflow-provider-impl {
- yang-version 1;
- namespace "urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl";
- prefix "ofplugin-cfg-impl";
-
- import config {prefix config; revision-date 2013-04-05;}
- import openflow-provider {prefix openflow-provider;}
- import openflow-switch-connection-provider {prefix openflow-switch-connection-provider;revision-date 2014-03-28;}
- import opendaylight-md-sal-binding { prefix md-sal-binding; revision-date 2013-10-28;}
-
-
- description
- "openflow-plugin-custom-config-impl";
-
- revision "2014-03-26" {
- description
- "Initial revision";
- }
-
- identity openflow-provider-impl {
- base config:module-type;
- config:provided-service openflow-provider:openflow-provider;
- config:java-name-prefix ConfigurableOpenFlowProvider;
- }
-
- augment "/config:modules/config:module/config:configuration" {
- case openflow-provider-impl {
- when "/config:modules/config:module/config:type = 'openflow-provider-impl'";
-
- container binding-aware-broker {
- uses config:service-ref {
- refine type {
- mandatory true;
- config:required-identity md-sal-binding:binding-broker-osgi-registry;
- }
- }
- }
- list openflow-switch-connection-provider {
- uses config:service-ref {
- refine type {
- mandatory true;
- config:required-identity openflow-switch-connection-provider:openflow-switch-connection-provider;
- }
- }
- }
- }
- }
-}
-----
-==== Generating config and sal classes from yangs
-NOTE: Suitable code generators, needed in pom, are involved.
-
-----
-<build> ...
- <plugins>
- <plugin>
- <groupId>org.opendaylight.yangtools</groupId>
- <artifactId>yang-maven-plugin</artifactId>
- <executions>
- <execution>
- <goals>
- <goal>generate-sources</goal>
- </goals>
- <configuration>
- <codeGenerators>
- <generator>
- <codeGeneratorClass>
- org.opendaylight.controller.config.yangjmxgenerator.plugin.JMXGenerator
- </codeGeneratorClass>
- <outputBaseDir>${project.build.directory}/generated-sources/config</outputBaseDir>
- <additionalConfiguration>
- <namespaceToPackage1>
- urn:opendaylight:params:xml:ns:yang:controller==org.opendaylight.controller.config.yang
- </namespaceToPackage1>
- </additionalConfiguration>
- </generator>
- <generator>
- <codeGeneratorClass>
- org.opendaylight.yangtools.maven.sal.api.gen.plugin.CodeGeneratorImpl
- </codeGeneratorClass>
- <outputBaseDir>${project.build.directory}/generated-sources/sal</outputBaseDir>
- </generator>
- <generator>
- <codeGeneratorClass>org.opendaylight.yangtools.yang.unified.doc.generator.maven.DocumentationGeneratorImpl</codeGeneratorClass>
- <outputBaseDir>${project.build.directory}/site/models</outputBaseDir>
- </generator>
- </codeGenerators>
- <inspectDependencies>true</inspectDependencies>
- </configuration>
- </execution>
- </executions>
- <dependencies>
- <dependency>
- <groupId>org.opendaylight.controller</groupId>
- <artifactId>yang-jmx-generator-plugin</artifactId>
- <version>0.2.5-SNAPSHOT</version>
- </dependency>
- <dependency>
- <groupId>org.opendaylight.yangtools</groupId>
- <artifactId>maven-sal-api-gen-plugin</artifactId>
- <version>${yangtools.version}</version>
- <type>jar</type>
- </dependency>
- </dependencies>
- </plugin>
- ...
-----
-* JMX generator (target/generated-sources/config)
-
-* sal CodeGeneratorImpl (target/generated-sources/sal)
-
-* Documentation generator (target/site/models): https://jenkins.opendaylight.org/openflowplugin/job/openflowplugin-merge/ws/openflowplugin/target/site/models/openflow-provider.html[openflow generator]and https://jenkins.opendaylight.org/openflowplugin/job/openflowplugin-merge/ws/openflowplugin/target/site/models/openflow-provider-impl.html[openflow provider impl].
-
-==== Altering generated files
-Those files were generated under src/main/java in the package as referred in yangs (if they exist, the generator will not overwrite them): +
-
-* ConfigurableOpenFlowProviderModuleFactory
-
-The *instantiateModule* methods are extended in order to capture and inject the osgi BundleContext into module, so it can be injected into final implementation: *OpenflowPluginProvider* +module.setBundleContext(bundleContext);+ +
-
-* ConfigurableOpenFlowProviderModule
-
-The *createInstance* method is extended in order to inject osgi BundleContext into the module implementation: +pluginProvider.setContext(bundleContext);+
-
-==== Configuration xml file
-
-The configuration file contains: +
-
-* Required capabilities
-
-** Modules definitions from openflowjava
-
-** Definitions from openflowplugin
-
-* Modules definition
-
-** openflow:switch:connection:provider:impl (listening on port 6633, name=openflow-switch-connection-provider-legacy-impl)
-** openflow:switch:connection:provider:impl (listening on port 6653, name=openflow-switch-connection-provider-default-impl)
-** openflow:common:config:impl (having 2 services (wrapping those 2 previous modules) and binding-broker-osgi-registry injected)
-* Provided services
-** openflow-switch-connection-provider-default
-** openflow-switch-connection-provider-legacy
-** openflow-provider
-----
-<snapshot>
- <required-capabilities>
- <capability>urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider:impl?module=openflow-switch-connection-provider-impl&revision=2014-03-28</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider?module=openflow-switch-connection-provider&revision=2014-03-28</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:openflow:common:config:impl?module=openflow-provider-impl&revision=2014-03-26</capability>
- <capability>urn:opendaylight:params:xml:ns:yang:openflow:common:config?module=openflow-provider&revision=2014-03-26</capability>
- </required-capabilities>
-
- <configuration>
-
-
- <modules xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <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>
- <switch-idle-timeout>15000</switch-idle-timeout>
- </module>
- <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>
- <switch-idle-timeout>15000</switch-idle-timeout>
- </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>
-
- <services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:switch:connection:provider">
- prefix:openflow-switch-connection-provider
- </type>
- <instance>
- <name>openflow-switch-connection-provider-default</name>
- <provider>/modules/module[type='openflow-switch-connection-provider-impl'][name='openflow-switch-connection-provider-default-impl']</provider>
- </instance>
- <instance>
- <name>openflow-switch-connection-provider-legacy</name>
- <provider>/modules/module[type='openflow-switch-connection-provider-impl'][name='openflow-switch-connection-provider-legacy-impl']</provider>
- </instance>
- </service>
-
- <service>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:openflow:common:config">prefix:openflow-provider</type>
- <instance>
- <name>openflow-provider</name>
- <provider>/modules/module[type='openflow-provider-impl'][name='openflow-provider-impl']</provider>
- </instance>
- </service>
- </services>
-
-
- </configuration>
-</snapshot>
-----
-==== API changes
-In order to provide multiple instances of modules from openflowjava, there is an API change. Previously, the OFPlugin got access to the SwitchConnectionProvider exposed by OFJava, and injected the collection of configurations so that for every configuration, a new instance of the TCP listening server was created. Now, those configurations are provided by the configSubsystem, and the configured modules (wrapping the original SwitchConnectionProvider) are injected into the OFPlugin (wrapping SwitchConnectionHandler).
-
-==== Providing config file (IT, local distribution/base, integration/distributions/base)
-*openflowplugin-it*
-
-The whole configuration is contained in one file (controller.xml). The entries needed in order to start up and wire the OEPlugin + OFJava are simply added there.
-
-*OFPlugin/distribution/base* +
-
-The new config file is added (src/main/resources/configuration/initial/42-openflow-protocol-impl.xml), and copied to the config/initial subfolder of the build.
-
-*Integration/distributions/build* +
-
-In order to push the actual config into the config/initial subfolder of distributions/base in the integration project, a new artifact was created in OFPlugin. The openflowplugin-controller-config contains only the config xml file under src/main/resources. Another change was committed into the integration project. During a build, this config xml is extracted and copied to the final folder in order to be accessible during the controller run.
-
-=== Message Spy in OF Plugin
-
-With the intent to debug, the OpenFlow plugin implements a Message Spy to monitor controller communications.
-The Message Spy collects and displays message statistics.
-
-==== Message statistics collection +
-Message statistics are grouped according to message type and checkpoint. The counter assigned to a checkpoint and message class increases by 1 when a message passes through.
-
-The following checkpoints count passing messages: +
-----
-/**
- * statistic groups overall in OFPlugin
- */
- enum STATISTIC_GROUP {
- /** message from switch, enqueued for processing */
- FROM_SWITCH_ENQUEUED,
- /** message from switch translated successfully - source */
- FROM_SWITCH_TRANSLATE_IN_SUCCESS,
- /** message from switch translated successfully - target */
- FROM_SWITCH_TRANSLATE_OUT_SUCCESS,
- /** message from switch where translation failed - source */
- FROM_SWITCH_TRANSLATE_SRC_FAILURE,
- /** message from switch finally published into MD-SAL */
- FROM_SWITCH_PUBLISHED_SUCCESS,
- /** message from switch - publishing into MD-SAL failed */
- FROM_SWITCH_PUBLISHED_FAILURE,
-
- /** message from MD-SAL to switch via RPC enqueued */
- TO_SWITCH_ENQUEUED_SUCCESS,
- /** message from MD-SAL to switch via RPC NOT enqueued */
- TO_SWITCH_ENQUEUED_FAILED,
- /** message from MD-SAL to switch - sent to OFJava successfully */
- TO_SWITCH_SUBMITTED_SUCCESS,
- /** message from MD-SAL to switch - sent to OFJava but failed*/
- TO_SWITCH_SUBMITTED_FAILURE
- }
-----
-==== Message statistics display +
-Access the message statistics by means of logs, osgi, and jmx. +
-
-* osgi command (on demand): This method is considered deprecated. +
-: +osgi> dumpMsgCount+ +
-
-* From the controller console where statistics are refreshed every 10 seconds:
-+Required logback settings: <logger name="org.opendaylight.openflowplugin.openflow.md.queue.MessageSpyCounterImpl" level="DEBUG" />+
-
-* As JMX from the jconsole:
-** Start the OFplugin with the -jmx parameter.
-** Tab MBeans contains org.opendaylight.controller.
-** RuntimeBean has a msg-spy-service-impl.
-** Operations provides makeMsgStatistics report functionality.
-
-*Sample results* +
-----
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_ENQUEUED: MSG[PortStatusMessage] -> +0 | 1
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_ENQUEUED: MSG[MultipartReplyMessage] -> +24 | 81
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_ENQUEUED: MSG[PacketInMessage] -> +8 | 111
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_IN_SUCCESS: MSG[PortStatusMessage] -> +0 | 1
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_IN_SUCCESS: MSG[MultipartReplyMessage] -> +24 | 81
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_IN_SUCCESS: MSG[PacketInMessage] -> +8 | 111
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[QueueStatisticsUpdate] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[NodeUpdated] -> +0 | 3
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[NodeConnectorStatisticsUpdate] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[GroupDescStatsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[FlowsStatisticsUpdate] -> +3 | 19
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[PacketReceived] -> +8 | 111
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[MeterFeaturesUpdated] -> +0 | 3
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[GroupStatisticsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[GroupFeaturesUpdated] -> +0 | 3
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[MeterConfigStatsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[MeterStatisticsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[NodeConnectorUpdated] -> +0 | 12
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_OUT_SUCCESS: MSG[FlowTableStatisticsUpdate] -> +3 | 8
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_TRANSLATE_SRC_FAILURE: no activity detected
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[QueueStatisticsUpdate] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[NodeUpdated] -> +0 | 3
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[NodeConnectorStatisticsUpdate] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[GroupDescStatsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[FlowsStatisticsUpdate] -> +3 | 19
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[PacketReceived] -> +8 | 111
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[MeterFeaturesUpdated] -> +0 | 3
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[GroupStatisticsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[GroupFeaturesUpdated] -> +0 | 3
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[MeterConfigStatsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[MeterStatisticsUpdated] -> +3 | 7
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[NodeConnectorUpdated] -> +0 | 12
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_SUCCESS: MSG[FlowTableStatisticsUpdate] -> +3 | 8
-DEBUG o.o.o.s.MessageSpyCounterImpl - FROM_SWITCH_PUBLISHED_FAILURE: no activity detected
-DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_ENQUEUED_SUCCESS: MSG[AddFlowInput] -> +0 | 12
-DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_ENQUEUED_FAILED: no activity detected
-DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_SUBMITTED_SUCCESS: MSG[AddFlowInput] -> +0 | 12
-DEBUG o.o.o.s.MessageSpyCounterImpl - TO_SWITCH_SUBMITTED_FAILURE: no activity detected
-----
-
-=== OpenFlow Plugin:Mininet
-==== Mininet on debian wheezy(7), x86_64
-===== Requirements
-
-*Openvswitch* +
-
-. Install all requirements.
-----
-apt-get install build-essential fakeroot
-apt-get install debhelper autoconf automake libssl-dev pkg-config bzip2 openssl python-all procps python-qt4 python-zopeinterface python-twisted-conch
-----
-[start= 2]
-. Install a few helper applications.
-----
-apt-get -y install screen sudo vim etckeeper mlocate autoconf2.13 libssl-dev graphviz tcpdump gdebi-core
-----
-==== Test the Python environment
-*Python pip* +
-
-. Install setuptools.
-----
-wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
-sudo python ez_setup.py
-----
-[start= 2]
-. Install pip.
-----
-wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
-sudo python get-pip.py
-----
-[start= 3]
-. Post install the python libraries required by the ODL testing script.
-----
-sudo pip install netaddr
-----
-=== Installation
-==== Openvswitch 2.0.0
-. Remove the old packages, as root:
-----
-sudo -i
-apt-get remove openvswitch-common openvswitch-datapath-dkms openvswitch-controller openvswitch-pki openvswitch-switch
-----
-[start= 2]
-. Download and unpack OpenV Switch 2.0.0.
-----
-wget http://openvswitch.org/releases/openvswitch-2.0.0.tar.gz
-tar zxvf openvswitch-2.0.0.tar.gz
-----
-*Build and install* +
-
-. Install the openvswitch package. Deploy it using the module assistant at: https://wiki.debian.org/ModuleAssistant
-----
-cd ../
-gdebi openvswitch-datapath-source_2.0.0-1_all.deb
-module-assistant auto-install openvswitch-datapath
-gdebi openvswitch-common_2.0.0-1_amd64.deb
-gdebi openvswitch-switch_2.0.0-1_amd64.deb
-gdebi openvswitch-pki_2.0.0-1_all.deb
-gdebi openvswitch-controller_2.0.0-1_amd64.deb
-----
-*Post installation settings* +
-----
-service openvswitch-controller stop
-update-rc.d openvswitch-controller disable
-----
-*Test installation* +
-----
-ovs-vsctl show
-ovs-vsctl --version
-ovs-ofctl --version
-ovs-dpctl --version
-ovs-controller --version
-----
-==== Mininet 2.1.0
-
-. Download and checkout the required version.
-----
-git clone git://github.com/mininet/mininet
-cd mininet
-git checkout -b 2.1.0 2.1.0
-----
-[start=2]
-. Compile and install mininet.
-----
-gcc mnexec.c -o mnexec
-mv mnexec /usr/bin/
-python setup.py install
-----
-[start=3]
-. Test the installation.
-----
-mn --version
-mn --test pingall
-----
-*Expected result* +
-----
-root@debian:~/mininet# mn --version
-2.1.0
-root@debian:~/mininet# mn --test pingall
-*** Creating network
-*** Adding controller
-*** Adding hosts:
-h1 h2
-*** Adding switches:
-s1
-*** Adding links:
-(h1, s1) (h2, s1)
-*** Configuring hosts
-h1 h2
-*** Starting controller
-*** Starting 1 switches
-s1
-*** Ping: testing ping reachability
-h1 -> h2
-h2 -> h1
-*** Results: 0% dropped (2/2 received)
-*** Stopping 1 switches
-s1 ..
-*** Stopping 2 hosts
-h1 h2
-*** Stopping 1 controllers
-c0
-*** Done
-completed in 0.269 seconds
-----
-*Post installation additions* +
-
-* Modify the source code of the mininet node.py file as described in https://wiki.opendaylight.org/view/Openflow_Protocol_Library:OpenVirtualSwitch#Stage_3[Stage 3].
-----
---- /root/mininet/build/lib.linux-x86_64-2.7/mininet/node.py 2013-11-22 03:35:12.000000000 -0800
-+++ /usr/local/lib/python2.7/dist-packages/mininet-2.1.0-py2.7.egg/mininet/node.py 2013-11-22 06:17:07.350574387 -0800
-@@ -952,6 +952,10 @@
- datapath: userspace or kernel mode (kernel|user)"""
- Switch.__init__( self, name, **params )
- self.failMode = failMode
-+ protKey = 'protocols'
-+ if self.params and protKey in self.params:
-+ print 'have protcol params!'
-+ self.opts += protKey + '=' + self.params[protKey]
- self.datapath = datapath
-
-@@ -1027,8 +1031,9 @@
- if self.datapath == 'user':
- self.cmd( 'ovs-vsctl set bridge', self,'datapath_type=netdev' )
- int( self.dpid, 16 ) # DPID must be a hex string
-+ print 'OVSswitch opts: ',self.opts
- self.cmd( 'ovs-vsctl -- set Bridge', self,
-- 'other_config:datapath-id=' + self.dpid )
-+ self.opts+' other_config:datapath-id=' + self.dpid)
- self.cmd( 'ovs-vsctl set-fail-mode', self, self.failMode )
- for intf in self.intfList():
- if not intf.IP():
-----
-*Start and test the modified mininet* +
-
-. Start the mn session:
-----
-sudo mn --topo single,3 --controller 'remote,ip=<your controller IP>' --switch ovsk,protocols=OpenFlow10
-----
-[start=2]
-. Alternatively, use this command:
-----
-sudo mn --topo single,3 --controller 'remote,ip=<your controller IP>' --switch ovsk,protocols=OpenFlow13
-----
-[start= 3]
-. Test the version of the protocol used by switch "s1":
-----
-ovs-ofctl -O OpenFlow10 show s1
-ovs-ofctl -O OpenFlow13 show s1
-----
-=== Usage
-
-REST tests openflowplugin
-----
-sudo python odl_tests.py --xmls 1,2
-----
-* For more option informations, use:
-----
-sudo python odl_tests.py --help
-----
-=== Coding tips for OpenFlow Plugin
-If you use Eclipse, the following compiler settings might be useful either during coding or while fixing errors.
-The following errors are noteworthy:
-
-* name shadowing.
-* null checks.
-* missing case in switch block.
-* missing break in case.
-* unused variables/parameters.
-* annotations checks (@override).
-* access to non accessible member of enclosing type.
-* If overriding hashcode or equals, both must be overriden.
-
-Also useful are warnings upon missing javadoc comments for public classes, members, and methods.
-
-.Configure Compiler Errors and Warnings
-image::codinghints1.png[height=750]
-
-.Configure Javadoc
-image::codinghints2.png[width=500]
-
-=== OpenFlow Plugin: Wiring up notifications
-==== Introduction
-OpenFlow messages coming from the OpenflowJava plugin into MD-SAL Notification objects must be translated, and then published to the MD-SAL.
-
-==== To create and register a Translator
-. Create a Translator class.
-. Register the Translator.
-. Register the notificationPopListener to handle Notification Objects.
-
-==== Creating a Translator Class
-An example is available in https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;a=blob;f=openflowplugin/src/main/java/org/opendaylight/openflowplugin/openflow/md/core/translator/PacketInTranslator.java;h=e0944c39bfacad1d396b15087f668d9d1fa1d95d;hb=HEAD[PacketInTranslator.java].
-
-. Create the class.
-----
-public class PacketInTranslator implements IMDMessageTranslator<OfHeader, List<DataObject>> {
-----
-[start=2]
-. Implement the translate function:
-----
-public class PacketInTranslator implements IMDMessageTranslator<OfHeader, List<DataObject>> {
-
- protected static final Logger LOG = LoggerFactory
- .getLogger(PacketInTranslator.class);
- @Override
- public PacketReceived translate(SwitchConnectionDistinguisher cookie,
- SessionContext sc, OfHeader msg) {
- ...
- }
-----
-[start=2]
-. Ensure that the type is the expected one, and cast it:
-----
- if(msg instanceof PacketInMessage) {
- PacketInMessage message = (PacketInMessage)msg;
- List<DataObject> list = new CopyOnWriteArrayList<DataObject>();
-----
-[start=3]
-. Complete the translation and return.
-----
- PacketReceived pktInEvent = pktInBuilder.build();
- list.add(pktInEvent);
- return list;
-----
-==== Registeing the Translator Class
-* Go to https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;a=blob;f=openflowplugin/src/main/java/org/opendaylight/openflowplugin/openflow/md/core/MDController.java;h=d79e18704b05923eee2a2da57d02655e2af6d9c1;hb=HEAD[MDController.java] and in init() add register your Translator:
-----
-public void init() {
- LOG.debug("Initializing!");
- messageTranslators = new ConcurrentHashMap<>();
- popListeners = new ConcurrentHashMap<>();
- //TODO: move registration to factory
- addMessageTranslator(ErrorMessage.class, OF10, new ErrorTranslator());
- addMessageTranslator(ErrorMessage.class, OF13, new ErrorTranslator());
- addMessageTranslator(PacketInMessage.class,OF10, new PacketInTranslator());
- addMessageTranslator(PacketInMessage.class,OF13, new PacketInTranslator());
-----
-NOTE: There is a separate registration for each of the OF10 and OF13. Basically, you indicate the type of openflowjava message you wish to translate for, the OF version, and an instance of your Translator.
-
-==== Registering your MD-SAL message for notification to the MD-SAL
-* In MDController.init() register to have the notificationPopListener handle your MD-SAL Message:
-----
-addMessagePopListener(PacketReceived.class, new NotificationPopListener<DataObject>());
-----
-When a message comes from the openflowjava plugin, it will be translated and published to the MD-SAL.
-
-=== OpenFlow Plugin:Python test scripts
-==== Prerequisites for Python test-scripts
-* Linux based OS (these instructions cover debian 7 - wheezy)
-* Java 1.7+
-* Python (v 2.6)
-* Openvswitch (v 2.0.0)
-* Mininet (v 2.1.0)
-* Controller (supporting openflow 1.3)
-
-==== Installing python tools
-NOTE: Build python tools with python2.6, not the default python.
-
-* wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
-* python2.6 ez_setup.py
-* wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
-* python2.6 get-pip.py
-
-See <<_openflow_plugin_mininet>>
-
-==== Installing Wireshark
-. apt-get install wireshark
-. Make yourself a standard user again (CTRL^D)
-. sudo dpkg-reconfigure wireshark-common
-. sudo usermod -a -G wireshark $USER
-. sudo reboot
-
-==== Adding openflow13 dissector to wireshark
-. mkdir /home/mininet/.wireshark/plugins/
-. Copy the file openflow.so to this directory //TODO add attachment.
-
-==== Controller
-
-*Install Java JDK and set JAVA_HOME*
-
-. apt-get install openjdk-7-jdk
-. Export JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java
-
-*Download, unzip, and run the integration build* +
-
-. Find the latest integration/distribution/base build on nexus.
-. Download it (using for example, wget <url to artifact.zip>) and unzip it (using for example, unzip <artifact.zip>)
-. Start the controller:
-----
-cd opendaylight
-./run.sh -of13
-----
-*Clone openflowplugin project* +
-
-* git clone https://git.opendaylight.org/gerrit/p/openflowplugin.git
-
-==== Tests
-
-* locations: openflowplugin/test-scripts
-* content directory
-** xmls (switch configuration input in xml form)
-** openvswitch
-** *runnable files*:
-*** odl_crud_tests.py
-*** stress_test.py
-*** oper_data_test.py
-*** sw_restart_test.py
-
-=== General
-The tests are designed for running on Linux based machines with installed ovs and mininet python scripts. All scripts has to be started with same permission as mininet (*sudo*).
- Otherwise the scripts can not start mininet. All runnable scripts contains a *help* description for input parameters for a quick orientation.
-
-Basic parameters for all runnable scripts:
-
-* +--help+: dump help
-* +--mnport+: A controller port listener for the openflow switch communications. The parameter is used for configuration startup of the Mininet. A default value is *6653*.
-* +--odlhost+: A controller IP address. The parameter is used for configuration startup of the Mininet and for the rest address builders. A default value is *127.0.0.1* (localhost).
-* +--odlport+: A controller port listener for a http REST communication. The parameter is used for the rest address builders.
-
-=== ODL Test (odl_crud_tests.py)
-
-The test scripts are designed like CRUD (Create Read Update Delete) End-to-End black-box test suite for testing the switch configuration inputs/outputs via RESTconf. (It could work with mininet [opf13] by CPqD,OVS only.)
-
-All inputs are read from xml files: +
-
-* file prefix f*.xml -> Flow ;
-* file prefix g*.xml -> Group ;
-* file prefix m*.xml -> Meter ;
-
-NOTE: Only the Groups and the Meters are supported by CPqD.
-
-The test uses:
-
-* RESTfull (GET, PUT, POST (create data only), DELETE)
-* RESTconf POST sal-services
-
-==== Test life cycle
-
-. Read input and put in to controller via REST (PUT | POST | POST sal-add).
-. Get the stored data via REST from config DataStore and compare input vs output (GET).
-. Get the stored data via REST from operational DataStore and compare input vs output (GET).
-. Modify the input and the update put in to controller via REST (PUT | POST sal-update).
-. Delete the input via REST (DELETE | POST sal-remove).
-. Validate the delete process in config DS and operational DS (GET).
-
-=== Parameters
-
-* +--odlhost+: odl controller host (default value is 127.0.0.1)
-* +--odlport+: odl RESTconf listening port (default value is 8080)
-* +--loglev+: tlogging level definition (default value is DEBUG) debug level contains request/response payload
-* +--mininet+: OpenVSwitch or CPqD (default OVS)
-* +--fxmls+:The number specifies a Flow test xml file from xmls directory (pattern: f{nr}.xml) (e.g. 1,3,34). This parameter has no default value. The script is testing all f_.xml files from xmls directory without --fxmls parameter. 0 means no test. The parameter is relevant for (OVS and CPqD)
-* +--mxmls+:The number specifies a Meter test xml file from xmls directory (pattern: m{nr}.xml) (e.g. 1,3). This parameter has no default value. The script is testing all m_.xml files from xmls directory without --mxmls parameter. 0 means no test. The parameter is relevant for (CPqD only)
-* +--gmls+:The number specifies a Group test xml file from xmls directory (pattern: g{nr}.xml) (e.g. 1,3). This parameter has no default value. The script is testing all g_.xml files from xmls directory without --gxmls parameter. 0 means no test. The parameter is relevant for (CPqD only)
-* +--confresp+: (configuration response) - define a delay to the Configruation Data Store (default = 0 sec.) Increase this value is important for a weaker controller machine
-* +--operresp+: (operation response) - define a delay to the Operation Data Store (defalut = 3 sec.) Increase this value is important for a weaker controller machine or a weaker network
-* +--coloring+: switcher for enable/disable coloring logged output
-
-NOTE: The script has a file and the console logging output handlers (file crud_test.log).
-
-*cmd example*:
-----
-python odl_crud_tests.py --mininet 2 --fxmls 1 --gxmls 0 --mxmls 3 --loglev 2
-----
-cmd means: The script expects ODL Controller RESTconf listener in 127.0.0.1:8080; the script expects Mininet by CPqD (gxmls and mxmls params are not ignored); and the script create the tests for f1.xml, and m3.xml and the script shows only INFO and ERROR logging messages which are colourized.
-
-NOTE: The device Errors listener is not supported yet. We recommend that you use a wireshark tool for the investigation of an unexpected behaviour.
-
-=== Stress Test (stress_test.py)
-
-The test simulates multiple connections for the repeatable END-TO-END add flow test scenario. The flow pattern is the same (look at openvswitch.flow_tools.py). The script changes only a flow_id value.
-
-The test life cycle:
-
-* Initialize mininet and thread pool
-* The incremental add flow's group (in every thread from thread pool)
-* Check nr. of flows (validate numbers of flows with expected calculated values and make report)
-* Get all flows from switch directly by command line
-* Get all flows from configuration DataStore
-* Get all flows from the operational DataStrore
-* Incrementally delete the groups of the flow (in every thread from thread pool)
- final report
-
-*Parameters*:
-
-* +--threads+: number of threads which should be used for multiple connection simulation in the thread pool. The default value is 50
-* +--flows+: number of flows which should be used for add connection samples
-
-=== Operational Data Test (oper_data_test.py)
-
-The test checks the operational store of the controller. The Flow addition action and deletion action from the Data Store. When a flow is added via REST, it is added to the config store and then pushed to the switch. When it is successfully pushed to the switch, it is also moved to the operational store. Deletion also happens the same way.
-
-You can specify the number of flows added by the parameter:
-----
---flows : number of the flows which are add to switch. The default value is 100
-----
-=== Switch restart (sw_restart_test.py)
-
-The test is for a flow addition to a switch after the switch has been restarted. After the switch is restarted, it should get the flow configuration from the controller operational datastore. The speed at which the configuration is pushed to the restarted switch may vary. So, you can specify the wait time; and the number of retries by wait time; and the number of retries by:
-----
-sw_restart_test.py --wait WAIT_TIME (default is 30)
-sw_restart_test.py --retry NO_RETRIES (default is 1)
-----
-You can also specify that flows are added by xmls from the /xmls folder. If you do not specify this parameter, the default xml template will be used.
-----
-sw_restart_test.py --xmls XMLS (default is generic template)
-----
-=== OpenFlow Plugin: Robot framework tests
-
-==== Prerequisites for robot tests
-
-* Virtual machine with Mininet for OF1.0 and OF1.3 and with OpenSwitch
-* Current version of ODL Controller
-* Python (v 2.6 and higher)
-* Robot framework
-* GIT
-
-==== Installation
-
-There are in three puzzle pieces: +
-
-* ODL controller
-* Mininet with ovs
-* Robot framework + tests
-
-NOTE: Use VMs to run them on the same machine or distribute them.
-
-*All-in-one strategy: Advantages and disadvantages*
-
-* Easy to transfer whole setup (if running on VM)
-* No network issues (especially between VMs)
-* However, there is no simple way to switch or update mininet or ovs
-
-*Distributed strategy: Robot + ODL controller on one VM, mininet on another* +
-
-* Modularity
-* Transfer of the whole set-up involves two VMs
-* VMs need network access to one another (This can be achieved by the 'internal network' of virtualBox.)
-
-==== VM with Mininet
-
-There are three options to create a VM:
-
-* Follow instructions on this Opendaylight wiki page at:
- https://wiki.opendaylight.org/view/CrossProject:Integration_Group:Create_System_Test_Environment#Install_Mininet_for_OF1.0_and_OF1.3[Install Mininet for OF1.0 and OF1.3]
-* Download https://wiki.opendaylight.org/view/CrossProject:Integration_Group:Test_VMs#Links_to_VMs[Preinstalled VMs]
- or there is also a possibility to create mininet VM from scratch (based on debian distribution)
-
-IMPORTANT: In order for robot framework to be able to control mininet through ssh the prompt on mininet VM has to end with ">" character.
-
-[options="header"]
-|===
-
-| Component | Topic | Included in Guide
-
-| MD-SAL |Southbound Protocol Plugin | Developer guide
-
-| MD-SAL a| Plugin Types:
-
-* Southbound Protocol Plugin
-* Manager-type Application
-* Protocol Library
-* Connector Plugin
-| User Guide
-|===
-
-=== TLS support for OF Plugin
-
-SDN separates the data plane from the control plane of networks. It is imperative that communication between the two planes is secure. +
-Secure communications between the data plane switches and controllers on the control plane require the authentication of switches and controllers.
-Authentication ensures that no unsecured switch connects to a controller, and that no unsecured controller manages a switch. When a controller with TLS configured is opened, the OpenFlow port only accepts Transport Layer Security (TLS) communications.
-Any switch without TLS configured will fail in its connection attempt.
-
-
-Open Secure Sockets Layer (SSL) provides the tools for the public key infrastructure (PKI) management required to establish secure connections between a controller and switches. +
-Information on `SSL on Open vSwitch and ovs controller’ is available at: +
-https://github.com/mininet/mininet/wiki/SSL-on-Open-vSwitch-and-ovs-controller +
-
-In a lab environment, the private key of the controller resides on the mininet host that also acts as the Certification authority (CA) signing host. In a production environment, the key generation for the controller would be separate from that of the switches; only the public controller key is shared with the switches.
-
-NOTE: While in a lab environment, TLS may be configured with the keystore shipped with the controller, the TLS configuration in a production environment must choose a different keystore.
-
-*Creating and signing private and public key certificates* +
-Use ovs pki to create private keys and public certificate files for the switches and the controller. +
-
-
-. On the mininet host, verify whether PKI is initialized: +
-: +ls /var/lib/openvswitch/pki/controllerca/cacert.pem+ +
-. If PKI is not initialized, use: +ovs-pki init+ +
-. To generate the signed certificates, use the request certificates sc-req.pem and ctl-req.pem:
-----
-$ ls /etc/openvswitch
-conf.db ctl-cert.pem ctl-privkey.pem ctl-req.pem sc-cert.pem sc-privkey.pem sc-req.pem
-system-id.conf
-----
-[start=4]
-. To create private keys and public cert files for the switches and the controller, run the ovs-pki:
-----
-cd /etc/openvswitch
-sudo ovs-pki req+sign sc switch
-sudo ovs-pki req+sign ctl controller
-----
-[start=5]
-. From .pem files, create an intermediate Open SSL PKCS 12 formatted keystore to hold the private key for the controller.
-----
-sudo openssl pkcs12 -export -in ctl-cert.pem -inkey ctl-privkey.pem \
--out ctl.p12 -name odlserver \
--CAfile /var/lib/openvswitch/pki/controllerca/cacert.pem -caname root -chain
-You'll be prompted for a password, use "opendaylight"
-Enter Export Password:
-Verifying - Enter Export Password:
-----
-[start=6]
-. Copy the intermediate keystore, which has the private key of the controller, and the switches public key cert file ( ctl.p12 and sc-cert.pem) from the mininet host to any work directory on the controller machine. Import the PKSC 12 format to a Java compatible format that the controller can use:
-----
-sftp mininet@mininetipaddress
-mininet
-sftp get ctl.p12 sc-cert.pem
-quit
-----
-[start=7]
-. For use in the steps that follow, find a keytool in a jdk bin directory, and add it to the path:
-----
-keytool -importkeystore \
- -deststorepass opendaylight -destkeypass opendaylight -destkeystore ctl.jks \
- -srckeystore ctl.p12 -srcstoretype PKCS12 -srcstorepass opendaylight \
- -alias odlserver
-----
-[start=8]
-. Store the public key of the switch in a truststore:
-----
-keytool -importcert -file sc-cert.pem -keystore truststore.jks -storepass opendaylight
-# when prompted "Trust this certificate? [no]:" enter "yes"
-# Certificate was added to keystore
-----
-[start=9]
-. Copy the two keystores to the ssl configuration directory:
-----
-mkdir ODLINSTALL/configuration/ssl
-cp ctl.jks truststore.jks ODLINSTALL/configuration/ssl
-----
-=== Configuring the ODL OpenFlow plugin
-
-* Configure the OF plugin using the following:
-----
-cd configuration/initial
-vi configuration/initial/42-openflowplugin.xml
-# add the <tls> blocks as shown to each of the existing OF-switch-connection-provider modules
-
- <!-- 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>
- <switch-idle-timeout>15000</switch-idle-timeout>
- <tls>
- <keystore>configuration/ssl/ctl.jks</keystore>
- <keystore-type>JKS</keystore-type>
- <keystore-path-type>PATH</keystore-path-type>
- <keystore-password>opendaylight</keystore-password>
- <truststore>configuration/ssl/truststore.jks</truststore>
- <truststore-type>JKS</truststore-type>
- <truststore-path-type>PATH</truststore-path-type>
- <truststore-password>opendaylight</truststore-password>
- <certificate-password>opendaylight</certificate-password>
- </tls>
-
- </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>
- <switch-idle-timeout>15000</switch-idle-timeout>
- <tls>
- <keystore>configuration/ssl/ctl.jks</keystore>
- <keystore-type>JKS</keystore-type>
- <keystore-path-type>PATH</keystore-path-type>
- <keystore-password>opendaylight</keystore-password>
- <truststore>configuration/ssl/truststore.jks</truststore>
- <truststore-type>JKS</truststore-type>
- <truststore-path-type>PATH</truststore-path-type>
- <truststore-password>opendaylight</truststore-password>
- <certificate-password>opendaylight</certificate-password>
- </tls>
-
- </module>
-----
-=== Configuring openvswitch SSL +
-
-*To configure openswitch SSL* +
-
-. Set ovs ssl options.
-----
-sudo ovs-vsctl set-ssl \
- /etc/openvswitch/sc-privkey.pem \
- /etc/openvswitch/sc-cert.pem \
- /var/lib/openvswitch/pki/controllerca/cacert.pem
-----
-[start=2]
-. Start a mininet with SSL connections to the ODL controller.
-.. Open the `ssl_switch_tests.py’ file
-----
-#!/usr/bin/python
-from mininet.net import Mininet
-from mininet.node import Controller, RemoteController
-from mininet.cli import CLI
-from mininet.log import setLogLevel, info
-
-def emptyNet():
- net = Mininet( controller=RemoteController )
- net.addController( 'c0' )
- h1 = net.addHost( 'h1' )
- h2 = net.addHost( 'h2' )
- s1 = net.addSwitch( 's1' )
- net.addLink( h1, s1 )
- net.addLink( h2, s1 )
-
- net.start()
- s1.cmd('ovs-vsctl set-controller s1 ssl:YOURODLCONTROLLERIPADDRESS:6633')
-
- CLI( net )
- net.stop()
-
-if __name__ == '__main__':
- setLogLevel( 'info' )
- emptyNet()
-----
-[start=3]
-. Start mininet with TLS:
-----
-chmod +x ssl_switch_test.py
-sudo ./ssl_switch_test.py
-----
-=== Configuring a hardware switch with TLS
-
-The configuration example that follows uses a Brocade MLX device. +
-*To configure a hardware switch* +
-
-. Set up a tftp server.
-----
-telnet@NetIron MLX-4 Router#enable
-<enter config password>.
-----
-[start=2]
-. Copy the sc-cert.pem and sc-privkey.pem files to the tftp sever on the controller:
-----
-telnet@NetIron MLX-4 Router(config)#copy tftp flash 10.0.0.1 sc-cert.pem client-certificate
-telnet@NetIron MLX-4 Router(config)#copy tftp flash 10.0.0.1 sc-privkey.pem client-private-key
-telnet@NetIron MLX-4 Router(config)#openflow controller ip-address 10.0.0.1
-----
-NOTE: A tftp server runs on the controller host "10.0.0.1".
-
-==== Commands for debugging
-*Debugging mininet* +
-To see connection entries in the ovswitchd log file, use: +
-+sudo tail /var/log/openvswitch/ovs-vswitchd.log+ +
-*Debugging the ODL controller* +
-+./run.sh -Djavax.net.debug=ssl,handshake+ +
-
-=== Open Flow Plugin: Support for extensibility
-OpenFlow (OF) allows vendor-defined extensions to fields in the flow entries of flow tables. OpenFlow-1.3 specifications describe experimenter items using meter, queue, match, action, multipart, table features, and error message. The OF Plugin supports extensions to the action and match fields of flow entries.
-OF Plugin extensibility API is defined in the openflowplugin-extension-api (odl), for example, converter interfaces, and register or lookup keys. OF Plugin extensibility is dependent on the MD-SAL and the OpenFlow Java Library. +
-The extensibility functionality uses a two-level conversion between the following: +
-
-* The semantic high level model (MD-SAL) and the protocol-oriented low level model (OFJava)
-* The low-level model (OFJava) and the Wire protocol
-
-Vendor actions augment the MD-SAL model. MD-SAL defines the flow model using yang. Vendors can extend the existing MD-SAL models by using the augmentation feature of yang. Augments only add new items to the model. They neither remove nor modify existing models. The OFJava-API contains protocol related constants and interfaces describing how to work with OFJava and generated models (generated from yang files). These models are referred to as OFJava-API models. +
-
-.OF Plugin support for extensibility
-image::OFPlugin_ExtensibilitySupportInOFPlugin.png[width=500]
-
-==== Converters (semantic level)
-Converters aid communication between applications and devices by making possible the communication between southbound APIs and their North-bound counterparts. They translate MD-SAL models to OFJava-API models. The default set of converters reside in: openflowplugin/src/main/java/org/opendaylight/openflowplugin/openflow/md/core/sal/convertor
-
-Converters act upon models from and to the MD-SAL. Inputs for *action converter from MD-SAL* are instances of the MD-SAL model: for example, in the case of action, OutputActionCase. The output contains OFJava-API models of Action transferred from applications to devices. Working in reverse, *action converters to MD-SAL* translate OFJava-API models (Action) to MD-SAL models (Action).
-
-After a vendor bundle is activated, converters are registered with the OF plugin so that they can work. Registration is based on the augmentation type and version. Once the converters are registered, the OF Plugin can convert MD-SAL action to OF Java actions.
-
-==== Approaches to action conversion
-The sample that follows shows two approaches to converting action (ActionConvertor.java). The first approach relies on a key field in a generalExtension augmentation. The second approach directly creates the converter lookup key out of the action type.
-----
-else if (action instanceof GeneralExtensionGrouping) {
-
- /**
- * TODO: EXTENSION PROPOSAL (action, MD-SAL to OFJava)
- * - we might need sessionContext as converter input
- *
- */
-
- GeneralExtensionGrouping extensionCaseGrouping = (GeneralExtensionGrouping) action;
- Extension extAction = extensionCaseGrouping.getExtension();
- ConverterExtensionKey<? extends ExtensionKey> key = new ConverterExtensionKey<>(extensionCaseGrouping.getExtensionKey(), version);
- ConvertorToOFJava<Action> convertor =
- OFSessionUtil.getExtensionConvertorProvider().getConverter(key);
- if (convertor != null) {
- ofAction = convertor.convert(extAction);
- }
- } else {
- // try vendor codecs
- TypeVersionKey<org.opendaylight.yang.gen.v1.urn.opendaylight.action.types.rev131112.action.Action> key =
- new TypeVersionKey<>(
- (Class<? extends org.opendaylight.yang.gen.v1.urn.opendaylight.action.types.rev131112.action.Action>) action.getImplementedInterface(),
- version);
- ConvertorActionToOFJava<org.opendaylight.yang.gen.v1.urn.opendaylight.action.types.rev131112.action.Action, Action> convertor =
- OFSessionUtil.getExtensionConvertorProvider().getConverter(key);
- if (convertor != null) {
- ofAction = convertor.convert(action);
- }
- }
-----
-==== Encoders and decoders for augment messages (low level)
-
-Augments are encoded using encoders. Vendor bundles register the encoders so that the OpenFlow Java Library can support the vendor actions. Default sets of encoders and decoders reside in /openflow-protocol-impl/src/main/java/org/opendaylight/openflowjava/protocol/impl/serialization and /openflow-protocol-impl/src/main/java/org/opendaylight/openflowjava/protocol/impl/deserialization.
-The OF plugin uses encoders to create the binary (wire protocol) form of a message object, and write it to the buffer.
-
-Decoders on the other hand are responsible for the following tasks: +
-
-* Read binary buffer
-* Detect the type of message (encoded in the header)
-* Create the corresponding objects, and populate them with values from the buffer
-
-==== Master decoder
-Vendor decoders cannot be directly registered if the actual message type is outside the general header, and only vendor-provided logic can take decisions. Then a master decoder, which is also provided be the vendor, is used. The master decoder contains logic to register decoders and to distinguish between vendor actions. The same work-flow persists: the lookup decoder by key containing version, actionClass, vendorActionSubtype. (For example, the experimenter action makes it appear as if all actions from one vendor have the same header, and the subtype of the actual action lies somewhere further in the buffer.)
-
-The OFJava extensions provide the space for registering vendor encoders and master decoders. They also provide the lookup mechanism to pick the right decoder or encoder for work with a message or buffer.
-
-=== Overload protection in the OF Plugin
-Overload protection in the OpenFlow (OF) Plugin works in the following way: +
-
-. The ConnectionConductor is the source from where all incoming messages are pushed to queues for asynchronous processing. It is the part of the OF Plugin closest to OFJava, and has on*Message methods (listeners to incoming messages). The ConnectionConductorImpl pushes messages to the QueueKeeper. Every ConnectionConductor has a local instance of the QueueKeeper. +
-The QueueKeeper has two queues: +
-** Unordered queues (for packetIn messages)
-** Ordered queues (for other messages) +
-Both queue types are limited and blocking.
-[start=2]
-. If a particular queue is full, the messages pushed to it will be dropped. Upon a successful push, the harverster is pinged to be roused from hibernation.
-. A QueueZipper wraps the two queues, and provides the poll method. This poll method rotates regularly through the underlying queues. If the currently polled queue is empty, it polls the next queue. (See QueueKeeperFairImpl).
-. Each QueueKeeper gets registered by the QueueKeeperHarvester. The Harvester runs upon one thread; iterates through all the registered QueueKeepers; and polls them. The polled message is then queued into the QueueProcessor. +
-If all the registered queueKeepers are empty, the harverster hibernates.
-[start=5]
-. At the QueueProcessor are several threads translating messages from OFJava-API models to MD-SAL models (preserving order). The QueueProcessor uses two threadPools:
-** One threadPool to process the queue items
-** Another threadPool (containing one thread) to publish messages to the MD-SAL +
-
-A queue gets filled for different reasons: +
-
-* The MD-SAL is overloaded.
-* A node is flooding, or something has generally slowed down the processing pipeline. +
-If the queue in the QueueProcessor is full, it blocks the harvester. If the harvester is blocked, the queues in the QueueKeeper will not be emptied.
-
-NOTE: The current implementation of the feature offers no checking of the memory or CPU load to actively throttle messages.
-
-.Overload protection
-
-image::overloadProtectionBrief.png[width=500]
-
-==== Effects of overload protection
-
-* When a node floods the controller, it will not block messages from other nodes.
-* The processing of messages is fair: 'Floody' node messages are neither prioritized, nor do they infest queues outside the ConnectionConductor.
-* Memory is not exhausted on the controller side as messages gets dropped immediately upon an unsuccessful push to the local queue.
-* The functionality cannot create back pressure at the netty level. Pressure affects the echo message, and might cause a connection close action on the switch side.
+++ /dev/null
-== Helium Overview
-
-add text and reference to helium project dependency diagram
-
+++ /dev/null
-== Packet Cable MultiMedia (PCMM)
-
-=== Checking out the Packetcable PCMM project
- git clone https://git.opendaylight.org/gerrit/p/packetcable.git
-
-The above command will create a directory called "packetcable" with the project.
-
-=== System Overview
-
-These components introduce a DOCSIS QoS Service Flow management using the PCMM protocol. The driver component is responsible for the PCMM/COPS/PDP functionality required to service requests from PacketCable Provider and FlowManager. Requests are transposed into PCMM Gate Control messages and transmitted via COPS to the CMTS. This plugin adheres to the PCMM/COPS/PDP functionality defined in the CableLabs specification. PacketCable solution is an MD-SAL compliant component.
-
-.System Overview
-image::pcmm-architecture.png["System Overview",width=500]
-
-=== Dependency Map
-.Dependency Map
-image::pcmm-depends-map.png["Dependency Map",width=500]
-
-=== Packetcable Components
-
-packetcable is comprised of three OpenDaylight bundles
-
-.Table of Bundle and Components
-[options="header"]
-|=======================
-| Bundle|Description
-| packetcable-model | Contains the YANG information model for flows and nodes
-| packetcable-provider | Provider hosts the model processing, RESTCONF, API implementation, and brokers requests to consumer
-| packetcable-driver | Driver manages PCMM Gate message over COPS for flows and CMTS connections
-| packetcable-consumer | Consumer is the codec for for transforming the model of nodes and flows to COPS Gate messages
-|=======================
-
-
-See link:https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-model/src/main/yang[YANG Model]
-
-=== Download and Install
-
-Current instructions
-
-==== Download
-
-link:http://nexus.opendaylight.org/content/groups/staging/org/opendaylight/integration/distribution-karaf/0.2.0-Helium/distribution-karaf-0.2.0-Helium.zip[Download]
-
-
-http://nexus.opendaylight.org/content/groups/staging/org/opendaylight/integration/distribution-karaf/
-
-==== Unzip
-[source, text]
-----
-unzip distribution-karaf-0.2.0-Helium.zip
-----
-
-
-==== Run Karaf
-[source, text]
-----
-cd distribution-karaf-0.2.0-Helium/bin/
-./karaf
-----
-
-=== Preparing to Work with the Packetcable PCMM Service
-
-==== Minimum install procedure
-
-[source, text]
-----
-opendaylight-user@root>feature:install odl-packetcable-all
-----
-
-==== Useful Features to Start with PCMM
-
-[source, text]
-----
-opendaylight-user@root>feature:install odl-restconf odl-l2switch-switch odl-dlux-core odl-mdsal-apidocs odl-packetcable-all
-----
-
-==== Auto Starting a Series of Bundles using Karaf
-
-Edit etc/org.apache.karaf.features.cfg ‘featuresBoot'
-[source, text]
-----
-#
-# Comma separated list of features to install at startup
-#
-featuresBoot=config,standard,region,package,kar,ssh,management,odl-restconf,odl-l2switch-switch,odl-dlux-core,odl-mdsal-apidocs,odl-packetcable-all
-
-----
-
-==== Starting Karaf as System Service
-----
-cd distribution-karaf-0.2.0-Helium/
-sudo bin/start
-----
-
-===== Accessing the Karaf Console
-[source, text]
-----
- ssh -p 8101 karaf@localhost
-
-----
-
-===== Add These Directives to Your Operating System Profile to Change the Karaf Startup Parameters for Troubleshooting
-[source, text]
-----
- export KARAF_DEBUG=true
- export JAVA_DEBUG_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"
-----
-
-===== Tell a Bundle to Log Debug
-[source, text]
-----
- log:set org.opendaylight.packetcable
-----
-
-
-==== Management UI
-
-http://localhost:8181/dlux/index.html
-
-|=======================
-| user | admin
-| password | admin
-|=======================
-
-
-Sign in
-
-.Sign in to Dlux UI
-image::pcmm-dlux-login.png["Dlux Login",width=500]
-
-Manage Flows
-
-.View and Manage Flows in Dlux
-image::pcmm-dlux-flows.png["Dlux Flows",width=500]
-
-Manage Nodes
-
-.View and Manage Nodes in Dlux
-image::pcmm-dlux-nodes.png["Dlux Nodes",width=500]
-
-
-=== Explore and exercise the PacketCable REST API
-http://localhost:8181/apidoc/explorer/index.html
-
-
-
-=== RESTCONF API Explorer
-
-http://localhost:8181/apidoc/explorer/index.html
-
-Add a CMTS to Opendaylight Inventory
-
-.Add CMTS using RESTCONF Explorer
-image::pcmm-apidoc-explorer.png["Add CMTS using RESTCONF Explorer",width=500]
-
-
-=== Postman
-
-link:https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Configure the Chrome browser]
-
-Download and import sample
-link:https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-client[packetcable collection] for Postman.
-
-.Postman Collection for Packetcable PCMM
-image::pcmm-postman.png["Postman",width=500]
-
-=== Custom Testsuite
-
-Most of the tests for RESTCONF can be adapted for PCMM and service flow testing. The following list of
-Packetcable client testing. Browse this folder for tests and examples used for testing.
-
-==== restconfapi.py
-
-Scripted series of packetcable actions testing compliance. Other flows can be formulated and added to create a regression test of what kind of flows are interesting for use cases.
-
-
-==== flow_config_perf_pcmm.py
-For load testing there is this nice tool that could be repurpose to load test a CMTS.
-
-=== Using Wireshark to Trace PCMM
-To start wireshark with privileges issue the following command:
-[source, text]
-----
-sudo wireshark &
-----
-
-Select the interface to monitor.
-
-Use the Filter to only display COPS messages by applying “cops” in the filter field.
-.Using Wireshark to View COPS
-image::pcmm-wireshark.png["Wireshark",width=500]
-
-=== Debugging and Verifying DQoS Gate (Flows) on the CMTS
-
-Below are some of the most useful CMTS commands to verify flows have been enabled on the CMTS.
-
-==== Cisco
-
-link:http://www.cisco.com/c/en/us/td/docs/cable/cmts/cmd_ref/b_cmts_cable_cmd_ref.pdf[Cisco CMTS Cable Command Reference]
-
-
-=== Find the Cable Modem
-
-[source,text]
-----
-10k2-DSG#show cable modem
- D
-MAC Address IP Address I/F MAC Prim RxPwr Timing Num I
- State Sid (dBmv) Offset CPE P
-0010.188a.faf6 0.0.0.0 C8/0/0/U0 offline 1 0.00 1482 0 N
-74ae.7600.01f3 10.32.115.150 C8/0/10/U0 online 1 -0.50 1431 0 Y
-0010.188a.fad8 10.32.115.142 C8/0/10/UB w-online 2 -0.50 1507 1 Y
-000e.0900.00dd 10.32.115.143 C8/0/10/UB w-online 3 1.00 1677 0 Y
-e86d.5271.304f 10.32.115.168 C8/0/10/UB w-online 6 -0.50 1419 1 Y
-----
-
-==== Show PCMM Plugin Connection
-
-[source,text]
-----
-10k2-DSG#show packetcabl ?
- cms Gate Controllers connected to this PacketCable client
- event Event message server information
- gate PacketCable gate information
- global PacketCable global information
-
-10k2-DSG#show packetcable cms
-GC-Addr GC-Port Client-Addr COPS-handle Version PSID Key PDD-Cfg
-
-
-10k2-DSG#show packetcable cms
-GC-Addr GC-Port Client-Addr COPS-handle Version PSID Key PDD-Cfg
-10.32.0.240 54238 10.32.15.3 0x4B9C8150/1 4.0 0 0 0
-----
-
-==== Show COPS Messages
-
-[source,text]
-----
-debug cops details
-----
-
-==== Use CM Mac Address to List Service Flows
-
-[source,text]
-----
-10k2-DSG#show cable modem
- D
-MAC Address IP Address I/F MAC Prim RxPwr Timing Num I
- State Sid (dBmv) Offset CPE P
-0010.188a.faf6 --- C8/0/0/UB w-online 1 0.50 1480 1 N
-74ae.7600.01f3 10.32.115.150 C8/0/10/U0 online 1 -0.50 1431 0 Y
-0010.188a.fad8 10.32.115.142 C8/0/10/UB w-online 2 -0.50 1507 1 Y
-000e.0900.00dd 10.32.115.143 C8/0/10/UB w-online 3 0.00 1677 0 Y
-e86d.5271.304f 10.32.115.168 C8/0/10/UB w-online 6 -0.50 1419 1 Y
-
-
-10k2-DSG#show cable modem 000e.0900.00dd service-flow
-
-
-SUMMARY:
-MAC Address IP Address Host MAC Prim Num Primary DS
- Interface State Sid CPE Downstream RfId
-000e.0900.00dd 10.32.115.143 C8/0/10/UB w-online 3 0 Mo8/0/2:1 2353
-
-
-Sfid Dir Curr Sid Sched Prio MaxSusRate MaxBrst MinRsvRate Throughput
- State Type
-23 US act 3 BE 0 0 3044 0 39
-30 US act 16 BE 0 500000 3044 0 0
-24 DS act N/A N/A 0 0 3044 0 17
-
-
-
-UPSTREAM SERVICE FLOW DETAIL:
-
-SFID SID Requests Polls Grants Delayed Dropped Packets
- Grants Grants
-23 3 784 0 784 0 0 784
-30 16 0 0 0 0 0 0
-
-
-DOWNSTREAM SERVICE FLOW DETAIL:
-
-SFID RP_SFID QID Flg Policer Scheduler FrwdIF
- Xmits Drops Xmits Drops
-24 33019 131550 0 0 777 0 Wi8/0/2:2
-
-Flags Legend:
-$: Low Latency Queue (aggregated)
-~: CIR Queue
-----
-
-==== Deleting a PCMM Gate Message from the CMTS
-
-[source,text]
-----
-10k2-DSG#test cable dsd 000e.0900.00dd 30
-----
-
-==== Find service flows
-
-All gate controllers currently connected to the PacketCable client are displayed
-
-[source,text]
-----
-show cable modem 00:11:22:33:44:55 service flow ????
-show cable modem
-----
-
-
-==== Debug and display PCMM Gate messages
-[source,text]
-----
-debug packetcable gate control
-debug packetcable gate events
-show packetcable gate summary
-show packetcable global
-show packetcable cms
-----
-
-==== Debug COPS messages
-[source,text]
-----
-debug cops detail
-debug packetcable cops
-debug cable dynamic_qos trace
-----
-
-=== Arris
-
-Pending
-
-
-=== RESTCONF API for Packetcable PCMM
-
-==== CMTS
-
-CMTS can be read, created, updated and deleted by a user having the
-correct role. An ID is used to identify where to read
-or save the CMTS node.
-
-===== Read
-
-[cols="h,5a"]
-|===
-| URL
-| /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
-
-| Method
-| GET
-
-| Request Body
-|
-// include::cmts-get-request.json.adoc[]
-[source,json]
-----
-{}
-----
-| Response Body
-|
-// include::cmts-get-response.json.adoc[]
-[source,json]
-----
-{}
-----
-| Return Codes
-| 201
-|===
-
-===== Create
-
-[cols="h,5a"]
-|===
-| URL
-| /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
-
-| Method
-| PUT
-
-| Request Body
-|
-// include::cmts-put-response.json.adoc[]
-[source,json]
-----
-{
- "packetcable-cmts:cmts-node": {
- "port": "3918",
- "address": "10.200.90.3"
- }
-}
-----
-| Response Body
-|
-[source,json]
-----
-{}
-----
-| Return Codes
-| 201
-|===
-
-
-===== Delete
-
-[cols="h,5a"]
-|===
-| URL
-| /restconf/config/opendaylight-inventory:nodes/node/[id]/packetcable-cmts:cmts-node/
-
-| Method
-| DELETE
-
-| Request Body
-|
-// include::cmts-delete-request.json.adoc[]
-[source,json]
-----
-{}
-----
-| Response Body
-|
-[source,json]
-----
-{}
-----
-| Return Codes
-| 201
-|===
-
-==== Flows
-
-Flows can be read, created, updated and deleted by a user having the
-correct role. A CMTS ID is used to identify which CMTS node to read
-or save the flow. Note: The Table ID is not used.
-
-===== Read
-
-[cols="h,5a"]
-|===
-| URL
-| /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
-
-| Method
-| GET
-
-| Request Body
-|
-// include::flow-get-request.json.adoc[]
-[source,json]
-----
-{}
-----
-| Response Body
-|
-// include::flow-get-response.json.adoc[]
-[source,json]
-----
-{
- "flow": {
- "cookie": "101",
- "cookie_mask": "255",
- "flow-name": "FooXf7",
- "hard-timeout": "1200",
- "id": "256",
- "idle-timeout": "3400",
- "installHw": "false",
- "instructions": {
- "instruction": {
- "apply-actions": {
- "action": {
- "order": "0",
- "traffic-profile": "best-effort"
- }
- },
- "order": "0"
- }
- },
- "match": {
- "ethernet-match": {
- "ethernet-type": {
- "type": "34525"
- }
- },
- "ip-match": {
- "ip-dscp": "60",
- "ip-ecn": "3",
- "ip-protocol": "6"
- },
- "ipv6-destination": "fe80:2acf:e9ff:fe21::6431/94",
- "ipv6-source": "1234:5678:9ABC:DEF0:FDCD:A987:6543:210F/76",
- "tcp-destination-port": "8080",
- "tcp-source-port": "183"
- },
- "priority": "2",
- "strict": "false",
- "table_id": "2"
- }
-}
-----
-|===
-
-===== Create
-
-[cols="h,5a"]
-|===
-| URL
-| /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
-
-| Method
-| PUT
-
-| Request Body
-|
-// include::flow-put-response.json.adoc[]
-[source,json]
-----
-{
- "flow": {
- "barrier": "false",
- "flow-name": "FooXCableFlowCrazyTrafficProfileFBesteffort1",
- "id": "115",
- "installHw": "false",
- "instructions": {
- "instruction": {
- "apply-actions": {
- "action": {
- "traffic-profile": "best-effort",
- "be-authorized-envelope": {
- "traffic-priority":"0",
- "reserved0":"0",
- "reserved1":"0",
- "request-transmission-policy":"0",
- "maximum-sustained-traffic-rate":"0",
- "maximum-traffic-burst":"3044",
- "maximum-reserved-traffic-rate":"0",
- "traffic-rate-packet-size-maximum-concatenated-burst":"0",
- "assumed-minimum-reserved":"1522",
- "required-attribute-mask":"0",
- "forbidden-attribute-mask":"0",
- "attribute-aggregation-rule-mask":"0",
- },
- "be-reserved-envelope": {
- "traffic-priority":"0",
- "reserved0":"0",
- "reserved1":"0",
- "request-transmission-policy":"0",
- "maximum-sustained-traffic-rate":"0",
- "maximum-traffic-burst":"3044",
- "maximum-reserved-traffic-rate":"0",
- "traffic-rate-packet-size-maximum-concatenated-burst":"0",
- "assumed-minimum-reserved":"1522",
- "required-attribute-mask":"0",
- "forbidden-attribute-mask":"0",
- "attribute-aggregation-rule-mask":"0",
- },
- "be-committed-envelope": {
- "traffic-priority":"0",
- "reserved0":"0",
- "reserved1":"0",
- "request-transmission-policy":"0",
- "maximum-sustained-traffic-rate":"0",
- "maximum-traffic-burst":"3044",
- "maximum-reserved-traffic-rate":"0",
- "traffic-rate-packet-size-maximum-concatenated-burst":"0",
- "assumed-minimum-reserved":"1522",
- "required-attribute-mask":"0",
- "forbidden-attribute-mask":"0",
- "attribute-aggregation-rule-mask":"0",
- }
-
- "order": "0"
- }
- },
- "order": "0"
- }
- },
- "match": {
- "ethernet-match": {
- "ethernet-type": {
- "type": "2048"
- }
- },
- "ipv4-destination": "10.0.0.1/24"
- },
- "priority": "2",
- }
-}
-----
-| Response Body
-|
-[source,json]
-----
-{}
-----
-| Return Codes
-| 201
-|===
-
-
-===== Delete
-
-[cols="h,5a"]
-|===
-| URL
-| /restconf/config/opendaylight-inventory:nodes/node/[cmts id]/table/0/flow/[flow id]
-
-| Method
-| DELETE
-
-| Request Body
-|
-// include::flow-delete-request.json.adoc[]
-[source,json]
-----
-{}
-----
-| Response Body
-|
-// include::flow-delete-request.json.adoc[]
-[source,json]
-----
-{}
-----
-| Return Codes
-| 201
-|===
-
-
-
-==== Specifications and References
-The packetcable-driver was written to the
-link:http://www.cablelabs.com/wp-content/uploads/specdocs/PKT-SP-MM-I05-091029.pdf[PacketCable Specification Multimedia Specification PKT-SP-MM-I05-091029]
+++ /dev/null
-== Plugin for OpenContrail
-
-The Developer Guide for the Plugin for OpenContrail can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/Southbound_Plugin_to_the_OpenContrail_Platform:Developer_Guide
+++ /dev/null
-== SNBI Developers' Guide
-The Secure Network Bootstrapping Infrastructure (SNBI) component of OpenDaylight automatically creates secure IP connectivity between a set of forwarding elements (devices) and the controller.
-
-=== Defining characteristics of SNBI bootstrapping
-In the SNBI context, network bootstrapping involves discovering the device, authenticating a device, and installing the device domain certificate so that it becomes part of an administrative domain ("SNBI domain").
-
-SNBI bootstrapping is: +
-
-* Secure: Only devices on the white list of the SNBI registrar are allowed into a domain. The RA (Registrar Authority) and the CA (Certificate Authority) ensure that a secure channel of communication is established between the SNBI registrar and the devices, and also between the devices. SNBI uses Bouncy Castle to run the CA and sign certificates.
-* Automatic: Normal network bootstrapping involves the manual configuration of network connectivity. To secure any control protocol connecting to the device, one typically needs to manually install certificates. SNBI fully automates the configuration of network connectivity (incl. IP address assignment, routing protocol configuration, and others) as well as the distribution and installation of certificates.
-
-=== SNBI components
-An SNBI implementation includes SNBI controllers and forwarding elements.
-
-* Forwarding element component (SNBI agent) +
-The software package for secure discovery service is created and integrated with the network container reference platform for the devices.
-
-* Controller components:
-** SNBI Registrar: The north-bound configuration manager that configures the south-bound SNBI plugin.
-:: The registrar establishes trust in a network domain thereby anchoring it.
-
-:: The SNBI registrar does the following: +
-
-*** Maintains the white list of devices which belong to a domain. An administrator sets a white list for the registrar for every domain.
-*** Decides in accordance with policy rules as to which devices are admitted to a domain.
-*** Manages certificates: Issues, renews, and revokes certificates as a CA. Certificate management is fully self-contained in the SNBI solution.
-** SNBI plugin +
-The secure discovery service is a southbound plugin that runs the SNBI protocol.
-
-==== Forwarding element components
-The SNBI functions in the Forwarding Elements (FEs) are implemented inside lightweight portable foundations.
-
-===== Portable Foundation
-The SNBI portable foundation can use any light weight portable foundation technology that provides a protected and isolated application execution environment. The current SNBI implementation utilizes Docker, a light weight portable foundation mechanism supported by the current Linux kernels.
-
-=== How SNBI works
-An administrator plugs in a device thereby introducing it into a domain. When a forwarding element discovers the new device, it acts as an intermediary between the new device and the registrar, and proxies all device requests to the registrar.
-
-A device gets a neighbour invite request from the registrar which is forwarded by a proxy forwarding element. The device presents its Unique Device Identifier (UDI) to the registrar through the proxy. The UDI could be anything, a serial number, an 802.1AR compliant identifier, or others. The proxy sends the credentials to the registrar for validation. Upon validation, the device sends a Certificate Sign Request (CSR) PKCS10 request and gets it signed by the CA running at the SNBI Registrar. The CA enrols and signs an x.509 certificate.
-
-The device gets a domain name and ID. The device uses the domain name and ID to also derive its IPv6 which it will use to communicate with other SNBI agents over the secure channel.
-
-==== Bootstrapping a device using SNBI
-To bootstrap a device using SNBI: +
-
-. In the Yang model of the REST API for SNBI, enter the names of devices per domain to be bootstrapped. The registrar includes this information in its white list: s/Yang/YANG/.
-. Plug in the device to be bootstrapped.
-
-==== Controller and FE communications
-
-.Communication between the controller and FE
-image::Controller-fe-communication-channels.png[width=500]
-
-*SNBI between controller and portable foundation* +
-The SNBI-plugin on the Controller and the SNBI agent on the "first hop" FE establishes a DTLS/SSL connection to secure their communication. It is assumed that the device or server which runs the Controller runs an instance of the portable foundation or container. This allows for SNBI to automatically establish a secure IP connectivity throughout the network without the need to pre-configure any IP connectivity between the devices in the network. If the Controller is hosted on a device which does not run an instance of an SNBI-agent within a portable foundation, then IP connectivity between the Controller and the "first hop" FE which runs an instance of an SNBI-agent within a portable foundation needs to be configured by other means (for example, manually). +
-s/portable foundation or container/portable foundation/
-
-It is recommended that the Controller always be hosted on a device (server) which also runs an instance of the SNBI-agent within the portable foundation.
-
-*SNBI agent discovery* +
-SNBI-agents discover each other through a discovery protocol.
-
-*Secure communication between devices* +
-SNBI agents establish a secure channel among themselves, which is typically an IPsec connection. Once the secure channel is established, other services running on the same host (be it a forwarding element or a controller) can leverage the secure IP connectivity for their means. In Figure 1, an example "protocol x plugin" leverages the secure channel to communicate between different instances of protocol x. Example protocols which could use the secure channel include OpenFlow, and Netconf. The protocols need not establish their own secure transport (for example, using DTLS/SSL).
-Any protocol can, of course, establish its own additional secure transport on top of the already secure connectivity provided by SNBI.
-
-*Configuration control between SNBI-agent and underlying host OS* +
-An SNBI-agent hosted in a portable foundation controls and retrieves certain configuration parameters through a RESTconf/Netconf interface. This includes: +
-
-* The establishment and configuration of the secure channel (that is to say, the IPsec connection).
-* Routing table control.
-* The retrieval of a UDI.
-
-The configuration interface between portable foundation and underlying host is based on standard IETF YANG models (https://tools.ietf.org/html/rfc7223[RFC 7223] for interface configuration, draft-ietf-netmod-routing-cfg for route management, and others).
-
-This approach decouples the underlying host and its configuration specifics from the portable foundation hosting environment, and allows for the simplified portability of the portable foundation.
-
-==== Benefits of SNBI discovery
-The automatic discovery between SNBI devices and controllers:
-
-* Reveals the physical topology of the network thus supporting network management
-* Exposes a device as either a forwarding element or a controller
-* Associates a device to an administrative domain
-* Makes possible the initiation of controller federation processes through device type and domain information
-
-The SNBI component of the OpenDaylight Controller automatically creates secure network connectivity between devices. This connectivity can be leveraged by other features and functions to for example to install, control and manage the life cycle of additional software components hosted within the portable foundation of a forwarding element..
-The portable foundation built on container technology can be extended to support additional orchestration and configuration management functions.
-
-==== SNBI: Non-ODL technologies used
-
-* Yang models: The SNBI APIs are defined through Yang.
-
-:: RFC 6020 ‘YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF) is available at:
-http://tools.ietf.org/html/rfc6020
-
-* Docker
-SNBI uses lightweight portable foundations to implement SNBI functions in FEs. The SNBI portable foundation in the current implementation uses Docker and Linux kernels. SNBI uses Docker to start the portable foundation in a host, and pass needed parameters, such as the CID, by means of environment variables into the container.
-
-:: Information on the Docker open platform is available at:
-https://www.docker.com/
-
-==== SNBI terms and definitions
-
-SNBI Domain:: A logical set of devices with common goals
-Registrar:: SNBI software that acts as a domain trust anchor, incorporating both RA and CA functions to bootstrap new devices
-UDI:: Unique device identifier
-FE:: Forwarding element
-Portable foundation:: Reference environment to host network functions, like the SNBI-agent, on devices. The PF provides infrastructure to help host network-centric software components on devices while decoupling them from the Linux distribution and software load of the underlying host.
-SNBI RA:: The Registration Authority module that authenticates new devices
-SNBI CA:: The Certificate Authority module that signs device certificates
-
-
-
-
-
-
-
-
-
+++ /dev/null
-== SNMP4SDN
-
-The Developer Guide for SNMP4SDN can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/SNMP4SDN:Helium_Developer_Guide
-
+++ /dev/null
-== TCP-MD5
-
-The Developer Guide for TCP-MD5 can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/TCPMD5:Helium_Developer_Guide
-
+++ /dev/null
-== YANG Tools\r
-YANG is a data modelling language used to model configuration and state data manipulated by the Network Configuration Protocol(NETCONF), NETCONF remote procedure calls, and NETCONF notifications.\r
-YANG is used to model the operations and content layers of NETCONF. \r
-\r
-=== Prerequisites for YANG Tools Project\r
-* OpenDayLight account +\r
- https://identity.opendaylight.org/carbon/user-registration/index.jsp?region=region1&item=user_registration_menu[Get an account] to push or edit code on the wiki. You can however pull code anonymously.\r
-* Gerrit Setup for code review +\r
- To use shh follow instructions on Opendaylight wiki page at: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Gerrit_Setup +\r
- To use https follow instructions on Opendaylight wiki page at: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Setting_up_HTTP_in_Gerrit\r
-* Maven 3 to import Maven project from OpendayLight Git repository +\r
- To clone the controller follow instructions at: https://git.opendaylight.org/gerrit/p/controller.git +\r
- To clone the yangtools repositories follow instructions at: https://git.opendaylight.org/gerrit/p/yangtools.git\r
-\r
-NOTE: You need to setup Gerrit to access GIT using ssh.\r
-\r
-=== Pulling code using ssh\r
-To pull code using ssh use the following command: +\r
-\r
- git clone ssh://${ODL_USERNAME}@git.opendaylight.org:29418/yangtools.git;(cd yangtools; scp -p -P 29418 ${ODL_USERNAME}@git.opendaylight.org:hooks/commit-msg .git/hooks/;chmod 755 .git/hooks/commit-msg;git config remote.origin.push HEAD:refs/for/master)\r
-\r
-=== Pulling code using https\r
-To pull code using https, use the following command: +\r
-\r
- git clone https://git.opendaylight.org/gerrit/p/yangtools.git;(cd yangtools; curl -o .git/hooks/commit-msg https://git.opendaylight.org/gerrit/tools/hooks/commit-msg;chmod 755 .git/hooks/commit-msg;git config remote.origin.push HEAD:refs/for/master)\r
-\r
-=== Building the code\r
-To build the code, increase the memory available for Maven. The settings on the Jenkins build server are: +\r
-\r
- export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=256m"\r
-\r
-IMPORTANT: The top level build line for yangtools project is: `cd yangtools;mvn clean install`\r
-\r
-=== Mapping YANG to Java \r
-This chapter covers the details of mapping YANG to Java.\r
-\r
-==== Name of the Package\r
-To configure your project and generate source code from YANG, edit your projects *pom.xml* and add Opendaylight SNAPSHOT repository for snapshot releases. Currently, only snapshots are available. \r
-The name of the package is _org.opendaylight.yang.gen.v1.urn:2:case#module.rev201379_\r
-After replacing digits and JAVA keywords the package name is _org.opendaylight.yang.gen.v1.urn._2._case.module.rev201379_\r
-\r
-The package name consists of the following parts: +\r
-\r
-* *Opendaylight prefix* - Specifies the opendaylight prefix. Every package name starts with the prefix _org.opendaylight.yang.gen.v_ that is hardcoded in *BindingGeneratorUtil.moduleNamespaceToPackageName()*.\r
-* *YANG version* - Specifies the YANG version. YANG version is updated through _module_ substatement _yang-version_.\r
-* *Namespace* - Specifies the value of _module_ subelement and the _namespace_ argument value. \r
- The namespace characters are _: / : - @ $ # ' * + , ; = . character group:/_ are replaced with periods (*.*).\r
-* *Revision* - Specifies the concatenation of word `rev` and value of _module_ subelement _revision_ argument value without leading zeros before month and day. \r
- For example: rev201379\r
-\r
-After the package name is generated check it in if it contains any JAVA key words or digits. If it is so then before the token add an underscore (*_*).\r
-\r
-List of key words which are prefixed with underscore:\r
-\r
----------\r
-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\r
----------\r
-\r
-As an example suppose following yang model:\r
-\r
----------\r
-module module {\r
- namespace "urn:2:case#module";\r
- prefix "sbd";\r
- organization "OPEN DAYLIGHT";\r
- contact "http://www.whatever.com/";\r
- revision 2013-07-09 {\r
- }\r
-}\r
----------\r
-\r
-=== Additional Packages\r
-In cases where the superior YANG elements contain specific subordinate YANG elements additional packages are generated. Table below provides details of superior and subordinate elements: \r
-\r
-[options="header"]\r
-|===\r
-|Superior Element | Subordinate Element \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.output and rpc.input | list, container, (choice isn't supported)\r
-|notification | list, container, (choice isn't supported)\r
-|augment | list, container, choice, case |\r
-|===\r
-\r
-Subordinate elements are not mapped only to JAVA Getter methods in the interface of superior element but, they also generate packages with names consisting of superior element package name and superior element name.\r
-In the example YANG model considers the container element _cont_ as the direct subelement of the module.\r
-\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 superior element for the subordinate elements _cont-inner_ and _outter-list_.\r
-\r
-JAVA code is generated in the following structure: +\r
-\r
-* org.opendaylight.yang.gen.v1.urn.module.rev201379 - package contains element which are subordinate of module \r
- ** Cont.java \r
-* org.opendaylight.yang.gen.v1.urn.module.rev201379.cont - package contains subordinate elements of cont container element \r
- ** ContInner.java \r
- ** OutterList.java \r
-\r
----------\r
- container cont { \r
- container cont-inner {\r
- }\r
- list outter-list {\r
- list list-in-list {\r
- }\r
- }\r
- }\r
----------\r
- \r
-_list outter-list_ is superior element for subordinate element _list-in-list_ \r
-\r
-JAVA code is generated in the following structure: +\r
-\r
-* org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.outter.list - package contains subordinate elements of outter-list list element \r
- ** ListInList.java \r
-\r
-==== Class and interface name\r
-Some YANG elements 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 characters space, -, _ are deleted and subsequent letter is capitalized. At the end first letter is capitalized. Transformation example:\r
-example-name without_capitalization is mapped to \r
-`ExampleNameWithoutCapitalization`\r
-\r
-==== Getters and setters name\r
-In some cases are YANG elements generated as getter or setter methods. This methods are created through class `MethodSignatureBuilder`\r
-The process for getter is: +\r
-\r
-* name of YANG element is converted to JAVA class name style \r
-* the word get is added as preffix \r
-* return type of the getter method is set to element's type substatement value \r
-\r
-The process for setter is: +\r
-\r
-* name of YANG element is converted to JAVA class name style \r
-* word set is added as preffix \r
-* input parameter name is set to element's name converted to JAVA parameter style \r
-* return parameter is set to void \r
-\r
-==== Module\r
-\r
-YANG module is converted to JAVA as two JAVA classes. Each of the class is in the separate JAVA file. The names of JAVA files are composed as follows:\r
-`<YANG_module_name><Sufix>`.java where `<sufix>` can be data or service.\r
-\r
-\r
-\r
-\r
-=== Data Interface\r
-Data Interface has a mapping similar to container, but contains only top level nodes defined in module. \r
-\r
-=== Service Interface\r
-Service Interface serves to describe RPC contract defined in the module. This RPC contract is defined by rpc statements. \r
-\r
-==== Typedef\r
-YANG typedef statement is mapped to JAVA class. Typedef may contain following substatement:\r
-\r
-[options="header"]\r
-|===\r
-|Substatement | Argument Mapped to JAVA\r
-|type| class attribute\r
-|descripton| is not mapped\r
-|units| is not mapped\r
-|default|is not mapped\r
-|===\r
-\r
-==== Valid Arguments Type\r
-Simple values of type argument are mapped as follows:\r
-\r
-[options="header"]\r
-|===\r
-|Argument Type | Mapped to JAVA\r
-|boolean| Boolean\r
-|empty| Boolean\r
-|int8| Byte\r
-|int16|Short\r
-|int32|Integer\r
-|int64|Long\r
-|string|String or, 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|Mapped to JAVA\r
-|enumeration|enum\r
-|bits|class\r
-|leafref|??\r
-|identityref|??\r
-|union|class\r
-|instance-identifier|??\r
-|===\r
-\r
-==== Enumeration Substatement Enum\r
-The YANG enumeration type has to contain some enum substatements. Enumeration is mapped as JAVA enum type (standalone class) and every YANG enum subelement is mapped to JAVA enum's predefined values.\r
-Enum substatement can have following substatements:\r
-\r
-[options="header"]\r
-|===\r
-|Enum's Substatement |Mapped to JAVA\r
-|description|is not mapped\r
-|value|mapped as input parameter for every predefined value of enum\r
-|===\r
-\r
-Example of maping of YANG enumeration to JAVA:\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-\r
-a|\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
-a|\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 JAVA class (standalone class) and every YANG bits subelement is mapped to class boolean attributes. In addition are overriden Object methods `hash, toString, equals`.\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA|JAVA overriden Object methods\r
-a|----\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
-a|----\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
-a|----\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
-==== Union's Substatement Type\r
-If type of typedef is union it has to contain `type` substatements. Union typedef is mapped to class and its `type` subelements are mapped to private class attributes. For every YANG union subtype si generated own JAVA constructor with a parameter which represent just one attribute.\r
-Example to union mapping:\r
-\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA|JAVA overriden Object methods\r
-a|----\r
-typedef typedef-union {\r
- type union {\r
- type int32;\r
- type string;\r
- }\r
-}\r
-a|----\r
-public class TypedefUnion {\r
- \r
- \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
-a|----\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
-==== String Mapping\r
-YANG String can be detailed specified through type subelements length and pattern which are mapped as follows:\r
-\r
-[options="header"]\r
-|===\r
-|Type subelement | 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
-Example of YANG string mapping \r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA|JAVA Overriden Object Methods\r
-a|----\r
-typedef typedef-string {\r
- type string {\r
- length 44;\r
- pattern "[a][.]*"\r
- }\r
-}\r
-----\r
-a|\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
- this.typedefString = typedefString;\r
- }\r
- \r
- public String getTypedefString() {\r
- return typedefString;\r
- }\r
-}\r
-----\r
-a|----\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
-==== Container\r
-YANG Container is mapped to JAVA interface which extends interfaces DataObject, Augmentable<container_interface>, where container_interface is name of mapped interface.\r
-Example of mapping:\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|----\r
-container cont {\r
-}\r
-a|----\r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
-}\r
-|===\r
-==== Leaf\r
-Each leaf has to contain at least one type substatement. The leaf is mapped to getter method of superior element with return type equal to type substatement value.\r
-Example of mapping:\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|----\r
-module module {\r
- \r
- namespace "urn:module";\r
- prefix "sbd";\r
- \r
- organization "OPEN DAYLIGHT";\r
- contact "http://www.whatever.com/"; \r
- \r
- revision 2013-07-09 {\r
- \r
- }\r
- leaf lf {\r
- type string; \r
- } \r
-}\r
-a|----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379;\r
-public interface ModuleData {\r
- String getLf();\r
-} \r
-|===\r
-Example of leaf mapping at container level:\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|\r
-----\r
-container cont {\r
- leaf lf {\r
- type string; \r
- }\r
-} \r
-a|----\r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
- String getLf();\r
-} \r
-|===\r
-\r
-==== Leaf-list\r
-Each leaf-list has to contain one type substatement. The leaf-list is mapped to getter method of superior element with return type equal to List of type substatement value.\r
-Example of mapping of leaf-list.\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|\r
-----\r
-container cont {\r
- leaf-list lf-lst {\r
- type typedef-union;\r
- }\r
-}\r
-a|----\r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
- List<TypedefUnion> getLfLst();\r
-}\r
-|===\r
-\r
-\r
-YANG `typedef-union` and `JAVA TypedefUnion` are the same as in union type.\r
-\r
-==== List\r
-YANG list element is mapped to JAVA interface. In superior element is generated as getter method with return type List of generated interfaces.\r
-Mapping of list substatement to JAVA:\r
-\r
-[options="header"]\r
-|===\r
-|Substatement|Mapping to JAVA\r
-|Key|Class\r
-|===\r
-Example of list mapping _outter-list_ is mapped to JAVA interface _OutterList_ and in _Cont_ interface (superior of _OutterList_) contains getter method with return type List<OutterList> \r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA|JAVA Overriden Object Methods\r
-a|\r
-----\r
-\r
-container cont {\r
- list outter-list {\r
- leaf leaf-in-list {\r
- type uint64; \r
- }\r
- leaf-list leaf-list-in-list {\r
- type string; \r
- }\r
- list list-in-list {\r
- leaf-list inner-leaf-list {\r
- type int16;\r
- }\r
- }\r
- }\r
-}\r
-a|\r
-ListInList.java +\r
-\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.outter.list;\r
- \r
-import org.opendaylight.yangtools.yang.binding.DataObject;\r
-import org.opendaylight.yangtools.yang.binding.Augmentable;\r
-import java.util.List;\r
- \r
-public interface ListInList extends DataObject, Augmentable<ListInList> {\r
- \r
- List<Short> getInnerLeafList();\r
-}\r
-----\r
-OutterListKey.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
-----\r
-OutterList.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
-Cont.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 java.util.List;\r
-import org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.OutterList;\r
- \r
-public interface Cont extends DataObject, Augmentable<Cont> {\r
- \r
- List<OutterList> getOutterList();\r
- \r
-}\r
-----\r
-a| OutterListKey.java\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 \r
-`Choice` element is mapped similarly as `list` element. Choice element is mapped to interface (marker interface) and in the superior element is created using getter method with the return type `List` of this marker interfaces.\r
-`Case` substatements are mapped to the JAVA interfaces which extend mentioned marker interface.\r
-Example of choice mapping: \r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|\r
-----\r
-container cont {\r
- choice choice-test {\r
- case case1 {\r
- }\r
- case case2 {\r
- }\r
- }\r
-}\r
-----\r
-a|\r
-Case1.java\r
-\r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.choice.test;\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 Case1 extends DataObject, Augmentable<Case1>, ChoiceTest {\r
-}\r
-----\r
-Case2.java \r
-----\r
-package org.opendaylight.yang.gen.v1.urn.module.rev201379.cont.choice.test;\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 Case2 extends DataObject, Augmentable<Case2>, ChoiceTest {\r
-}\r
-----\r
-ChoiceTest.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 ChoiceTest extends DataObject {\r
-}\r
-----\r
-a|\r
-\r
-Cont.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
- ChoiceTest getChoiceTest();\r
- \r
-}\r
-----\r
-|===\r
-\r
-==== Grouping and Uses\r
-Grouping is mapped to JAVA interface. Uses used in some element (using of concrete grouping) are mapped as extension of interface for this element with the interface which represents grouping.\r
-Example of grouping and uses mapping.\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|\r
-----\r
-grouping grp {\r
- \r
-}\r
- \r
-container cont {\r
- uses grp;\r
-}\r
-----\r
-a|\r
-Cont.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
-Grp.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
----- \r
-|===\r
-\r
-==== Rpc\r
-Rpc is mapped to JAVA as method of class `ModuleService.java`.\r
-Rpc's substatement are mapped as follows: \r
-\r
-[options="header"]\r
-|===\r
-|Rpc Substatement|Mapping to JAVA\r
-|input|interface\r
-|output|interface\r
-|===\r
-\r
-Example of rpc mapping: \r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|\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
-a| ModuleService.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
-RpcTest1Input.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
-RpcTest1Output.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\r
-`Notification` is mapped to the JAVA interface which extends Notification interface.\r
-Example of notification mapping:\r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|\r
-----\r
-notification notif {\r
- }\r
-----\r
-a| \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
-\r
-==== Augment\r
-`Augment` is mapped to the JAVA interface. The interface starts with the same name as the name of augmented interface. The suffix is order number of augmenting interface. The augmenting interface also extends `Augmentation<>` with actual type parameter equal to augmented interface.\r
-Example of augment mapping. In this example is augmented interface `Cont` so whole parametrized type is `Augmentation<Cont>`. \r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-a|\r
-----\r
-container cont {\r
-} \r
- \r
-augment "/cont" {\r
-}\r
-----\r
-a| Cont.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
-Cont1.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
-==== Identity\r
-The purpose of the identity statement is to define a new globally unique, abstract, and untyped identity. YANG substatement base considers an argument a string; the name of existing identity from which the new identity is derived. Hence, the identity statement is mapped to JAVA abstract class and base substatement is mapped as extends JAVA keyword. The identity name is translated to class name. \r
-\r
-[options="header"]\r
-|===\r
-|YANG|JAVA\r
-\r
-a|\r
-----\r
-identity toast-type { \r
-}\r
-----\r
-a| \r
-----\r
-public abstract class ToastType extends BaseIdentity {\r
- protected ToastType() {\r
- super();\r
- }\r
-}\r
-----\r
-a|\r
-----\r
-identity white-bread {\r
- base toast-type;\r
-}\r
-----\r
-a| WhiteBread.java\r
-----\r
-public abstract class WhiteBread extends ToastType {\r
- protected WhiteBread() {\r
- super();\r
- }\r
-}\r
-----\r
-|===\r
-\r
-\r
- \r
-\r
-\r
// * OpenDaylight_OpenFlow_Plugin:Backlog:Extensibility[Extensibility Framework]
-// include::odl-ofp-yang-models.adoc[]
+include::odl-ofp-yang-models.adoc[]
include::odl-ofp-feature-tree.adoc[]
--- /dev/null
+[[yang-models-ans-api]]
+=== Yang models and API
+
+
+
+[cols="3a,a", width="100%",options="header",]
+|=======================
+|Model |DOC
+2+e|*Openflow basic types*
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-table-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-table-types.yang] |link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-table-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-action-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-action-types.yang]| link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-action-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-flow-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-flow-types.yan] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-flow-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-meter-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-meter-types.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-meter-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-group-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-group-types.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-group-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-match-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-match-types.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-match-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-port-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-port-types.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-port-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-base/src/main/yang/opendaylight-queue-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-queue-types.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-base/target/site/models/opendaylight-queue-types.html[YangDOC]
+2+e|*Openflow services*
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/sal-table.yang;a=blob;hb=refs/heads/stable/boron[sal-table.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/sal-table.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/sal-group.yang;a=blob;hb=refs/heads/stable/boron[sal-group.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/sal-group.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/sal-queue.yang;a=blob;hb=refs/heads/stable/boron[sal-queue.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/sal-queue.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/flow-errors.yang;a=blob;hb=refs/heads/stable/boron[flow-errors.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/flow-errors.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/flow-capable-transaction.yang;a=blob;hb=refs/heads/stable/boron[flow-capable-transaction.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/flow-capable-transaction.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/sal-flow.yang;a=blob;hb=refs/heads/stable/boron[sal-flow.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/sal-flow.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/sal-meter.yang;a=blob;hb=refs/heads/stable/boron[sal-meter.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/sal-meter.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/flow-topology-discovery.yang;a=blob;hb=refs/heads/stable/boron[flow-topology-discovery.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/flow-topology-discovery.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/node-errors.yang;a=blob;hb=refs/heads/stable/boron[node-errors.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/node-errors.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/node-config.yang;a=blob;hb=refs/heads/stable/boron[node-config.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/node-config.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/sal-echo.yang;a=blob;hb=refs/heads/stable/boron[sal-echo.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/sal-echo.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/sal-port.yang;a=blob;hb=refs/heads/stable/boron[sal-port.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/sal-port.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/packet-processing.yang;a=blob;hb=refs/heads/stable/boron[packet-processing.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/packet-processing.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-service/src/main/yang/flow-node-inventory.yang;a=blob;hb=refs/heads/stable/boron[flow-node-inventory.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-service/target/site/models/flow-node-inventory.html[YangDOC]
+
+2+e|*Openflow statistics*
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-statistics/src/main/yang/opendaylight-queue-statistics.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-queue-statistics.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-statistics/target/site/models/opendaylight-queue-statistics.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-statistics/src/main/yang/opendaylight-flow-table-statistics.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-flow-table-statistics.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-statistics/target/site/models/opendaylight-flow-table-statistics.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-statistics/src/main/yang/opendaylight-port-statistics.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-port-statistics.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-statistics/target/site/models/opendaylight-port-statistics.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-statistics/src/main/yang/opendaylight-statistics-types.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-statistics-types.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-statistics/target/site/models/opendaylight-statistics-types.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-statistics/src/main/yang/opendaylight-group-statistics.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-group-statistics.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-statistics/target/site/models/opendaylight-group-statistics.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-statistics/src/main/yang/opendaylight-flow-statistics.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-flow-statistics.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-statistics/target/site/models/opendaylight-flow-statistics.html[YangDOC]
+
+|link:https://git.opendaylight.org/gerrit/gitweb?p=openflowplugin.git;f=model/model-flow-statistics/src/main/yang/opendaylight-meter-statistics.yang;a=blob;hb=refs/heads/stable/boron[opendaylight-meter-statistics.yang] | link:https://jenkins.opendaylight.org/releng/view/openflowplugin/job/openflowplugin-merge-boron/lastSuccessfulBuild/artifact/model/model-flow-statistics/target/site/models/opendaylight-meter-statistics.html[YangDOC]
+
+|*Openflow basic types*
+|=======================
+
+== OVSDB NetVirt
+
+include::ovsdb-overview.adoc[]
+
+include::ovsdb-library-developer.adoc[]
include::ovsdb-southbound-developer.adoc[]
-== OVSDB Hardware VTEP Developer Guide
+=== OVSDB Hardware VTEP Developer Guide
-=== Overview
+==== Overview
TBD
-=== OVSDB Hardware VTEP Architecture
+==== OVSDB Hardware VTEP Architecture
TBD
--- /dev/null
+[[ovsdb-library-developer-guide]]
+=== OVSDB Library Developer Guide
+
+[[overview]]
+==== Overview
+
+The OVSDB library manages the Netty connections to network nodes and
+handles bidirectional JSON-RPC messages. It not only provides OVSDB
+protocol functionality to OpenDaylight OVSDB plugin but also can be used
+as standalone JAVA library for OVSDB protocol.
+
+The main responsibilities of OVSDB library include:
+
+* Manage connections to peers
+* Marshal and unmarshal JSON Strings to JSON objects.
+* Marshal and unmarshal JSON Strings from and to the Network Element.
+
+[[connection-service]]
+==== Connection Service
+
+The OVSDB library provides connection management through the OvsdbConnection
+interface. The OvsdbConnection interface provides OVSDB connection
+management APIs which include both active and passive connections. From
+the library perspective, active OVSDB connections are initiated from the
+controller to OVS nodes while passive OVSDB connections are initiated
+from OVS nodes to the controller. In the active connection scenario
+an application needs to provide the IP address and listening port of OVS nodes
+to the library management API. On the other hand, the library management API
+only requires the info of the controller listening port in the passive
+connection scenario.
+
+For a passive connection scenario, the library also provides a connection
+event listener through the OvsdbConnectionListener interface. The listener
+interface has connected() and disconnected() methods to notify an
+application when a new passive connection is established or an existing
+connection is terminated.
+
+[[ssl-connection]]
+==== SSL Connection
+
+In addition to a regular TCP connection, the OvsdbConnection interface
+also provides a connection management API for an SSL connection. To start
+an OVSDB connection with SSL, an application will need to provide a Java
+SSLContext object to the management API. There are different ways
+to create a Java SSLContext, but in most cases a Java KeyStore with
+certificate and private key provided by the application is required.
+Detailed steps about how to create a Java SSLContext is out of the scope of
+this document and can be found in the Java documentation for
+http://goo.gl/5svszT[JAVA Class SSlContext].
+
+In the active connection scenario, the library uses the given SSLContext to
+create a Java SSLEngine and configures the SSL engine with the client mode for
+SSL handshaking. Normally clients are not required to authenticate
+themselves.
+
+In the passive connection scenario, the library uses the given SSLContext to
+create a Java SSLEngine which will operate in server mode for SSL
+handshaking. For security reasons, the SSLv3 protocol and some cipher suites
+are disabled. Currently the OVSDB server only supports the
+TLS_RSA_WITH_AES_128_CBC_SHA cipher suite and the following protocols:
+SSLv2Hello, TLSv1, TLSv1.1, TLSv1.2.
+
+The SSL engine is also configured to operate on two-way authentication
+mode for passive connection scenarios, i.e., the OVSDB server (controller)
+will authenticate clients (OVS nodes) and clients (OVS nodes) are also
+required to authenticate the server (controller). In the two-way
+authentication mode, an application should keep a trust manager to store
+the certificates of trusted clients and initialize a Java SSLContext with this
+trust manager. Thus during the SSL handshaking process the OVSDB server
+(controller) can use the trust manager to verify clients and only accept
+connection requests from trusted clients. On the other hand, users should
+also configure OVS nodes to authenticate the controller. Open vSwitch
+already supports this functionality in the ovsdb-server command with option
+`--ca-cert=cacert.pem` and `--bootstrap-ca-cert=cacert.pem`. On the OVS
+node, a user can use the option `--ca-cert=cacert.pem` to specify a controller
+certificate directly and the node will only allow connections to the
+controller with the specified certificate. If the OVS node runs ovsdb-server
+with option `--bootstrap-ca-cert=cacert.pem`, it will authenticate the
+controller with the specified certificate cacert.pem. If the certificate
+file doesn’t exist, it will attempt to obtain a certificate from the
+peer (controller) on its first SSL connection and save it to the named
+PEM file `cacert.pem`. Here is an example of ovsdb-server with
+`--bootstrap-ca-cert=cacert.pem` option:
+
+`ovsdb-server --pidfile --detach --log-file --remote punix:/var/run/openvswitch/db.sock --remote=db:hardware_vtep,Global,managers --private-key=/etc/openvswitch/ovsclient-privkey.pem -- certificate=/etc/openvswitch/ovsclient-cert.pem --bootstrap-ca-cert=/etc/openvswitch/vswitchd.cacert`
+
+[[ovsdb-protocol-transactions]]
+==== OVSDB protocol transactions
+
+The OVSDB protocol defines the RPC transaction methods in RFC 7047.
+The following RPC methods are supported in OVSDB protocol:
+
+* List databases
+* Get schema
+* Transact
+* Cancel
+* Monitor
+* Update notification
+* Monitor cancellation
+* Lock operations
+* Locked notification
+* Stolen notification
+* Echo
+
+According to RFC 7047, an OVSDB server must implement all methods, and
+an OVSDB client is only required to implement the "Echo" method and
+otherwise free to implement whichever methods suit its needs. However,
+the OVSDB library currently doesn’t support all RPC methods. For the "Echo"
+method, the library can handle "Echo" messages from a peer and send a JSON
+response message back, but the library doesn’t support actively sending an
+"Echo" JSON request to a peer. Other unsupported RPC methods are listed
+below:
+
+* Cancel
+* Lock operations
+* Locked notification
+* Stolen notification
+
+In the OVSDB library the RPC methods are defined in the Java interface OvsdbRPC.
+The library also provides a high-level interface OvsdbClient as the main
+interface to interact with peers through the OVSDB protocol. In the passive
+connection scenario, each connection will have a corresponding
+OvsdbClient object, and the application can obtain the OvsdbClient
+object through connection listener callback methods. In other words, if
+the application implements the OvsdbConnectionListener interface, it will
+get notifications of connection status changes with the corresponding
+OvsdbClient object of that connection.
+
+[[ovsdb-database-operations]]
+==== OVSDB database operations
+
+RFC 7047 also defines database operations, such as insert, delete, and
+update, to be performed as part of a "transact" RPC request. The OVSDB
+library defines the data operations in Operations.java and provides
+the TransactionBuilder class to help build "transact" RPC requests. To build
+a JSON-RPC transact request message, the application can obtain
+the TransactionBuilder object through a transactBuilder() method in
+the OvsdbClient interface.
+
+The TransactionBuilder class provides the following methods to help build
+transactions:
+
+* getOperations(): Get the list of operations in this transaction.
+* add(): Add data operation to this transaction.
+* build(): Return the list of operations in this transaction. This is the
+same as the getOperations() method.
+* execute(): Send the JSON RPC transaction to peer.
+* getDatabaseSchema(): Get the database schema of this transaction.
+
+If the application wants to build and send a "transact" RPC request to
+modify OVSDB tables on a peer, it can take the following steps:
+
+. Statically import parameter "op" in Operations.java
++
+`import static org.opendaylight.ovsdb.lib.operations.Operations.op;`
++
+. Obtain transaction builder through transacBuilder() method in
+OvsdbClient:
++
+`TransactionBuilder transactionBuilder = ovsdbClient.transactionBuilder(dbSchema);`
++
+. Add operations to transaction builder:
++
+`transactionBuilder.add(op.insert(schema, row));`
++
+. Send transaction to peer and get JSON RPC response:
++
+`operationResults = transactionBuilder.execute().get();`
++
+NOTE:
+Although the "select" operation is supported in the OVSDB library, the
+library implementation is a little different from RFC 7047. In RFC 7047,
+section 5.2.2 describes the "select" operation as follows:
++
+“The "rows" member of the result is an array of objects. Each object
+corresponds to a matching row, with each column specified in "columns"
+as a member, the column's name as the member name, and its value as the
+member value. If "columns" is not specified, all the table's columns are
+included (including the internally generated "_uuid" and "_version"
+columns).”
++
+The OVSDB library implementation always requires the column’s name in the
+"columns" field of a JSON message. If the "columns" field is not
+specified, none of the table’s columns are included. If the application
+wants to get the table entry with all columns, it needs to specify all
+the columns’ names in the "columns" field.
+
+[[reference-documentation]]
+==== Reference Documentation
+
+RFC 7047 The Open vSwitch Databse Management Protocol
+https://tools.ietf.org/html/rfc7047
+
-== OVSDB Openstack Developer Guide
+=== OVSDB Openstack Developer Guide
-=== Overview
-The Open vSwitch database (OVSDB) Plugin component for OpenDaylight implements
+==== Overview
+The Open vSwitch database (OVSDB) Southbound Plugin component for OpenDaylight implements
the OVSDB https://tools.ietf.org/html/rfc7047[RFC 7047] management protocol
that allows the southbound configuration of switches that support OVSDB. The
-component comprises a library and a plugin usages. The OVSDB protocol
+component comprises a library and a plugin. The OVSDB protocol
uses JSON-RPC calls to manipulate a physical or virtual switch that supports OVSDB.
Many vendors support OVSDB on various hardware platforms.
The OpenDaylight controller uses the library project to interact with an OVS
instance.
-http://www.openstack.org[OpenStack] is a popular open source infrastructure
-as a service project, covering compute, storage and network management.
+http://www.openstack.org[OpenStack] is a popular open source Infrastructure
+as a Service (IaaS) project, covering compute, storage and network management.
OpenStack can use OpenDaylight as its network management provider through the
-Neutron API, which acts as a northbound for OpenStack. The providers for
-the Neutron API are in the OVSDB Net-virt piece of OVSDB.
+Neutron API, which acts as a northbound for OpenStack. the OVSDB NetVirt piece
+of the OVSDB project is a provider for the Neutron API in OpenDaylight.
OpenDaylight manages the network flows for the OpenStack compute nodes via
the OVSDB project, with the south-bound plugin. This section describes how to
set that up, and how to tell when everything is working.
-=== OVSDB Openstack Architecture
-The OpenStack integration architecture uses the following technologies: +
+==== OVSDB Openstack Architecture
+The OpenStack integration architecture uses the following technologies:
* https://tools.ietf.org/html/rfc7047[RFC 7047] - The Open vSwitch Database Management Protocol
* http://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-switch-v1.3.4.pdf[OpenFlow v1.3]
-== OVSDB Integration\r
-The Open vSwitch database (OVSDB) Plugin component for OpenDaylight implements the OVSDB https://tools.ietf.org/html/rfc7047[RFC 7047] management protocol that allows the southbound configuration of vSwitches. The component comprises a library and various plugin usages.\r
-The OVSDB protocol uses JSON/RPC calls to manipulate a physical or virtual switch that has OVSDB attached to it. Almost all vendors support OVSDB on various hardware platforms. The OpenDaylight controller uses the native OVSDB implementation to manipulate the Open vSwitch database. \r
-\r
-NOTE: Read the OVSDB User Guide before you begin development.\r
-\r
-=== OpenDaylight OVSDB integration\r
-\r
-For information on how the GRE-endpoint destination IP address is communicated to the controller, see https://docs.google.com/presentation/d/19ua9U6nFJSO0wtenWmJUEzUFmib8ClTkkHTgZ_BvaMk/edit?pli=1#slide=id.g17727178e_180[Neutron and ODL interactions].\r
-\r
-The OpenStack integration architecture uses the following technologies: +\r
-\r
-* https://tools.ietf.org/html/rfc7047[RFC 7047] and http://datatracker.ietf.org/doc/rfc7047/[The Open vSwitch Database Management Protocol]\r
-* OpenFlow v1.3\r
-* OpenStack Neutron ML2 Plugin\r
-\r
-==== Getting the code\r
-----\r
-export ODL_USERNAME=<username for the account you created at OpenDaylight>\r
-git clone ssh://${ODL_USERNAME}@git.opendaylight.org:29418/ovsdb.git;(cd ovsdb; scp -p -P 29418 ${ODL_USERNAME}@git.opendaylight.org:hooks/commit-msg .git/hooks/;chmod 755 .git/hooks/commit-msg;git config remote.origin.push HEAD:refs/for/master)\r
-----\r
-\r
-==== OpenDaylight Mechanism Driver for Openstack Neutron ML2\r
+=== OVSDB Integration\r
+The Open vSwitch database (OVSDB) Southbound Plugin component for OpenDaylight implements\r
+the OVSDB https://tools.ietf.org/html/rfc7047[RFC 7047] management protocol\r
+that allows the southbound configuration of switches that support OVSDB. The\r
+component comprises a library and a plugin. The OVSDB protocol\r
+uses JSON-RPC calls to manipulate a physical or virtual switch that supports OVSDB.\r
+Many vendors support OVSDB on various hardware platforms.\r
+The OpenDaylight controller uses the library project to interact with an OVS\r
+instance.\r
+\r
+NOTE:\r
+Read the OVSDB User Guide before you begin development.\r
+\r
+==== OpenDaylight OVSDB integration\r
+The OpenStack integration architecture uses the following technologies:\r
+\r
+* https://tools.ietf.org/html/rfc7047[RFC 7047] - The Open vSwitch Database Management Protocol\r
+* http://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/openflow-switch-v1.3.4.pdf[OpenFlow v1.3]\r
+* https://wiki.openstack.org/wiki/Neutron/ML2[OpenStack Neutron ML2 Plugin]\r
+\r
+===== OpenDaylight Mechanism Driver for Openstack Neutron ML2\r
This code is a part of OpenStack and is available at: https://github.com/openstack/neutron/blob/master/neutron/plugins/ml2/drivers/mechanism_odl.py\r
\r
+The ODL neutron driver implementation can be found at: https://github.com/openstack/networking-odl\r
+\r
To make changes to this code, please read about https://wiki.openstack.org/wiki/NeutronDevelopment[Neutron Development].\r
\r
-Before submitting the code, run the following tests: +\r
+Before submitting the code, run the following tests:\r
+\r
----\r
tox -e py27\r
tox -e pep8\r
----\r
-==== Importing the code in to Eclipse or IntelliJ\r
-Check out either of the following: +\r
+\r
+===== Importing the code in to Eclipse or IntelliJ\r
+To import code, look at either of the following pages:\r
\r
* https://wiki.opendaylight.org/view/Eclipse_Setup[Getting started with Eclipse]\r
* https://wiki.opendaylight.org/view/OpenDaylight_Controller:Developing_With_Intellij[Developing with Intellij]\r
\r
* To ensure that a project in Eclipse does not have a conflicting name in the workspace, select Advanced > Name Template > [groupId].[artifactId] when importing the project.\r
\r
-==== Browsing the code\r
+===== Browsing the code\r
The code is mirrored to https://github.com/opendaylight/ovsdb[GitHub] to make reading code online easier. \r
\r
-==== Source code organization\r
+===== Source code organization\r
\r
-The OVSDB project generates 3 x Karaf Modules:\r
+The OVSDB project generates the following Karaf modules:\r
\r
- ovsdb -- all ovsdb related artifacts\r
- of-nxm-extensions -- openflow nxm extensions\r
- ovs-sfc -- openflow service chainning function\r
-\r
-Both of-nxm-extensions and ovs-sfc are expected to be moved out of the ovsdb source tree in the future.\r
+* ovsdb.karaf -- all openstack netvirt related artifacts\r
+* ovsdb.library-karaf -- the OVSDB library reference implementation\r
+* ovsdb.openstack.net-virt-sfc-karaf -- openflow service function chaining\r
+* ovsdb.hwvtepsouthbound-karaf -- the hw_vtep schema southbound plugin\r
+* ovsdb.southbound-karaf - the Open_vSwitch schema plugin\r
\r
Following are a brief descriptions on directories you will find a the root ovsdb/ directory:\r
\r
-* _commons_ contains the parent POM file for Maven project which is used to get consistency of settings across the project. \r
+* _commons_ contains the parent POM file for Maven project which is used to get consistency of settings across the project.\r
+\r
+* _features_ contains all the Karaf related feature files.\r
+\r
+* _hwvtepsouthbound_ contains the hw_vtep southbound plugin.\r
+\r
+* _karaf_ contains the ovsdb library and southbound and OpenStack bundles for the OpenStack integration.\r
+\r
+* _library_ contains a schema-independent library that is a reference implementation for RFC 7047.\r
+\r
+* _openstack_ contains the northbound handlers for Neutron used by OVSDB, as well as their providers. The NetVirt SFC implementation is also located here.\r
\r
-* _distribution_ contains the OVSDB distribution. For OSGI, this is the latest Virtualization Edition pulled from the Integration project with your local OVSDB artifacts added. This gives developers the ability to run the controller for testing. \r
-For Karaf, this is the latest Karaf bundle pulled from the Integration project, with your local OVSDB Karaf bundles mentioned above.\r
+* _ovsdb-ui_ contains the DLUX implementation for displaying network virtualization.\r
\r
-* _openstack_ contains the northbound handlers for Neutron used by OVSDB, as well as their providers.\r
+* _resources_ contains useful scripts, how-tos, demos and other resources.\r
\r
-* _resources_ contains useful scripts, How-To's and other resources.\r
+* _schemas_ contains the OVSDB schemas that are implemented in OpenDaylight.\r
\r
-* _schemas_ contains the OVSDB schemas that are implemented in ODL.\r
+* _southbound_ contains the plugin for converting from the OVSDB protocol to MD-SAL and vice-versa.\r
\r
-* _utils_ contains helper functions used for handling MD-SAL OpenFlow implementation.\r
+* _utils_ contains a collection of utilities for using the OpenFlow plugin, southbound, Neutron and other helper methods.\r
\r
-=== Building and running OVSDB\r
+==== Building and running OVSDB\r
*Prerequisites* +\r
\r
* JDK 1.7+\r
* Maven 3+\r
\r
[[ovsdbBuildSteps]]\r
-==== Building a Karaf feature and deploying it in an Opendaylight Karaf distribution +\r
-This is a new method for Opendaylight distribution wherein there are no defined editions such \r
-as Base, Virtualization, or SP editions. The end-customer can choose to deploy the required feature based on user deployment needs.\r
-\r
+===== Building a Karaf feature and deploying it in an Opendaylight Karaf distribution +\r
. From the root ovsdb/ directory, run *mvn clean install*.\r
-. Unzip the distribution-karaf-<VERSION_NUMBER>-SNAPSHOT.zip file created from step 1 in the directory ovsdb/distribution/opendaylight-karaf/target:\r
+. Unzip the karaf-<VERSION_NUMBER>-SNAPSHOT.zip file created from step 1 in the directory ovsdb/karaf/target/:\r
----\r
-unzip distribution-karaf-<VERSION_NUMBER>-SNAPSHOT.zip\r
+unzip karaf-<VERSION_NUMBER>-SNAPSHOT.zip\r
----\r
-==== Downloading OVSDB's Karaf distribution +\r
+===== Downloading OVSDB's Karaf distribution +\r
Instead of building, you can download the latest OVSDB distribution from the Nexus server. The link for that is:\r
----\r
-http://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/ovsdb/distribution.ovsdb/1.2.0-SNAPSHOT/\r
+https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/ovsdb/karaf/1.3.0-SNAPSHOT/\r
----\r
\r
-==== Running Karaf feature from OVSDB's Karaf distribution +\r
+===== Running Karaf feature from OVSDB's Karaf distribution +\r
\r
[[ovsdbStartingOdl]]\r
. Start ODL, from the unzipped directory\r
feature:install odl-ovsdb-openstack\r
----\r
\r
-For ovsdb northbound, you will also need to invoke\r
-----\r
-feature:install odl-ovsdb-northbound\r
-----\r
-===== Sample output from the Karaf console\r
+====== Sample output from the Karaf console\r
----\r
opendaylight-user@root>feature:list | grep -i ovsdb \r
-odl-ovsdb-all | 1.0.0-SNAPSHOT | | ovsdb-1.0.0-SNAPSHOT \r
-OpenDaylight :: OVSDB :: all \r
-odl-ovsdb-library | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT \r
-OVSDB :: Library \r
-odl-ovsdb-schema-openvswitch | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT \r
-OVSDB :: Schema :: Open_vSwitch \r
-odl-ovsdb-schema-hardwarevtep | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT \r
-OVSDB :: Schema :: hardware_vtep\r
-odl-ovsdb-plugin | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT \r
-OpenDaylight :: OVSDB :: Plugin\r
-odl-ovsdb-northbound | 0.6.0-SNAPSHOT | | ovsdb-1.0.0-SNAPSHOT \r
-OpenDaylight :: OVSDB :: Northbound \r
-odl-ovsdb-openstack | 1.0.0-SNAPSHOT | x | ovsdb-1.0.0-SNAPSHOT \r
-OpenDaylight :: OVSDB :: OpenStack Network Virtual \r
-odl-ovsdb-ovssfc | 0.0.1-SNAPSHOT | | ovsdb-0.0.1-SNAPSHOT \r
-OpenDaylight :: OVSDB :: OVS Service Function Chai\r
-odl-openflow-nxm-extensions | 0.0.3-SNAPSHOT | x | ovsdb-0.0.3-SNAPSHOT \r
-OpenDaylight :: Openflow :: Nicira Extensions\r
-----\r
-\r
-==== Testing patches\r
+opendaylight-user@root>feature:list -i | grep ovsdb\r
+odl-ovsdb-southbound-api | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: api\r
+odl-ovsdb-southbound-impl | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: impl\r
+odl-ovsdb-southbound-impl-rest | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: impl :: REST\r
+odl-ovsdb-southbound-impl-ui | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: impl :: UI\r
+odl-ovsdb-library | 1.2.1-SNAPSHOT | x | odl-ovsdb-library-1.2.1-SNAPSHOT | OpenDaylight :: library\r
+odl-ovsdb-openstack | 1.2.1-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OpenDaylight :: OVSDB :: OpenStack Network Virtual\r
+----\r
+\r
+===== Testing patches\r
It is recommended that you test your patches locally before submission.\r
- \r
-==== Neutron integration\r
+\r
+===== Neutron integration\r
To test patches to the Neutron integration, you need a http://devstack.org/guides/multinode-lab.html[Multi-Node Devstack Setup]. The ``resources`` folder contains sample ``local.conf`` files.\r
\r
-==== Open vSwitch\r
+===== Open vSwitch\r
To test patches to the library, you will need a working http://openvswitch.org/[Open vSwitch]. Packages are available for most Linux distributions. If you would like to run multiple versions of Open vSwitch for testing you can use https://github.com/dave-tucker/docker-ovs[docker-ovs] to run Open vSwitch in https://www.docker.com/[Docker] containers. \r
\r
-==== Mininet\r
+===== Mininet\r
http://mininet.org/[Mininet] is another useful resource for testing patches. Mininet creates multiple Open vSwitches connected in a configurable topology. \r
\r
-==== Vagrant\r
-\r
-The Vagrant file in the root of the OVSDB source code provides an easy way to create VMs for tests. \r
+===== Vagrant\r
+The Vagrant file in the root of the OVSDB source code provides an easy way to create VMs for tests.\r
\r
* To install Vagrant on your machine, follow the steps at: https://docs.vagrantup.com/v2/installation/[Installing Vagrant].\r
\r
vagrant destroy\r
----\r
\r
-=== OVSDB integration design\r
-==== Resources\r
+==== OVSDB integration design\r
+===== Resources\r
See the following: +\r
\r
* http://networkheresy.com/2012/09/15/remembering-the-management-plane/[Network Heresy]\r
\r
* http://www.youtube.com/channel/UCMYntfZ255XGgYFrxCNcAzA[ODL OVSDB Youtube Channel]\r
* https://wiki.opendaylight.org/view/OVSDB_Integration:Mininet_OVSDB_Tutorial[Mininet OVSDB Tutorial]\r
+* https://wiki.opendaylight.org/view/OVSDB_Integration:Main#Getting_Started_with_OpenDaylight_OVSDB_Plugin_Network_Virtualization[OVSDB Getting Started]\r
\r
-=== OpenDaylight OVSDB southbound plugin architecture and design\r
+==== OpenDaylight OVSDB southbound plugin architecture and design\r
OpenVSwitch (OVS) is generally accepted as the unofficial standard for Virtual Switching in the Open hypervisor based solutions. Every other Virtual Switch implementation, properietery or otherwise, uses OVS in some form.\r
For information on OVS, see http://openvswitch.org/[Open vSwitch].\r
\r
In Software Defined Networking (SDN), controllers and applications interact using two channels: OpenFlow and OVSDB. OpenFlow addresses the forwarding-side of the OVS functionality. OVSDB, on the other hand, addresses the management-plane. \r
A simple and concise overview of Open Virtual Switch Database(OVSDB) is available at: http://networkstatic.net/getting-started-ovsdb/\r
\r
-==== Overview of OpenDaylight Controller architecture\r
+===== Overview of OpenDaylight Controller architecture\r
The OpenDaylight controller platform is designed as a highly modular and plugin based middleware that serves various network applications in a variety of use-cases. The modularity is achieved through the Java OSGi framework. The controller consists of many Java OSGi bundles that work together to provide the required\r
controller functionalities. \r
\r
For example, the OpenFlow plugin might serve the Data-Plane needs of an OVS element, while the OVSDB plugin can serve the management plane needs of the same OVS element.\r
As the Openflow Plugin talks OpenFlow protocol with the OVS element, the OVSDB plugin will use OVSDB schema over JSON-RPC transport.\r
\r
-=== OVSDB southbound plugin\r
+==== OVSDB southbound plugin\r
The http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-02[Open vSwitch Database Management Protocol-draft-02] and http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf[Open vSwitch Manual] provide theoretical information about OVSDB.\r
The OVSDB protocol draft is generic enough to lay the groundwork on Wire Protocol and Database Operations, and the OVS Manual currently covers 13 tables leaving space for future OVS expansion, and vendor expansions on proprietary implementations.\r
The OVSDB Protocol is a database records transport protocol using JSON RPC1.0. For information on the protocol structure, see http://networkstatic.net/getting-started-ovsdb/[Getting Started with OVSDB].\r
* OVSDB to OpenFlow plugin mapping service \r
* Inventory Service \r
\r
-=== Connection service\r
-One of the primary services that most southbound plugins provide to SAL in Opendaylight and NSF is Connection Service. The service provides protocol specific connectivity to network elements, and supports the connectivity management services as specified by the OpenDaylight Connection Manager. \r
+==== Connection service\r
+One of the primary services that most southbound plugins provide in Opendaylight a Connection Service. The service provides protocol specific connectivity to network elements, and supports the connectivity management services as specified by the OpenDaylight Connection Manager.\r
The connectivity services include: +\r
\r
* Connection to a specified element given IP-address, L4-port, and other connectivity options (such as authentication,...) \r
* Disconnection from an element \r
* Handling Cluster Mode change notifications to support the OpenDaylight Clustering/High-Availability feature \r
\r
-By default, the ovsdb-server process running on the hypervisor listens on TCP port 6632 (This is configurable.). The Connection Service takes the connectivity parameters from the connection manager, including the IP-address and TCP-Port for connections. Owing to the many benefits it provides, Connection Service will use the Netty framework (http://netty.io/) for connectivity purposes. \r
-Every successful connection to a network element will result in a Node object (Refer to OpenDaylight SAL Node.java) with the type = "OVSDB" and value = User-Readable Name of the Connection as specified by the Connection Manager. This Node object is returned to the OpenDaylight Connection Manager and the application that invoked the Connect() functionality. \r
-----\r
-IPluginInConnectionService : public Node connect(String identifier, Map<ConnectionConstants, String> params)\r
-----\r
-Any subsequent interaction with this network element through any of the SAL services (Connection, Configuration, and others) will be by means of this Node Object. This Node object will be added to the Inventory maintained and managed by the Inventory Service of the plugin. The Node object will also assist with the OVSDB to Openflow mapping. \r
-\r
-The Node and its "Name" holds the key to the stateful Netty Socket handler maintained under the Connection Object created during the connect() call. The Channel concept of the Netty framework provides the much needed abstraction on the pipelining. With this Channel Pipelining and the asynchronous event handling, the message handling process gets better streamlined and understood. It also makes easier the replacement or manipulation of the pipeline functions in a more controlled fashion.\r
-\r
-.Connection to OVSDB server\r
-image::ConnectionService.png[]\r
-\r
-.Successful connection handling\r
-image::ConnectionServiceReturn.png[]\r
-\r
-=== Network Configuration Service\r
-\r
-The goal of the OpenDaylight Network Configuration services is to provide complete management plane solutions needed to successfully install, configure, and deploy the various SDN based network services. These are generic services which can be implemented in part or full by any south-bound protocol plugin. \r
+==== Network Configuration Service\r
+The goal of the OpenDaylight Network Configuration services is to provide complete management plane solutions needed to successfully install, configure, and deploy the various SDN based network services. These are generic services which can be implemented in part or full by any south-bound protocol plugin.\r
The south-bound plugins can be either of the following: +\r
\r
* The new network virtualization protocol plugins such as OVSDB JSON-RPC\r
\r
The above definition, and more information on Network Configuration Services, is available at : https://wiki.opendaylight.org/view/OpenDaylight_Controller:NetworkConfigurationServices \r
\r
-The current default OVSDB schemas support the Layer2 Bridge Domain services as defined in the Networkconfig.bridgedomain component. \r
-\r
-* Create Bridge Domain: createBridgeDomain(Node node, String bridgeIdentifier, Map<ConfigConstants, Object> params) \r
-* Delete Bridge Domain: deleteBridgeDomain(Node node, String bridgeIdentifier) \r
-* Add configurations to a Bridge Domain: addBridgeDomainConfig(Node node, String bridgeIdentifier, Map<ConfigConstants, Object> params) \r
-* Delete Bridge Domain Configuration: removeBridgeDomainConfig(Node node, String bridgeIdentifier, Map<ConfigConstants, Object> params) \r
-* Associate a port to a Bridge Domain: addPort(Node node, String bridgeIdentifier, String portIdentifier, Map<ConfigConstants, Object> params); \r
-* Disassociate a port from a Bridge Domain: deletePort(Node node, String bridgeIdentifier, String portIdentifier) \r
-* Add configurations to a Node Connector / Port: addPortConfig(Node node, String bridgeIdentifier, String portIdentifier, Map<ConfigConstants, Object> params) \r
-* Remove configurations from a Node Connector: removePortConfig(Node node, String bridgeIdentifier, String portIdentifier, Map<ConfigConstants, Object> params) \r
-\r
-The above services are defined as generalized entities in SAL in order to ensure their compatibility with all relevant southBound plugins equally. Hence, the OVSDB plugin must derive appropriate specific configurations from a generalized request. For example: addPort() or addPortConfig() SAL service call takes in a params option which is a Map structure with a Constant Key. \r
-These ConfigConstants are defined in SAL network configuration service: +\r
-----\r
-public enum ConfigConstants {\r
- TYPE("type"),\r
- VLAN("Vlan"),\r
- VLAN_MODE("vlan_mode"),\r
- TUNNEL_TYPE("Tunnel Type"),\r
- SOURCE_IP("Source IP"),\r
- DEST_IP("Destination IP"),\r
- MACADDRESS("MAC Address"),\r
- INTERFACE_IDENTIFIER("Interface Identifier"),\r
- MGMT("Management"),\r
- CUSTOM("Custom Configurations");\r
-}\r
-----\r
-These are mapped to the appropriate OVSDB configurations. So, if the request is to create a VXLAN tunnel with src-ip=x.x.x.x, dst-ip=y.y.y.y, then the params Map structure may contain:\r
-----\r
-{\r
-TYPE = "tunnel",\r
-TUNNEL_TYPE = "vxlan",\r
-SOURCE_IP="x.x.x.x",\r
-DEST_IP="y.y.y.y"\r
-}\r
-----\r
-NOTE: All of the APIs take in the Node parameter which is the Node value returned by the connect() method explained in <<_connection_service>>.\r
-\r
-==== Bidirectional JSON-RPC library\r
+===== Bidirectional JSON-RPC library\r
The OVSDB plugin implements a Bidirectional JSON-RPC library. It is easy to design the library as a module that manages the Netty connection towards the Element. \r
\r
The main responsibilities of this Library are: +\r
* Demarshal and marshal JSON Strings to JSON objects \r
* Demarshal and marshal JSON Strings from and to the Network Element.\r
\r
-==== OVSDB Schema definitions and Object mappers\r
+===== OVSDB Schema definitions and Object mappers\r
The OVSDB Schema definitions and Object Mapping layer sits above the JSON-RPC library. It maps the generic JSON objects to OVSDB schema POJOs (Plain Old Java Object) and vice-versa. This layer mostly provides the Java Object definition for the corresponding OVSDB schema (13 of them) and also will provide much more friendly API abstractions on top of these object data. This helps in hiding the JSON semantics from the functional modules such as Configuration Service and Tunnel management.\r
\r
-On the demarshaling side, the mapping logic differentiates the Request and Response messages as follows : +\r
+On the demarshaling side the mapping logic differentiates the Request and Response messages as follows : +\r
\r
* Request messages are mapped by its "method" \r
* Response messages are mapped by their IDs which were originally populated by the Request message.\r
The JSON semantics of these OVSDB schema is quite complex.\r
The following figures summarize two of the end-to-end scenarios: +\r
\r
-.End-to-end handling of a Create Bridge request \r
+.End-to-end handling of a Create Bridge request\r
image::ConfigurationService-example1.png[width=500]\r
\r
.End-to-end handling of a monitor response\r
image::MonitorResponse.png[width=500]\r
\r
-==== Overlay tunnel management\r
+===== Overlay tunnel management\r
\r
Network Virtualization using OVS is achieved through Overlay Tunnels. The actual Type of the Tunnel may be GRE, VXLAN, or STT. The differences in the encapsulation and configuration decide the tunnel types. Establishing a tunnel using configuration service requires just the sending of OVSDB messages towards the ovsdb-server. However, the scaling issues that would arise on the state management at the data-plane (using OpenFlow) can get challenging. Also, this module can assist in various optimizations in the presence of Gateways. It can also help in providing Service guarantees for the VMs using these overlays with the help of underlay orchestration. \r
\r
-==== OVSDB to OpenFlow plugin mapping service\r
+===== OVSDB to OpenFlow plugin mapping service\r
The connect() of the ConnectionService would result in a Node that represents an ovsdb-server. The CreateBridgeDomain() Configuration on the above Node would result in creating an OVS bridge. This OVS Bridge is an OpenFlow Agent for the OpenDaylight OpenFlow plugin with its own Node represented as (example) OF|xxxx.yyyy.zzzz. \r
Without any help from the OVSDB plugin, the Node Mapping Service of the Controller platform would not be able to map the following: +\r
----\r
----\r
Without such mapping, it would be extremely difficult for the applications to manage and maintain such nodes. This Mapping Service provided by the OVSDB plugin would essentially help in providing more value added services to the orchestration layers that sit atop the Northbound APIs (such as OpenStack). \r
\r
-==== Inventory service\r
-\r
-Inventory Service provides a simple database of all the nodes managed and maintained by the OVSDB plugin on a given controller. For optimization purposes, it can also provide enhanced services to the OVSDB to OpenFlow mapping service by maintaining the following mapping owing to the static nature of this operation. +\r
-----\r
-{OVSDB_NODE + BRIDGE_IDENTFIER} <---> {OF_NODE}\r
-----\r
-=== OpenDaylight OVSDB Developer Getting Started Video Series\r
+==== OpenDaylight OVSDB Developer Getting Started Video Series\r
The video series were started to help developers bootstrap into OVSDB development.\r
\r
* http://www.youtube.com/watch?v=ieB645oCIPs[OpenDaylight OVSDB Developer Getting Started]\r
* http://www.youtube.com/watch?v=xgevyaQ12cg[OpenDaylight OVSDB Developer Getting Started - Java APIs]\r
* http://www.youtube.com/watch?v=NayuY6J-AMA[OpenDaylight OVSDB Developer Getting Started - OpenStack Integration OpenFlow v1.0]\r
\r
-==== Other developer tutorials\r
+===== Other developer tutorials\r
\r
+* https://docs.google.com/presentation/d/1KIuNDuUJGGEV37Zk9yzx9OSnWExt4iD2Z7afycFLf_I/edit?usp=sharing[OVSDB NetVirt Tutorial]\r
+* https://www.youtube.com/watch?v=2axNKHvt5MY&list=PL8F5jrwEpGAiJG252ShQudYeodGSsks2l&index=43[Youtube of OVSDB NetVirt tutorial]\r
* https://wiki.opendaylight.org/view/OVSDB:OVSDB_OpenStack_Guide[OVSDB OpenFlow v1.3 Neutron ML2 Integration]\r
* http://networkstatic.net/getting-started-ovsdb/[Open vSwitch Database Table Explanations and Simple Jackson Tutorial]\r
\r
-=== OVSDB integration: New features\r
-==== Schema independent library\r
+==== OVSDB integration: New features\r
+===== Schema independent library\r
The OVS connection is a node which can have multiple databases. Each database is represented by a schema. A single connection can have multiple schemas.\r
OSVDB supports multiple schemas. Currently, these are two schemas available in the\r
OVSDB, but there is no restriction on the number of schemas. Owing to the Northbound v3 API, no code changes in ODL are needed for supporting additional schemas.\r
* openvswitch : Schema wrapper that represents http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf\r
* hardwarevtep: Schema wrapper that represents http://openvswitch.org/docs/vtep.5.pdf\r
\r
-==== Northbound API v3\r
-OVSDB supports Northbound API v3 which allows external access to all ODL OVSDB databases or schemas.\r
-The general syntax for that API follows this format:\r
-----\r
-http://{{controllerHost}}:{{controllerPort}}/ovsdb/nb/v3/node/{{OVS|HOST}}/database\r
----- \r
-For more information on Northbound REST API see: +\r
-https://docs.google.com/spreadsheets/d/11Rp5KSNTcrvOD4HadCnXDCUdJq_TZ5RgoQ6qSHf_xkw/edit?usp=sharing\r
- \r
-The key differences between Northbound API v2 and v3 include: +\r
- \r
-* Support for schema independence\r
-* Formal restful style API, which includes consistent URL navigation for nodes and tables\r
-* Ability to create interfaces and ports within a single rest call. To allow that, the JSON in the body can include distinct parts like interface and port\r
-\r
-==== Port security\r
+===== Port security\r
Based on the fact that security rules can be obtained from a port object, OVSDB can apply Open Flow rules. These rules will match on what types of traffic the Openstack tenant VM is allowed to use.\r
\r
Support for security groups is very experimental. There are limitations in determining the state of flows in the Open vSwitch. See http://%20https//www.youtube.com/watch?v=DSop2uLJZS8[Open vSwitch and the Intelligent Edge] from Justin Petit for a deep dive into the challenges we faced creating a flow based port security implementation. The current set of rules that will be installed only supports filtering of the TCP protocol. This is because via a Nicira TCP_Flag read we can match on a flows TCP_SYN flag, and permit or deny the flow based on the Neutron port security rules. If rules are requested for ICMP and UDP, they are ignored until greater visibility from the Linux kernel is available as outlined in the OpenStack presentation mentioned earlier. \r
\r
The current rules are applied on the basis of the following attributes: ingress/egress, tcp protocol, port range, and prefix.\r
\r
-===== OpenStack workflow\r
-\r
+====== OpenStack workflow\r
. Create a stack.\r
. Add the network and subnet. \r
. Add the Security Group and Rules.\r
--nic net-id=$(neutron net-list | grep 'vxlan2' | awk '{print $2}') vxlan2 \\r
--security-groups group1\r
----\r
-===== Examples: Rules supported\r
+====== Examples: Rules supported\r
----\r
neutron security-group-create group2 --description "Group 2"\r
neutron security-group-rule-create --direction ingress --protocol tcp --port-range-min 54 group2\r
----\r
*Reference gist*:https://gist.github.com/anonymous/1543a410d57f491352c8[Gist]\r
\r
-===== Security group rules supported in ODL \r
+====== Security group rules supported in ODL \r
The following rules formata are supported in the current implementation. The direction (ingress/egress) is always expected. Rules are implemented such that tcp-syn packets that do not satisfy the rules are dropped.\r
[cols="3", width="60%"]\r
|===\r
|TCP |x |Any\r
|TCP |Any |Any\r
|===\r
-===== Limitations\r
\r
-* Soon, conntrack will be supported by OVS. Until then, TCP flags are used as way of checking for connection state. Specifically, that is done by matching on the TCP-SYN flag. \r
+====== Limitations\r
+* Soon, conntrack will be supported by OVS. Until then, TCP flags are used as way of checking for connection state. Specifically, that is done by matching on the TCP-SYN flag.\r
* The param '--port-range-max' in 'security-group-rule-create' is not used until the implementation uses contrack. \r
* No UDP/ICMP specific match support is provided.\r
* No IPv6 support is provided.\r
\r
-==== L3 forwarding\r
+===== L3 forwarding\r
OVSDB extends support for the usage of an ODL-Neutron-driver so that OVSDB can configure OF 1.3 rules to route IPv4 packets. The driver eliminates the need for the router of the L3 Agent. In order to accomplish that, OVS 2.1 or a newer version is required.\r
OVSDB also supports inbound/outbound NAT, floating IPs.\r
\r
-===== Starting OVSDB and OpenStack\r
-\r
+====== Starting OVSDB and OpenStack\r
. Build or download OVSDB distribution, as mentioned in <<ovsdbBuildSteps,building a Karaf feature section>>.\r
. http://docs.vagrantup.com/v2/installation/index.html[Install Vagrant].\r
\r
vagrant ssh devstack-compute-1\r
cd ~/devstack && ./stack.sh\r
----\r
-===== OpenStack workflow\r
\r
+====== OpenStack workflow\r
.Sample workflow\r
image::L3FwdSample.png[height=250]\r
\r
--key-name demo_key host20\r
----\r
\r
-===== Limitations\r
-\r
-* To use this feature, you need OVS 2.1 or newer version. \r
+====== Limitations\r
+* To use this feature, you need OVS 2.1 or newer version.\r
* Owing to OF limitations, icmp responses due to routing failures, like ttl expired or host unreacheable, are not generated.\r
* The MAC address of the default route is not automatically mapped. In order to route to L3 destinations outside the networks of the tenant, the manual configuration of the default route is necessary. To provide the MAC address of the default route, use ovsdb.l3gateway.mac in file configuration/config.ini ; \r
* This feature is Tech preview, which depends on later versions of OpenStack to be used without the provided neutron-driver. \r
* odl-neutron-driver: https://github.com/dave-tucker/odl-neutron-drivers\r
* OF rules example: http://dtucker.co.uk/hack/building-a-router-with-openvswitch.html\r
\r
-==== LBaaS\r
+===== LBaaS\r
Load-Balancing-as-a-Service (LBaaS) creates an Open vSwitch powered L3-L4 stateless load-balancer in a virtualized network environment so that individual TCP connections destined to a designated virtual IP (VIP) are sent to the appropriate servers (that is to say, serving app VMs). The load-balancer works in a session-preserving, proactive manner without involving the controller during flow setup.\r
\r
A Neutron northbound interface is provided to create a VIP which will map to a pool of servers (that is to say, members) within a subnet. The pools consist of members identified by an IP address. The goal is to closely match the API to the OpenStack LBaaS v2 API: http://docs.openstack.org/api/openstack-network/2.0/content/lbaas_ext.html.\r
\r
-===== Creating an OpenStack workflow\r
+====== Creating an OpenStack workflow\r
. Create a subnet. \r
. Create a floating VIP 'A' that maps to a private VIP 'B'. \r
. Create a Loadbalancer pool 'X'. \r
neutron lb-vip-create --name http-vip --protocol-port 80 --protocol HTTP --subnet-id XYZ http-pool\r
----\r
\r
-===== Implementation\r
+====== Implementation\r
\r
The current implementation of the proactive stateless load-balancer was made using "multipath" action in the Open vSwitch. The "multipath" action takes a max_link parameter value (which is same as the number of pool members) as input, and performs a hash of the fields to get a value between (0, max_link). The value of the hash is used as an index to select a pool member to handle that session. \r
\r
-==== Open vSwitch rules\r
-\r
-Assuming that table=20 contains all the rules to forward the traffic destined for a specific destination MAC address, the following are the rules needed to be programmed in the LBaaS service table=10. The programmed rules makes the translation from the VIP to a different pool member for every session. \r
+===== Open vSwitch rules\r
+Assuming that table=20 contains all the rules to forward the traffic destined for a specific destination MAC address, the following are the rules needed to be programmed in the LBaaS service table=10. The programmed rules makes the translation from the VIP to a different pool member for every session.\r
\r
* Proactive forward rules:\r
----\r
----\r
sudo ovs-ofctl -O OpenFlow13 add-flow s1 table=10,ip,tcp,tp_src=80,actions=mod_dl_src:00:00:00:00:00:05,mod_nw_src:10.0.0.5,goto_table:20\r
---- \r
-===== OVSDB project code\r
+\r
+====== OVSDB project code\r
The current implementation handles all neutron calls in the net-virt/LBaaSHandler.java code, and makes calls to the net-virt-providers/LoadBalancerService to program appropriate flowmods. The rules are updated whenever there is a change in the Neutron LBaaS settings. There is no cache of state kept in the net-virt or providers. \r
\r
-===== Limitations\r
+====== Limitations\r
Owing to the inflexibility of the multipath action, the existing LBaaS implementation comes with some limitations: \r
\r
* TCP, HTTP or HTTPS are supported protocols for the pool. (Caution: You can lose access to the members if you assign {Proto:TCP, Port:22} to LB) \r
-== OVSDB Service Function Chaining Developer Guide
+=== OVSDB Service Function Chaining Developer Guide
-=== Overview
+==== Overview
+The OVSDB NetVirtSfc provides a classification and traffic steering component when integrated with OpenStack. Please refer to the Service Function Chaining project for the theory and programming of service chains.
-TBD
+==== Installing the NetVirt SFC Feature
+Install the odl-ovsdb-sfc feature. The feature will also ensure that the odl-ovsdb-openstack feature as well as the openflowplugin, neutron and sfc features are installed.
-=== OVSDB Hardware VTEP Architecture
+---
+feature:install odl-ovsdb-sfc-ui
+---
-TBD
+Verify the required features are installed:
+---
+opendaylight-user@root>feature:list -i | grep ovsdb
+
+odl-ovsdb-southbound-api | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: api
+odl-ovsdb-southbound-impl | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: impl
+odl-ovsdb-southbound-impl-rest | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: impl :: REST
+odl-ovsdb-southbound-impl-ui | 1.2.1-SNAPSHOT | x | odl-ovsdb-southbound-1.2.1-SNAPSHOT | OpenDaylight :: southbound :: impl :: UI
+odl-ovsdb-library | 1.2.1-SNAPSHOT | x | odl-ovsdb-library-1.2.1-SNAPSHOT | OpenDaylight :: library
+odl-ovsdb-openstack | 1.2.1-SNAPSHOT | x | ovsdb-1.2.1-SNAPSHOT | OpenDaylight :: OVSDB :: OpenStack Network Virtual
+odl-ovsdb-sfc-api | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc :: api
+odl-ovsdb-sfc | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc
+odl-ovsdb-sfc-rest | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc :: REST
+odl-ovsdb-sfc-ui | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc :: UI
+
+opendaylight-user@root>feature:list -i | grep sfc
+odl-sfc-model | 0.2.0-SNAPSHOT | x | odl-sfc-0.2.0-SNAPSHOT | OpenDaylight :: sfc :: Model
+odl-sfc-provider | 0.2.0-SNAPSHOT | x | odl-sfc-0.2.0-SNAPSHOT | OpenDaylight :: sfc :: Provider
+odl-sfc-provider-rest | 0.2.0-SNAPSHOT | x | odl-sfc-0.2.0-SNAPSHOT | OpenDaylight :: sfc :: Provider
+odl-sfc-ovs | 0.2.0-SNAPSHOT | x | odl-sfc-0.2.0-SNAPSHOT | OpenDaylight :: OpenvSwitch
+odl-sfcofl2 | 0.2.0-SNAPSHOT | x | odl-sfc-0.2.0-SNAPSHOT | OpenDaylight :: sfcofl2
+odl-ovsdb-sfc-test | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-test1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc-test
+odl-ovsdb-sfc-api | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc :: api
+odl-ovsdb-sfc | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc
+odl-ovsdb-sfc-rest | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc :: REST
+odl-ovsdb-sfc-ui | 1.2.1-SNAPSHOT | x | odl-ovsdb-sfc-1.2.1-SNAPSHOT | OpenDaylight :: ovsdb-sfc :: UI
+
+opendaylight-user@root>feature:list -i | grep neutron
+odl-neutron-service | 0.6.0-SNAPSHOT | x | odl-neutron-0.6.0-SNAPSHOT | OpenDaylight :: Neutron :: API
+odl-neutron-northbound-api | 0.6.0-SNAPSHOT | x | odl-neutron-0.6.0-SNAPSHOT | OpenDaylight :: Neutron :: Northbound
+odl-neutron-spi | 0.6.0-SNAPSHOT | x | odl-neutron-0.6.0-SNAPSHOT | OpenDaylight :: Neutron :: API
+odl-neutron-transcriber | 0.6.0-SNAPSHOT | x | odl-neutron-0.6.0-SNAPSHOT | OpenDaylight :: Neutron :: Implementation
+---
+
+==== OVSDB NetVirt Service Function Chaining Example
+The architecture within OpenDaylight can be seen in the following figure:
+
+.OpenDaylight OVSDB NetVirt SFC Architecture
+image::ovsdb/ODL_SFC_Architecture.png[]
+
+Tacker is a Virtual Network Functions Manager that is responsible for orchestrating the Service Function Chaining. Tacker is responsible for generating templates for Virtual Network Functions for OpenStack to instantiate the Service Functions. Tacker also uses the RESTCONF interfaces of OpenDaylight to create the Service Function Chains.
+
+==== Classification
+OVSDB NetVirt SFC implements the classification for the chains. The classification steers traffic from the tenant overlay to the chain overlay and back to the tenant overlay.
+
+An Access Control List used by NetVirtSFC to create the classifier is shown below. This is an example of classifying HTTP traffic using the tcp port 80. In this example the user would have created a Service Function Chain with the name "http-sfc" as well as all the associated Service Functions and Service Function Forwarders for the chain.
+
+---
+http://localhost:8181/restconf/config/ietf-access-control-list:access-lists
+
+{
+ "access-lists": {
+ "acl": [
+ {
+ "acl-name": "http-acl",
+ "access-list-entries": {
+ "ace": [
+ {
+ "rule-name": "http-rule",
+ "matches": {
+ "source-port-range": {
+ "lower-port": 0,
+ "upper-port": 0
+ },
+ "protocol": 6,
+ "destination-port-range": {
+ "lower-port": 80,
+ "upper-port": 80
+ }
+ },
+ "actions": {
+ "netvirt-sfc-acl:sfc-name": "http-sfc"
+ }
+ }
+ ]
+ }
+ }
+ ]
+ }
+}
+---
+
+When the chain is rendered using the Rendered Service Path RPC, NetvirtSfc will add the classification flows. The classification flows are shown below. The list shown has been modified to remove the NetVirt tenant overlay flows. The classification flow is identified with the cookie: 0x1110010000040255. The 6th digit of the cookie identifies the flow type as the classifier. The last 8 digits identify the chain with the first four digits indicating the NSH NSP and the last four digits identifying the NSH NSI. In this case the chain is identified with an NSP of 4 and the NSI is 255 to indicate the beginning of the chain.
+
+---
+sudo ovs-ofctl --protocol=OpenFlow13 dump-flows br-int
+OFPST_FLOW reply (OF1.3) (xid=0x2):
+ cookie=0x0, duration=17.157s, table=0, n_packets=0, n_bytes=0, priority=6 actions=goto_table:1
+ cookie=0x14, duration=10.692s, table=0, n_packets=0, n_bytes=0, priority=400,udp,in_port=4,tp_dst=6633 actions=LOCAL
+ cookie=0x0, duration=17.134s, table=0, n_packets=0, n_bytes=0, dl_type=0x88cc actions=CONTROLLER:65535
+ cookie=0x14, duration=10.717s, table=0, n_packets=0, n_bytes=0, priority=350,nsp=4 actions=goto_table:152
+ cookie=0x14, duration=10.688s, table=0, n_packets=0, n_bytes=0, priority=400,udp,nw_dst=10.2.1.1,tp_dst=6633 actions=output:4
+ cookie=0x0, duration=17.157s, table=1, n_packets=0, n_bytes=0, priority=0 actions=goto_table:11
+ cookie=0x1110070000040254, duration=10.608s, table=1, n_packets=0, n_bytes=0, priority=40000,reg0=0x1,nsp=4,nsi=254,in_port=1 actions=goto_table:21
+ cookie=0x0, duration=17.157s, table=11, n_packets=0, n_bytes=0, priority=0 actions=goto_table:21
+ cookie=0x1110060000040254, duration=10.625s, table=11, n_packets=0, n_bytes=0, nsp=4,nsi=254,in_port=4 actions=load:0x1->NXM_NX_REG0[],move:NXM_NX_NSH_C2[]->NXM_NX_TUN_ID[0..31],resubmit(1,1)
+ cookie=0x1110010000040255, duration=10.615s, table=11, n_packets=0, n_bytes=0, tcp,reg0=0x1,tp_dst=80 actions=move:NXM_NX_TUN_ID[0..31]->NXM_NX_NSH_C2[],set_nshc1:0xc0a83246,set_nsp:0x4,set_nsi:255,load:0xa020101->NXM_NX_TUN_IPV4_DST[],load:0x4->NXM_NX_TUN_ID[0..31],resubmit(,0)
+ cookie=0x0, duration=17.157s, table=21, n_packets=0, n_bytes=0, priority=0 actions=goto_table:31
+ cookie=0x1110040000000000, duration=10.765s, table=21, n_packets=0, n_bytes=0, priority=1024,arp,in_port=LOCAL,arp_tpa=10.2.1.1,arp_op=1 actions=move:NXM_OF_ETH_SRC[]->NXM_OF_ETH_DST[],set_field:f6:00:00:0f:00:01->eth_src,load:0x2->NXM_OF_ARP_OP[],move:NXM_NX_ARP_SHA[]->NXM_NX_ARP_THA[],move:NXM_OF_ARP_SPA[]->NXM_OF_ARP_TPA[],load:0xf600000f0001->NXM_NX_ARP_SHA[],load:0xa020101->NXM_OF_ARP_SPA[],IN_PORT
+ cookie=0x0, duration=17.157s, table=31, n_packets=0, n_bytes=0, priority=0 actions=goto_table:41
+ cookie=0x0, duration=17.157s, table=41, n_packets=0, n_bytes=0, priority=0 actions=goto_table:51
+ cookie=0x0, duration=17.157s, table=51, n_packets=0, n_bytes=0, priority=0 actions=goto_table:61
+ cookie=0x0, duration=17.142s, table=61, n_packets=0, n_bytes=0, priority=0 actions=goto_table:71
+ cookie=0x0, duration=17.140s, table=71, n_packets=0, n_bytes=0, priority=0 actions=goto_table:81
+ cookie=0x0, duration=17.116s, table=81, n_packets=0, n_bytes=0, priority=0 actions=goto_table:91
+ cookie=0x0, duration=17.116s, table=91, n_packets=0, n_bytes=0, priority=0 actions=goto_table:101
+ cookie=0x0, duration=17.107s, table=101, n_packets=0, n_bytes=0, priority=0 actions=goto_table:111
+ cookie=0x0, duration=17.083s, table=111, n_packets=0, n_bytes=0, priority=0 actions=drop
+ cookie=0x14, duration=11.042s, table=150, n_packets=0, n_bytes=0, priority=5 actions=goto_table:151
+ cookie=0x14, duration=11.027s, table=151, n_packets=0, n_bytes=0, priority=5 actions=goto_table:152
+ cookie=0x14, duration=11.010s, table=152, n_packets=0, n_bytes=0, priority=5 actions=goto_table:158
+ cookie=0x14, duration=10.668s, table=152, n_packets=0, n_bytes=0, priority=650,nsp=4,nsi=255 actions=load:0xa020101->NXM_NX_TUN_IPV4_DST[],goto_table:158
+ cookie=0x14, duration=10.995s, table=158, n_packets=0, n_bytes=0, priority=5 actions=drop
+ cookie=0xba5eba11ba5eba11, duration=10.645s, table=158, n_packets=0, n_bytes=0, priority=751,nsp=4,nsi=255,in_port=4 actions=move:NXM_NX_NSH_C1[]->NXM_NX_NSH_C1[],move:NXM_NX_NSH_C2[]->NXM_NX_NSH_C2[],move:NXM_NX_TUN_ID[0..31]->NXM_NX_TUN_ID[0..31],IN_PORT
+ cookie=0xba5eba11ba5eba11, duration=10.590s, table=158, n_packets=0, n_bytes=0, priority=751,nsp=4,nsi=254,in_port=4 actions=move:NXM_NX_NSI[]->NXM_NX_NSI[],move:NXM_NX_NSP[]->NXM_NX_NSP[],move:NXM_NX_NSH_C1[]->NXM_NX_TUN_IPV4_DST[],move:NXM_NX_NSH_C2[]->NXM_NX_TUN_ID[0..31],IN_PORT
+ cookie=0xba5eba11ba5eba11, duration=10.640s, table=158, n_packets=0, n_bytes=0, priority=750,nsp=4,nsi=255 actions=move:NXM_NX_NSH_C1[]->NXM_NX_NSH_C1[],move:NXM_NX_NSH_C2[]->NXM_NX_NSH_C2[],move:NXM_NX_TUN_ID[0..31]->NXM_NX_TUN_ID[0..31],output:4
+ cookie=0xba5eba11ba5eba11, duration=10.571s, table=158, n_packets=0, n_bytes=0, priority=761,nsp=4,nsi=254,nshc1=3232248390,in_port=4 actions=move:NXM_NX_NSI[]->NXM_NX_NSI[],move:NXM_NX_NSP[]->NXM_NX_NSP[],move:NXM_NX_NSH_C1[]->NXM_NX_TUN_IPV4_DST[],move:NXM_NX_NSH_C2[]->NXM_NX_TUN_ID[0..31],set_nshc1:0,resubmit(,11)
+---
+
+==== Configuration
+Some configuration is required due to application coexistence for the OpenFlow programming. The SFC project programs flows for the SFC overlay and NetVirt programs flows for the tenant overlay. Coexistence is achieved by each application owning a unique set of tables and providing a simple handoff between the tables.
+
+First configure NetVirt to use table 1 as it's starting table:
+
+---
+http://localhost:8181/restconf/config/netvirt-providers-config:netvirt-providers-config
+
+{
+ "netvirt-providers-config": {
+ "table-offset": 1
+ }
+}
+---
+
+Next configure SFC to start at table 150 and configure the table handoff. The configuration starts SFC at table 150 and sets the handoff to table 11 which is the NetVirt SFC classification table.
+
+---
+http://localhost:8181/restconf/config/sfc-of-renderer:sfc-of-renderer-config
+
+{
+ "sfc-of-renderer-config": {
+ "sfc-of-app-egress-table-offset": 11,
+ "sfc-of-table-offset": 150
+ }
+}
+---
\ No newline at end of file
-== OVSDB MD-SAL Southbound Plugin Developer Guide
+=== OVSDB MD-SAL Southbound Plugin Developer Guide
-=== Overview
+==== Overview
The Open vSwitch Database (OVSDB) Model Driven Service Abstraction Layer
-(MD-SAL) Southbound plugin provides an MD-SAL based interface to
+(MD-SAL) Southbound Plugin provides an MD-SAL based interface to
Open vSwitch systems. This is done by augmenting the MD-SAL topology node with
a YANG model which replicates some (but not all) of the Open vSwitch schema.
-=== OVSDB MD-SAL Southbound Plugin Architecture and Operation
+==== OVSDB MD-SAL Southbound Plugin Architecture and Operation
The architecture and operation of the OVSDB MD-SAL Southbound plugin is
illustrated in the following set of diagrams.
-==== Connecting to an OVSDB Node
+===== Connecting to an OVSDB Node
An OVSDB node is a system which is running the OVS software and is capable of
-being managed by an OVSDB Manager. The OVSDB MD-SAL Southbound plugin in
+being managed by an OVSDB manager. The OVSDB MD-SAL Southbound plugin in
OpenDaylight is capable of operating as an OVSDB manager. Depending on the
configuration of the OVSDB node, the connection of the OVSDB manager can
be active or passive.
-===== Active OVSDB Node Manager Workflow
+====== Active OVSDB Node Manager Workflow
An active OVSDB node manager connection is made when OpenDaylight initiates the
connection to the OVSDB node. In order for this to work, you must configure the
OVSDB node to listen on a TCP port for the connection (i.e.
any updates made to the OVSDB databases on the OVSDB node.
-===== Passive OVSDB Node Manager Workflow
+====== Passive OVSDB Node Manager Workflow
A passive OVSDB node connection to OpenDaylight is made when the OVSDB node
initiates the connection to OpenDaylight. In order for this to work, you must
configure the OVSDB node to connect to the IP address and OVSDB port on which
construct a monitor request which causes the OVSDB node to send back
any updates which have been made to the OVSDB databases on the OVSDB node.
-==== OVSDB Node ID in the Southbound Operational MD-SAL
+===== OVSDB Node ID in the Southbound Operational MD-SAL
When OpenDaylight initiates an active connection to an OVSDB node, it
writes an external-id to the Open_vSwitch table on the OVSDB node. The
external-id is an OpenDaylight instance identifier which identifies the
$ sudo ovs-vsctl remove open_vswitch . external-id "opendaylight-iid"
-==== OVSDB Changes by using OVSDB Southbound Config MD-SAL
+===== OVSDB Changes by using OVSDB Southbound Config MD-SAL
After the connection has been made to an OVSDB node, you can make changes to the
OVSDB node by using the OVSDB Southbound Config MD-SAL. You can
make CRUD operations by using the RESTCONF interface or by a plugin
-using the MD-SAL APIs. The following diagram illustrates the highlevel flow of
+using the MD-SAL APIs. The following diagram illustrates the high-level flow of
events.
.OVSDB Changes by using the Southbound Config MD-SAL
into corresponding changes made to the OVSDB Southbound Operational
MD-SAL data store.
-==== Detecting changes in OVSDB coming from outside OpenDaylight
+===== Detecting changes in OVSDB coming from outside OpenDaylight
Changes to the OVSDB nodes database may also occur independently of OpenDaylight.
OpenDaylight also receives notifications for these events and updates the
Southbound operational MD-SAL. The following diagram illustrates the sequence
// Discussion of how the OpenFlow controller node is associated with the OVSDB
// southbound model
-==== OVSDB Model
+===== OVSDB Model
The OVSDB Southbound MD-SAL operates using a YANG model which is based on the
abstract topology node model found in the
https://github.com/opendaylight/yangtools/blob/stable/lithium/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang[network topology model].
* *list port-other-configs* - a list of the key/value pairs in the port table other_config column for this port
* *list interface-other-configs* - a list of the key/value pairs in the interface table other_config column for this interface
-=== Examples of OVSDB Southbound MD-SAL API
+==== Examples of OVSDB Southbound MD-SAL API
-==== Connect to an OVSDB Node
+===== Connect to an OVSDB Node
This example RESTCONF command adds an OVSDB node object to the OVSDB
Southbound configuration data store and attempts to connect to the OVSDB host
located at the IP address 10.11.12.1 on TCP port 6640.
]
}
-==== Query the OVSDB Southbound Configuration MD-SAL
+===== Query the OVSDB Southbound Configuration MD-SAL
Following on from the previous example, if the OVSDB Southbound configuration
MD-SAL is queried, the RESTCONF command and the resulting reply is similar
to the following example.
// ==== Delete examples
// TBD
-=== Reference Documentation
+==== Reference Documentation
http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf[Openvswitch schema]
+++ /dev/null
-== Reservation Developer Guide
-
-=== Overview
-The Reservation Project provides a model extension that allows for realisation of
-time based constraints in Intents or Policy work.
-
-NOTE: To be clear the target audience for this guide is a developer who
-will be _using_ the feature to build something separate, but _not_
-somebody who will be developing code for this feature itself.
-
-=== Reservation Project Architecture
-TODO: provide Reservation architecture when we have a better idea what the
-final (at least for Lithium) model will look like.
-
-=== Reservation Model
-TODO: Describe the agreed-upon model and the thus the generated APIs.
-
-=== API Reference Documentation
-TODO: Provide links to to how to get to the RESTCONF APIdoc and to the
-generated Javadoc from the YANG generated Java code.
+++ /dev/null
-== TCPMD5 Developer Guide
-
-=== Overview
-
-The TCPMD5 project delivers the support for providing access to MD5 Signature
-Option on operating systems which support it in their TCP stack. The
-implementation is compliant with link:http://tools.ietf.org/html/rfc2385[RFC-2385].
-
-The project is available from the tcpmd5 repository. It is split into:
-
-tcpmd5-api
-
-tcpmd5-jni
-
-tcpmd5-nio
-
-tcpmd5-netty
-
-tcpmd5-controller-config
-
-tcpmd5-feature
-
-=== TCPMD5 Architecture
-
-This project defines a new TCP option for carrying an MD5 digest
-in a TCP segment. This digest acts like a signature for that segment,
-incorporating information known only to the connection end points.
-
-=== Key APIs and Interfaces
-
-As this project is fairly small, it provides only one feature that installs and
-provides all APIs and implementations for this project.
-
-==== tcpmd5-api
-
-Defines the basic API and a dummy implementation.
-
-==== tcpmd5-jni
-
-Contains the JNI implementation and its Java binding. The core of the artifact
-is NativeKeyAccess.java, which is the Java frontend and binding class. It
-defines the two native methods, setChannelKey0() and isClassSupported0(). These
-are implemented in tcpmd5_jni.c. Individual instances are then provided by
-NativeKeyAccessFactory, which runs basic sanity tests before allowing itself
-being instantiated.
-
-==== tcpmd5-nio
-
-Contains the code to bridge the JNI component with java.nio package,
-specifically ServerSocketChannel, SocketChannel and SocketOption classes.
-
-==== tcpmd5-netty
-
-Contains the code to bridge the JNI component with netty.io, by providing the
-appropriate SocketChannelFactory.
-
--- /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 than 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 - check for specific number
+* Specific string filtrator - checks for specific string
+* Range number filtrator - checks if specified field is higher than provided minimum and lower than provided maximum
+* Range string filtrator - checks if specified field is alphabetically greater than provided minimum and alphabetically lower than provided maximum
+* 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
-TopoProcessingProvider is entry point for Topology Processing Framework. It requires DataBroker instance. DataBroker is needed for listener registrations. There is TopologyRequestListener which listens on aggregated topology requests (placed into configuration datastore) and UnderlayTopologyListeners which listen on underlay topology data changes (made in operational datastore). TopologyRequestHandler saves toporequest data and provides method for translating path to the specified leaf. When a change in topology occurs, registered UnderlayTopologyListener processes this information for further aggregation and/or filtration. Finally, after overlay topology is created, it is passed to TopologyWriter, which writes this topology into operational datastore.
+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.
-=== Topology Processing Framework Architecture
-Contains of topoprocessing-api, topoprocessing-spi and topoprocessing-impl
-bundles.
-
-* topoprocessing-api - contains correlation definitions
-* topoprocessing-spi - entry point for topoprocessing service (start and close)
-* topoprocessing-impl - contains implemented handlers, listeners and aggregators
+=== Architecture
+include::odl-topoprocessing-architecture-dev.adoc[]
=== Aggregation and Filtration
+include::odl-topoprocessing-aggregation-filtration-dev.adoc[]
-==== Terminology
-We use the term Physical Node for nodes in the underlay and Logical Node for nodes in the overlay regardless of whether either is actually a physical network element.
-
-==== Introduction
-The Topology Processing Framework allows for the creation of aggregated topologies or filtered views of existing topologies. Currently aggregation and filtration of nodes is supported only for topologies augmenting the https://github.com/opendaylight/yangtools/blob/master/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang[topology YANG model]. When a request to build an aggregate or filtered topology is received, the framework creates one listener per underlay topology. Whenever any underlay topology changes, its listener is triggered the change is processed. Two types of correlations (functionalities) are currently supported:
-
-* Aggregation
-** Unification
-** Equality
-* Filtration
-** NodeIpFiltration
-
-==== Aggregation
-Aggregation is an operation which creates an aggregated node from two or more nodes in the underlay topology if the condition for doing so 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 nodes that the framework will check for equality.
-
-===== Create overlay node
-First, each new underlay node is inserted into proper topology (specifically into topology store structure). Once notified of the new node, the framework compares it (using the target field value) with all existing nodes in the specified underlay topologies and if the equality condition is fulfilled, a new overlay node is created containing pointers to all 'equal' underlay nodes.
-
-.Equality case
-In this case, if a node doesn't fulfill the equality condition with any other nodes, processing finishes after adding the node into topology store. It will stay there, for future use, ready to create aggregated node with a new underlay node, with which it would satisfy condition to create overlay node.
-
-.Unification case
-In this case, an overlay node is created for all underlay nodes, even those which don't fulfill the equality condition with any other nodes. This means than an overlay node is created for every underlay node, but for nodes which satisfy the equality condition, an aggregated node is created.
-
-===== Update node
-Processing of updated underlay nodes depends on whether the target field has been modified. If this it has been, then:
-
-* if the underlay node belonged to some overlay node, it is withdrawn from that node and then, if the condition of equality on target field is satisfied, it is inserted into another (possibly the same) overlay node.
-* if the node was a "singleton" node, it is put into overlay node, if the condition of equality is fulfilled on the new value of target field with some existing underlay node
-
-.Unification case
-Every underlay node belongs to some overlay node. Either with some other underlay nodes when they have the same value of target field or otherwise there is one underlay node in an overlay node.
-
-===== Remove node
-The underlay node is removed from appertaining topology store and from it's overlay node if it belongs to one.
-
-.Equality case
-If there is only one underlay node left in the overlay node, the overlay node is removed.
-
-.Unification case
-In this case, it is allowed to have one underlay node in overlay node. However if this node is removed from its overlay node, the overlay node is removed.
-
-==== Filtration
-Filtration is an operation which results in creation of overlay topology containing only nodes fulfilling condition set in the request for creating this topology.
-
-===== NodeIpFiltration
-This is filtration is based on IP addresses. If a node's IP address fulfills mask set in the value tag of the request, this node is put into resulting overlay topology.
-
-.Create node
-For a new node fulfilling IP address mask condition, this node is put into overlay node later written into datastore.
-
-.Update node
-If IP address of filtered node has changed to value still fulfilling the mask's condition, a new overlay node is created and this updated node is inserted there. If the new IP address does not fit within the mask, the overlay node is simply removed.
-
-.Remove node
-If underlay node is part of some overlay node, the overlay node is simply removed.
-
-=== Wrapper, RPC republishing, writing mechanism
-
-During the process of aggregation and filtration, overlay nodes (so called Logical Nodes) were created from underlay nodes (Physical Nodes). In TopologyManager, overlay nodes are put into wrapper. A wrapper is identified with unique ID and contains list of Logical Nodes. Wrappers are used to deal with transitivity of underlay nodes - which permits grouping of overlay nodes (into wrappers).
-
-.Class relationship
-image::topoprocessing/wrapper.png[width=500]
-
-PN1, PN2, PN3 = Physical Node
-
-LN1, LN2 = Logical Node
-
-==== RPC republishing
-All RPC underlay nodes are re-registered under their corresponding wrapper ID. RPCs of underlay nodes (belonging to an overlay node) are gathered, and registered under ID of their wrapper.
-
-===== RPC Call
-When RPC is called on overlay node, this call is delegated to it's underlay nodes, it means this RPC is called on all underlay nodes of this overlay node.
-
-==== Writing mechanism
-When a wrapper (containing overlay node(s) with it's underlay nodes(s)) is ready to be written into data store, it has to be converted into DOM format. After this translation is done, result is written into datastore. Physical nodes are stored as supporting-nodes.
-In order to use resources responsibly, writing 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.
-
-=== Classes relationships
-
-[1] TopologyRequestHandler instantiates TopologyWriter, TopologyManager. Then according to request initializes either TopologyAggregator or Topology filtrator.
-
-[2] It creates as many instances of UnderlayTopologyListener as there are underlay topologies
-
-[3] PhysicalNodes are created for relevant income nodes (those having node ID)
-
-[4a] Performs aggregation and creates Logical Nodes
-
-[4b] Performs filtration and creates Logical Nodes
-
-[5] Logical Nodes are put into wrapper
+=== Link Computation
+include::odl-topoprocessing-link-computation-dev.adoc[]
-[6] Wrapper is translated into adequate format and written into Datastore
+=== Wrapper, RPC Republishing, Writing Mechanism
+include::odl-topoprocessing-wrapper-rpc-writing-dev.adoc[]
-.Class relationship
-image::topoprocessing/TopologyRequestHandler_classesRelationship.png[width=500]
+=== Topology Rendering Guide - Inventory Rendering
+include::odl-topoprocessing-inventory-rendering-dev.adoc[]
=== Key APIs and Interfaces
-Basic Provider class is TopoProcessingProvider which provides startup and shutdown
-methods. Otherwise the framework communicates via requests and outputs stored
-in DataStores.
+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
-//Provide links to JavaDoc, REST API documentation, etc. [TBD]
+=== 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].
--- /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 calli 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 there 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-li odl-openflowplugin-nsf-model-li`
+
+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
+During the topology request processing, 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.
+++ /dev/null
-== Table Type Patterns
-
-IMPORTANT: This section assumes you have already downloaded the Karaf
- distribution of OpenDaylight Helium and followed the
- instructions in the Table Type Patterns section of the
- Installation guide. If not, do that first.
-
-=== Introduction
-
-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].
-// for reasons that baffle me, I cannot link to:
-// https://www.opennetworking.org/images/stories/downloads/sdn-resources/onf-specifications/openflow/OpenFlow%20Table%20Type%20Patterns%20v1.0.pdf
-// it renders it as a link to a file ignoring the https part
-
-==== Support in Helium
-In the Helium release, Table Type Patterns (TTPs) are exposed as a YANG
-model for TTPs themselves which can be loaded into the MD-SAL Data
-Store in three places:
-// link to the MD-SAL Data Store docs?
-
-. As one of a list of TTPs in the +opendaylight-ttps+ top-level
- container.
-. Attached to a +node+ in the +opendaylight-inventory+ model as an
- +active_ttp+ via the +ttp-capable-node+ augmentation.
-. Attached to a +node+ in the +opendaylight-inventory+ model as one of
- a list of +supported_ttps+ via the +ttp-capable-node+ augmentation.
-// link to the inventory docs somehow?
-
-Each of these points can be accessed either through the RESTCONF-based
-REST APIs or via the Java interface to the MD-SAL Data Store. This
-discussion will focus on the REST APIs.
-
-[NOTE]
-===============================
-Developers who wish to use the Java interfaces are encouraged to to
-first read and understand using the MD-SAL Data Store's APIs including
-importing the appropriate bundles for to get models, dealing with
-transactions, and constructing instance identifiers.
-
-After that, it should be somewhat straightforward to translate the REST
-API calls here into appropriate instance identifiers which can be used
-in MD-SAL Data Store transactions.
-===============================
-
-=== Using The REST APIs
-
-As stated above there are 3 locations where a Table Type Patter 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>+
-===============================
-
-==== 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+.
-
-=== Limitations
-
-==== Differences between OpenDaylight TTP and ONF TTP
-
-The OpenDaylight YANG specification for TTPs differs from the ONF's
-specification in a few areas. These differences are due to limitations
-in the subsets of JSON that YANG schemas can be used to describe.
-
-* *+doc+ members must always be lists and cannot be just a string*
-
-For example, this is not allowed:
-
-----
-"doc": "The VLAN ID of a locally attached L2 subnet on a Router."
-----
-
-While this is:
-
-----
-"doc": ["The VLAN ID of a locally attached L2 subnet on a Router."]
-----
-
-[start=2]
-* *+table_map+ formats differ*
-
-In the ONF spec, the table_map looks like this
-
-----
-"table_map": {
- "ControlFrame": 0,
- "IngressVLAN": 1,
- "MacLearning": 2,
- "L2": 3
-},
-----
-
-In the ODL TTP YANG definition, it would instead look like this:
-
-----
-"table_map": [
- { "name": "ControlFrame", "number": 0 },
- { "name": "IngressVLAN", "number": 1 },
- { "name": "MacLearning", "number": 2 },
- { "name": "L2", "number": 3 },
-],
-----
-
-[start=3]
-* *Limited meta member keywords*
-
-The meta member keywords (+all+, +one_or_more+, +zero_or_more+,
-+exactly_one+, and +zero_or_one+) are allowed anywhere in a TTP
-according to the ONF specification, but they are only allowed in
-specific locations in the ODL YANG schema. Specifically:
-
-.. +all+, +one_or_more+, and +zero_or_more+ are allowed in the +flow_mod_types+ member
-.. +exactly_one+ and +zero_or_one+ are allowed in the +match_set+ and
- +instruction_set+ members as well as in in lists of actions.
-
-[start=4]
-* *+flow_paths+ repeated table syntax differs*
-
-In the ONF TTP specification, the ability to repeat a table in a path
-traversal of the tables is done by having the table be a list
-containing the table name as a string. Like this:
-
-----
-"flow_paths": ["path": ["table1", ["table2"] ] ]
-----
-
-In the ODL YANG schema this is instead represented by moving the square
-brackets inside the string as follows:
-
-----
-flow_paths": ["path": ["table1", "[table2]" ] ]
-----
-
-[start=5]
-* *+priority+ and +priority_rank+ must be strings and can't be numbers.
-
-The +priority+ and +priority_rank+ members are allowed to be either
-strings or numbers in the ONF specification, but must be strings in the
-ODL YANG schema.
-
-* *Empty lists must be omitted*
-
-Lists like this:
-
-----
-"match_set": []
-----
-
-must instead be omitted from the TTP.
-
-==== Strictly Informational
-
-At this point in time the only operations available with TTPs are
-storing and retrieving TTPs from the data store in the three previously
-mentioned places.
-
-Additional features that make use of and populate this information are
-planned for future releases.
-
-==== Known issues
-
-. Strings containing some special characters result in REST calls
- returning a +400 Bad Request+ code. A string that contains both an
- opening angle bracket (<) and a colon (:) with the angle bracket
- appearing first is known to trigger this behavior.
-
-For example this is known to break RESTCONF:
-
-----
-"var": "<<group_entry_types:name>>"
-----
-
-While these two work
-
-----
-"var": "group_entry_types:name"
-----
-
-----
-"var": "<<group_entry_types/name>>"
-----
-== ALTO User Guide
+== ALTO User Guide ==
-=== Overview
-The ALTO project provides support for _Application Layer Traffic
-Optimization_ services defined in link:https://tools.ietf.org/html/rfc7285[RFC
-7285].
+=== Overview ===
-In the Lithium release, ALTO uses the YANG model described in
-link:https://tools.ietf.org/html/draft-shi-alto-yang-model-03[this draft].
+The ALTO project is aimed to provide support for *Application Layer
+Traffic Optimization* services defined in
+https://tools.ietf.org/html/rfc7285[RFC 7285] in OpenDaylight.
-=== ALTO Architecture
+This user guide will introduce the three basic services (namely
+`simple-ird`, `manual-maps` and `host-tracker`) which are implemented in
+the Beryllium release, and give instructions on how to configure them to
+provide corresponding ALTO services.
-There are three kinds of ALTO packages in OpenDaylight.
+=== How to Identify ALTO Resources ===
-. **Core**
-The **core** packages include:
-.. `alto-model`: Defines the YANG model of ALTO services in MD-SAL
-.. `service-api-rfc7285`: Defines interfaces for ALTO services in AD-SAL
-.. `alto-northbound`: Implements the RFC7285-compatible RESTful API
-. **Basic**
-The **basic** packages include:
-.. Basic implementations of ALTO services:
-... `alto-provider`: Implements the services defined in `alto-model`
-... `simple-impl`: Implements the services defined in `service-api-rfc7285`
-.. Utilities:
-... `alto-manager`: Provides a karaf command line tool to manipulate network
-maps and cost maps.
-. **Service**
-The **service** packages include:
-.. `alto-hosttracker`: Generates a network map, a corresponding cost map and
-the endpoint cost service based on <<_l2switch_user_guide, l2switch>>.
+Each ALTO resource can be uniquely identified by a tuple . For each
+resource, a _version-tag_ is used to support historical look-ups.
-=== Configuring ALTO
+The formats of _resource-id_ and _version-tag_ are defined in
+https://tools.ietf.org/html/rfc7285#section-10.2[section 10.2] and
+https://tools.ietf.org/html/rfc7285#section-10.3[section 10.3]
+respectively. The _context-id_ is not part of the protocol and we choose
+the same format as a _universal unique identifier_ (UUID) which is
+defined in http://tools.ietf.org/html/rfc4122[RFC 4122].
-There are three packages that require their own configuration files,
-including `alto-provider`, `alto-hosttracker` and `simple-impl`. However, the
-only configurable option is the type of the data broker in all three
-configuration files.
+A context is like a namespace for ALTO resources, which eliminates
+_resource-id_ collisions. For simplicity, we also provide a default
+context with the id **000000000000-0000-0000-0000-00000000**.
-=== Administering or Managing ALTO
+=== How to Use Simple IRD ===
-To enable ALTO, the features must be installed first.
+The simple IRD feature provides a simple _information resource
+directory_ (IRD) service defined in
+https://tools.ietf.org/html/rfc7285#section-9[RFC 7285].
+
+==== Install the Feature ====
+
+To enable simple IRD, run the following command in the karaf CLI:
[source,bash]
-karaf > feature:install odl-alto-provider
-karaf > feature:install odl-alto-manager
-karaf > feature:install odl-alto-northbound
-karaf > feature:install odl-alto-hosttracker
+karaf > feature:install odl-alto-simpleird
-==== Managing Data with RESTCONF
+After the feature is successfully installed, a special context will be
+created for all simple IRD resources. The id for this context can be
+seen by executing the following command in a terminal:
-After installing `odl-alto-provider` feature in karaf, it is possible to manage
-network-maps and cost-maps using RESTCONF. Take a look at all the operations
-provided by `alto-model` at the API service page which can be found at
-`http://localhost:8181/apidoc/explorer/index.html`.
+[source,bash]
+curl -X GET -u admin:admin http://localhost:8181/restconf/operational/alto-simple-ird:information/
+
+==== Create a new IRD ====
+
+To create a new IRD resource, two fields MUST be provided:
-With the example input below you can insert a network map into the data store,
-either by filling the form in the API doc page, or by using tools such as `curl`.
+* Field **instance-id**: the _resource-id_ of the IRD resource;
+* Field **entry-context**: the context-id for non-IRD entries managed by
+this IRD resource.
+
+Using the following script, one can create an empty IRD resource:
+
+[source,bash]
+#!/bin/bash
+# filename: ird-create
+INSTANCE_ID=$1
+if [ $2 ]; then
+ CONTEXT_ID=$2
+else
+ CONTEXT_ID="00000000-0000-0000-0000-000000000000"
+fi
+URL="`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$INSTANCE_ID"/[`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$INSTANCE_ID"/`]`"
+DATA=$(cat template \
+ | sed 's/\$1/'$CONTEXT_ID'/g' \
+ | sed 's/\$2/'$INSTANCE_ID'/g')
+curl -4 -D - -X PUT -u admin:admin \
+ -H "Content-Type: application/json" -d "$(echo $DATA)"\
+ $URL
+
+For example, the following command will create a new IRD named _ird_
+which can accept entries with the default context-id:
[source,bash]
-HOST_IP=localhost # IP address of the controller
-CREDENTIAL=admin:admin # username and password for authentication
-BASE_URL=$HOST_IP:8181/restconf/config
-SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
-RESOURCE_ID=test_odl # Should match the one in the input file
-curl -X PUT -H "content-type:application/yang.data+json" \
- -d @example-input.json -u $CREDENTIAL \
- http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
+$ ./ird-create ird 000000000000-0000-0000-0000-00000000
+
+And below is the what the template file looks like:
[source,json]
-include::example-input.json[]
+{
+ "ird-instance-configuration": {
+ "entry-context": "/alto-resourcepool:context[alto-resourcepool:context-id='$1']",
+ "instance-id": "$2"
+ }
+}
-[[read-restconf]]Use the following command to see the results:
+==== Remove an IRD ====
+
+To remove an existing IRD (and all the entries in it), one can use the
+following command in a terminal:
[source,bash]
-HOST_IP=localhost # IP address of the controller
-CREDENTIAL=admin:admin # username and password for authentication
-BASE_URL=$HOST_IP:8181/restconf/config
-SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
-RESOURCE_ID=test_odl
-curl -X GET -u $CREDENTIAL http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
+curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$INSTANCE_ID
+
+==== Add a new entry ====
+
+There are several ways to add entries to an IRD and in this section we
+introduce only the simplest method. Using the following script, one can
+add a new entry to the target IRD.
-Use `DELETE` method to remove the data from the data store.
+For each new entry, four parameters MUST be provided:
+
+* Parameter __ird-id__: the _resource-id_ of the target IRD;
+* Parameter __entry-id__: the _resource-id_ of the ALTO service to be
+added;
+* Parameter __context-id__: the _context-id_ of the ALTO service to be
+added, which MUST be identical to the target IRD's __entry-context__;
+* Parameter __location__: either a URI or a relative path to the ALTO
+service.
+
+The following script can be used to add one entry to the target IRD,
+where the relative path is used:
+
+[source,bash]
+#!/bin/bash
+# filename: ird-add-entry
+IRD_ID=$1
+ENTRY_ID=$2
+CONTEXT_ID=$3
+BASE_URL=$4
+URL="`http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/"$IRD_ID"/ird-configuration-entry/"$ENTRY_ID"/"
+DATA=$(cat template \
+ | sed 's/\$1/'$ENTRY_ID'/g' \
+ | sed 's/\$2/'$CONTEXT_ID'/g' \
+ | sed 's/\$3/'$BASE_URL'/g' )
+curl -4 -D - -X PUT -u admin:admin \
+ -H "Content-Type: application/json" -d "$(echo $DATA)" \
+ $URL
+
+For example, the following command will add a new resource named
+__networkmap__, whose context-id is the default context-id and the base
+URL is /alto/networkmap, to the IRD named __ird__:
[source,bash]
-HOST_IP=localhost # IP address of the controller
-CREDENTIAL=admin:admin # username and password for authentication
-BASE_URL=$HOST_IP:8181/restconf/config
-SERVICE_PATH=alto-service:resources/alto-service:network-maps/alto-service:network-map
-RESOURCE_ID=test_odl
-curl -X DELETE -H "content-type:application/yang.data+json" \
- -u $CREDENTIAL http://$BASE_URL/$SERVICE_PATH/$RESOURCE_ID
+$ ./ird-add-entry ird networkmap 000000000000-0000-0000-0000-00000000 /alto/networkmap
+
+And below is the template file:
+
+[source,json]
+{
+ "ird-configuration-entry": {
+ "entry-id": "$1",
+ "instance": "/alto-resourcepool:context[alto-resourcepool:context-id='$2']/alto-resourcepool:resource[alto-resourcepool:resource-id='$1']",
+ "path": "$3/$1"
+ }
+}
-==== Using `alto-manager`
+==== Remove an entry ====
-The `alto-manager` package provides a karaf command line tool which wraps up
-the functions described in the last section.
+To remove an entry from an IRD, one can use the following one-line
+command:
[source,bash]
-karaf > alto-create <type> <resource-file>
-karaf > alto-delete <type> <resource-id>
+curl -X DELETE -u admin:admin http://localhost:8181/restconf/config/alto-simple-ird:ird-instance-configuration/$IRD_ID/ird-configuration-entry/$ENTRY_ID/
-Currently only `network-map` and `cost-map` are supported. Also the resource
-files used in `alto-manager` follow the RFC7285-compatible format instead of
-RESTCONF format.
+=== How to Use Host-tracker-based ECS ===
-The following example shows how to use `alto-manager` to put a network map into
-the data store.
+As a real instance of ALTO services, *_alto-hosttracker_* reads data
+from *_l2switch_* and generates a network map with resource id
+*_hosttracker-network-map_* and a cost map with resource id
+*_hostracker-cost-map_*. It can only work with OpenFlow-enabled
+networks.
+
+After installing the *_odl-alto-hosttracker_* feature, the corresponding
+network map and cost map will be inserted into the data store.
+
+=== Managing Resource with `alto-resourcepool` ===
+
+After installing `odl-alto-release` feature in Karaf, `alto-resourcepool` feature
+will be installed automatically. And you can manage all resources in ALTO via
+RESTCONF APIs provided by `alto-resourcepool`.
+
+With the example bash script below you can get any resource infomation in a
+given context.
[source,bash]
-karaf > alto-create network-map example-rfc7285-networkmap.json
+#!/bin/bash
+RESOURCE_ID=$1
+if [ $2 ] ; then
+ CONTEXT_ID=$2
+else
+ CONTEXT_ID="00000000-0000-0000-0000-000000000000"
+fi
+URL="http://localhost:8181/restconf/operational/alto-resourcepool:context/"$CONTEXT_ID"/alto-resourcepool:resource/"$RESOURCE_ID
+curl -X GET -u admin:admin $URL | python -m json.tool | sed -n '/default-tag/p' | sed 's/.*:.*\"\(.*\)\".*/\1/g'
-[source,json]
-include::example-rfc7285-networkmap.json[]
+=== Manual Configuration ===
-==== Using `alto-hosttracker`
+==== Using RESTCONF API ====
-As a real instance of ALTO services, `alto-hosttracker` reads data from
-`l2switch` and generates a network map with resource id
-`hosttracker-network-map` and a cost map with resource id `hostracker-cost-map`.
-It can only work with OpenFlow-enabled networks.
+After installing `odl-alto-release` feature in Karaf, it is possible to manage
+network-maps and cost-maps using RESTCONF. Take a look at all the operations
+provided by `resource-config` at the API service page which can be found at
+`http://localhost:8181/apidoc/explorer/index.html`.
-After installing the `odl-alto-hosttracker` feature, the corresponding network
-map and cost map will be inserted into the data store. Follow the steps in
-<<read-restconf, how to read data with RESTCONF>> to see the contents.
+The easiest method to operate network-maps and cost-maps is to modify data broker
+via RESTCONF API directly.
+
+==== Using RPC ====
+
+The `resource-config` package also provides a query RPC to config the resources.
+You can CREATE, UPDATE and DELETE *network-maps* and *cost-maps* via query RPC.
+
+=== Use Case ===
+
+==== Server Selection ====
+
+One of the key use case for ALTO is server selection. For example, a client (with
+IP address 10.0.0.1) sends a data transferring request to Data Transferring Service
+(DTS). And there are three data replica servers (with IP address 10.60.0.1, 10.60.0.2
+and 10.60.0.3) which can response the request. In this case, DTS can send a query
+request to ALTO server to make server selection decision.
+
+Following is an example ALTO query:
+
+[source]
+POST /alto/endpointcost HTTP/1.1
+Host: localhost:8080
+Content-Type: application/alto-endpointcostparams+json
+Accept: application/alto-endpointcost+json,application/alto-error+json
+{
+ "cost-type": {
+ "cost-mode": "ordinal",
+ "cost-metric": "hopcount"
+ },
+ "endpoints": {
+ "srcs": [ "ipv4:10.0.0.1" ],
+ "dsts": [
+ "ipv4:10.60.0.1",
+ "ipv4:10.60.0.2",
+ "ipv4:10.60.0.3"
+ ]
+ }
+}
+++ /dev/null
-== Armoury
-This section describes how to use the Armoury feature in OpenDaylight
-and contains contains configuration, administration, and management
-sections for the feature.
-
-=== Overview
-Just as compute needs to make requests to the controller to get networking
-resources in order to provide its services, so too does the controller
-sometimes need to make requests of the workload manager to get compute
-resources and/or network function (NF) (physical or virtual) orchestration
-to provide its services.
-
-=== Armoury Architecture
-There are mainly three components :
-
-* *Armoury Catalog*
-A registry or catalog of the necessary information (images, metadata, templatized
-day 0 config, how to communicate with the NF, etc) to describe the NF to the
-workload manager and/or network function (NF) (physical or virtual) orchestration.
-
-* *Armoury Workload Manager*
-The most minimal possible API to allow applications to request that the workload
-manager start/stop/etc the NF and some information from the workload manager/nf
-orchestrator about the state of the NF.
-
-* *Armoury Driver Registry*
-Example Drivers to talk to various workload managers (OpenStack/Meseophere/Docker/
-Kubernetes/etc).
-
-=== Armoury Catalog
-The NF Catalog contains metadata describing a NF.
-
-==== Configuring Armoury Catalog
-TBD: Describe how to configure Armoury Catalog after installation.
-
-==== Administering Armoury Catalog
-TBD: Include related command reference or operations
-for using Armoury Catalog.
-
-=== Armoury Workload Manager
-The Workload Manager defines RPCs to manage instances.
-
-==== Configuring Armoury Workload Manager
-TBD: Describe how to configure Armoury Workload Manager after installation.
-
-==== Administering Armoury Workload Manager
-TBD: Include related command reference or operations
-for using Armoury Workload Manager.
-
-=== Armoury Driver Registry
-The Driver Registry Describes the driver that is used to talk with the
-workload manager (OpenStack/Meseophere/Docker/Kubernetes/etc).
-
-==== Configuring Armoury Driver Registry
-TBD: Describe how to configure Armoury Driver Registry.
-
-==== Administering Armoury Driver Registry
-TBD: Include related command reference or operations
-for using Driver Registry.
-
-=== Tutorials
-Below are tutorials for Armoury.
-
-==== Using Armoury Catalog
-TBD: State the purpose of tutorial
-
-===== Overview
-TBD: An overview of the Armoury Catalog tutorial
-
-===== Prerequisites
-TBD: Provide any prerequisite information, assumed knowledge, or environment
-required to execute the use case.
-
-===== Target Environment
-TBD: Include any topology requirement for the use case.
-
-===== Instructions
-TBD: Step by step procedure for using Armoury Catalog.
-
-==== Using Armoury Workload Manager
-TBD: State the purpose of tutorial
-
-===== Overview
-TBD: An overview of the Armoury Workload Manager tutorial
-
-===== Prerequisites
-TBD: Provide any prerequisite information, assumed knowledge, or environment
-required to execute the use case.
-
-===== Target Environment
-TBD: Include any topology requirement for the use case.
-
-===== Instructions
-TBD: Step by step procedure for using Armoury Workload Manager.
-
-==== Using Armoury Driver Registry
-TBD: State the purpose of tutorial
-
-===== Overview
-TBD: An overview of the Armoury Driver Registry tutorial
-
-===== Prerequisites
-TBD: Provide any prerequisite information, assumed knowledge, or environment
-required to execute the use case.
-
-===== Target Environment
-TBD: Include any topology requirement for the use case.
-
-===== Instructions
-TBD: Step by step procedure for using Armoury Driver Registry.
\ No newline at end of file
+++ /dev/null
-== BGP LS PCEP
-
-=== BGP LS
-
-OpenDaylight comes pre-configured in the installation. You can find it in the opendaylight/configuration/initial directory and it consists of two files:
-
-https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/31-bgp.xml[31-bgp.xml], which defines the basic parser and RIB support. Unless you need to add a new AFI/SAFI, you should keep this file as is. +
-
-https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/41-bgp-example.xml[41-bgp-example.xml], which contains a sample configuration which needs to be customized to your deployment.
-
-*Currently the configuration for BGP peer is ignored in the configuration, to prevent the client from starting with default configuration. Therefore the first step is to uncomment ALL the commented parts in this file.*
-
-. Adjust values for initial BGP Open message
-+
-
-[literal]
-<module>
- <type>prefix:rib-impl</type>
- <name>example-bgp-rib</name>
- <rib-id>example-bgp-rib</rib-id>
- <local-as>64496</local-as> // Our AS number, we use this in best path selection
- <bgp-id>192.0.2.2</bgp-id> // Our BGP identifier, we use this in best path selection
-
-. Specify IP address of your BGP speaker
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-peer
- </type>
- <name>example-bgp-peer</name>
- <host>192.0.2.1</host> // IP address or hostname of the speaker
- <holdtimer>180</holdtimer>
-
-You can also add more BGP peers with different instance name and hostname.
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-peer
- </type>
- <name>example-bgp-peer2</name>
- <host>192.0.2.2</host>
- <holdtimer>180</holdtimer>
-
-[start = 3]
-. Configure connection attributes (all in milliseconds)
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:reconnectstrategy">
- prefix:timed-reconnect-strategy
- </type>
- <name>example-reconnect-strategy</name>
- <min-sleep>1000</min-sleep> // Minimum sleep time in between reconnect tries
- <max-sleep>180000</max-sleep> // Maximum sleep time in between reconnect tries
- <sleep-factor>2.00</sleep-factor> // Power factor of the sleep time between reconnect tries
- <connect-time>5000</connect-time> // How long we should wait for the TCP connect attempt, overrides default connection timeout dictated by TCP retransmits
- <executor>
- <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">
- netty:netty-event-executor
- </type>
- <name>global-event-executor</name>
- </executor>
-</module>
-
-
-==== BGP speaker configuration +
-
-Previous entries addressed the configuration of a BGP connection initiated by ODL. ODL also supports BGP Speaker functionality and accepts incoming BGP connections.
-
-The configuration of BGP speaker is located in https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/41-bgp-example.xml[41-bgp-example.xml].
-
----------------------
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-peer-acceptor
- </type>
- <name>bgp-peer-server</name>
- <!--Default parameters-->
- <!--<binding-address>0.0.0.0</binding-address>-->
- <!--<binding-port>179</binding-port>-->
- <bgp-dispatcher>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-dispatcher
- </type>
- <name>global-bgp-dispatcher</name>
- </bgp-dispatcher>
- <!--Drops or accepts incoming BGP connection, every BGP Peer that should be accepted needs to be added to this registry-->
- <peer-registry>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-peer-registry
- </type>
- <name>global-bgp-peer-registry</name>
- </peer-registry>
-</module>
----------------------
-
-. Changing speaker configuration
-
-* Changing binding address: Uncomment tag binding-address and change the address to e.g. 127.0.0.1. The default binding address is 0.0.0.0.
-* Changing binding port: Uncomment tag binding-port and change the port to e.g. 1790. The default binding port is 179 as specified in BGP RFC.
-. Configuring incoming BGP connections
-
-By default, the *BGP speaker drops all BGP connections from unknown BGP peers*. The decision is made in component bgp-peer-registry that is injected into the speaker (The registry is configured in 31-bgp.xml).
-
-To add BGP Peer configuration into the registry, it is necessary to configure regular BGP peer just like in example in https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/41-bgp-example.xml[41-bgp-example.xml]. Notice that the BGP peer depends on the same _bgp-peer-registry as bgp-speaker_:
-[literal]
-
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-peer
- </type>
- <name>example-bgp-peer</name>
- <host>192.0.2.1</host>
- ...
- <peer-registry>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-peer-registry
- </type>
- <name>global-bgp-peer-registry</name>
- </peer-registry>
- ...
-</module>
-
-BGP peer registers itself into the registry, which allows incoming BGP connections handled by the _bgp-speaker_. (Config attribute _peer-registry_ is optional for now to preserve backwards compatibility). With this configuration, the connection to 192.0.2.1 is initiated by ODL but will also be accepted from 192.0.2.1. In case both connections are being established, only one of them will be preserved and the other will be dropped. The connection initiated from device with lower bgp id will be dropped by the registry.
-
-There is a way to configure the peer only for incoming connections (The connection will not be initiated by the ODL, ODL will only wait for incoming connection from the peer. The peer is identified by its IP address). To configure peer only for incoming connection add attribute _initiate-connection_ to peer configuration:
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-peer
- </type>
- <name>example-bgp-peer</name>
- <host>192.0.2.1</host> // IP address or hostname of the speaker
- <holdtimer>180</holdtimer>
- <initiate-connection>false</initiate-connection> // Connection will not be initiated by ODL
- ...
-</module>
-
-The attribute initiate-connection is optional with the default value set to *true*.
-
-*Application peer configuration* +
-
-Application peer is a special type of BGP peer. It has own BGP RIB. This RIB can be populated through RESTCONF.
-If ODL is set as BGP speaker, the changes are sent to other BGP clients as well. To properly configure application peer, add following lines to https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/41-bgp-example.xml[41-bgp-example.xml] and make appropriate changes.
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:bgp-application-peer
- </type>
- <name>example-bgp-peer-app</name>
- <bgp-id>10.1.9.9</bgp-id> <!-- Your local BGP-ID that will be used in BGP Best Path Selection algorithm -->
- <target-rib>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- prefix:rib-instance
- </type>
- <name>example-bgp-rib</name> <!-- RIB where the changes from application RIB should be propagated -->
- </target-rib>
- <application-rib-id>example-app-rib</application-rib-id> <!-- Your application RIB identifier -->
- <data-broker>
- <type xmlns:binding="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">
- binding:binding-async-data-broker
- </type>
- <name>binding-data-broker</name>
- </data-broker>
-</module>
-
-=== PCEP
-OpenDaylight is pre-configured with baseline PCEP configuration. The default shipped configuration will start a PCE server on port 4189.
-
-https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/32-pcep.xml[32-pcep.xml] - basic PCEP configuration, including session parameters
-https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/39-pcep-provider.xml[39-pcep-provider.xml] - configuration for PCEP provider
-
-==== Configure draft versions +
-
-There are already two extensions for PCEP:
-https://tools.ietf.org/html/draft-ietf-pce-stateful-pce-09[draft-ietf-pce-stateful-pce] - in versions 02 and 07
-https://tools.ietf.org/html/draft-ietf-pce-pce-initiated-lsp-01[draft-ietf-pce-pce-initiated-lsp] - versions crabbe-initiated-00 and ietf-initiated-00.
-
-NOTE: It is important to load the extensions with compatible versions because they extend each other. In this case crabbe-initiated-00 is compatible with stateful-02 and ietf-initiated-00 is compatible with stateful-07. Default configuration is to use newest versions of the drafts.
-
-Complete the following steps in order to get stateful02 PCEP connection running and synchronized.
-
-To use older version:
-. Switch commented code to ignore stateful-7 and ietf-initiated-00 versions in https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/32-pcep.xml[32-pcep.xml]:
-
-[literal]
- <!-- This block is draft-ietf-pce-stateful-pce-07 + draft-ietf-pce-inititated-pce-00 -->
- <!--extension>
- <type>pcepspi:extension</type>
- <name>pcep-parser-ietf-stateful07</name>
- </extension>
- <extension>
- <type>pcepspi:extension</type>
- <name>pcep-parser-ietf-initiated00</name>
- </extension-->
- <!-- This block is draft-ietf-pce-stateful-pce-02 + draft-crabbe-pce-inititated-pce-00 -->
-<extension>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <name>pcep-parser-ietf-stateful02</name>
-</extension>
-<extension>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <name>pcep-parser-crabbe-initiated00</name>
-</extension>
-
-. In the same file, make sure the proposal matches your chosen draft version. Change _stateful07-proposal_ to _stateful02-proposal_:
-
-[literal]
-
-<pcep-session-proposal-factory>
- <type>pcep:pcep-session-proposal-factory</type>
- <name>stateful02-proposal</name>
-</pcep-session-proposal-factory>
-
-. In https://jenkins.opendaylight.org/integration/view/Integration%20jobs/job/integration-master-project-centralized-integration/lastSuccessfulBuild/artifact/distributions/serviceprovider/target/distributions-serviceprovider-0.2.0-SNAPSHOT-osgipackage/opendaylight/configuration/initial/39-pcep-provider.xml[39-pcep-provider.xml], stateful-plugin also needs to match. Change _stateful07_ to _stateful02_:
-[literal]
-<stateful-plugin>
- <type>prefix:pcep-topology-stateful</type>
- <name>stateful02</name>
-</stateful-plugin>
-
-==== Configure PCEP segment routing
-http://tools.ietf.org/html/draft-sivabalan-pce-segment-routing-02[draft-sivabalan-pce-segment-routing-02] PCEP extension for Segment Routing
-
-PCEP Segment Routing initial configuration:
-https://jenkins.opendaylight.org/bgpcep/job/bgpcep-nightly/ws/pcep/controller-config/src/main/resources/initial/33-pcep-segment-routing.xml[33-pcep-segment-routing.xml] +
-
-* To use Segment Routing uncomment two commented blocks +
-
-* Activate parsers/serializes extension: +
-
-** Create _pcep-parser-segment-routing02_ instance
-** Reconfigure (inject into list of extensions) global-pcep-extensions
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:sr02:cfg">
- prefix:pcep-parser-segment-routing02
- </type>
- <name>pcep-parser-segment-routing02</name>
-</module>
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- prefix:pcep-extensions-impl
- </type>
- <name>global-pcep-extensions</name>
- <extension>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <name>pcep-parser-segment-routing02</name>
- </extension>
-</module>
-.
-.
-.
-<services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:pcepspi="urn:opendaylight:params:xml:ns:yang:controller:pcep:spi">
- pcepspi:extension
- </type>
- <instance>
- <name>pcep-parser-segment-routing02</name>
- <provider>/config/modules/module[name='pcep-parser-segment-routing02']/instance[name='pcep-parser-segment-routing02']</provider>
- </instance>
- </service>
-</services>
-
-* Advertise Segment Routing capability in Open Message:
-** Instantiate pcep-session-proposal-factory-sr02
-** Reconfigure _global-pcep-dispatcher_
-
-[literal]
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:sr02:cfg">
- prefix:pcep-session-proposal-factory-sr02
- </type>
- <name>pcep-session-proposal-factory-sr02</name>
-</module>
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
- prefix:pcep-dispatcher-impl
- </type>
- <name>global-pcep-dispatcher</name>
- <pcep-session-proposal-factory>
- <type xmlns:pcep="urn:opendaylight:params:xml:ns:yang:controller:pcep">
- pcep:pcep-session-proposal-factory
- </type>
- <name>pcep-session-proposal-factory-sr02</name>
- </pcep-session-proposal-factory>
-</module>
-.
-.
-.
-<services xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <service>
- <type xmlns:pcep="urn:opendaylight:params:xml:ns:yang:controller:pcep">
- pcep:pcep-session-proposal-factory
- </type>
- <instance>
- <name>pcep-session-proposal-factory-sr02</name>
- <provider>/config/modules/module[name='pcep-session-proposal-factory-sr02']/instance[name='pcep-session-proposal-factory-sr02']</provider>
- </instance>
- </service>
-</services>
</affiliation>
</author>
<copyright>
- <year>2015</year>
+ <year>2016</year>
<holder>Linux Foundation</holder>
</copyright>
- <releaseinfo>Beryllium</releaseinfo>
+ <releaseinfo>Boron</releaseinfo>
<productname>OpenDaylight</productname>
<pubdate></pubdate>
<legalnotice role="license">
include::aaa/aaa.adoc[AAA]
-include::armoury/odl-armoury-user.adoc[ARMOURY]
-
include::bgpcep/odl-bgpcep-bgp-all-user.adoc[BGP]
include::bgpcep/odl-bgpcep-bmp-user.adoc[BMP]
include::capwap/capwap-user.adoc[CAPWAP]
+include::cardinal/odl-cardinal-user.adoc[]
+
include::centinel/centinel-user-guide.adoc[]
include::didm/didm-user.adoc[]
include::lfm/lispflowmapping-msmr-user.adoc[LISP flow mapping]
-include::messaging4transport/messaging4transport-user.adoc[Messaging4Transport]
-
include::nemo/odl-nemo-engine-user.adoc[NEMO]
include::controller/netconf/odl-netconf-user.adoc[]
include::opflex/agent-ovs-user.adoc[]
+include::ovsdb/odl-ovsdb-netvirt-user-guide.adoc[]
+
include::bgpcep/odl-bgpcep-pcep-all-user.adoc[PCEP]
include::packetcable/packetcable-user.adoc[PacketCable PCMM - CMTS Management]
include::sxp/odl-sxp-user.adoc[]
-include::tcpmd5/odl-tcpmd5-all-user.adoc[TCP-MD5]
-
include::tsdr/tsdr-user-guide.adoc[]
include::ttp/ttp-cli-tools-user.adoc[TTP]
--- /dev/null
+== Cardinal: OpenDaylight Monitoring as a Service
+This section describes how to use the Cardinal feature in OpenDaylight
+and contains configuration, administration, and management
+sections for the feature.
+
+=== 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 will add:
+
+. 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
+
+=== Configuring Cardinal feature
+To start Cardinal feature, start karaf and type the following command:
+
+ feature:install odl-cardinal
+
+After this Cardinal should be up and working with SNMP daemon running on port 161.
+
+=== Tutorials
+Below are tutorials for Cardinal.
+
+==== Using Cardinal
+These tutorials are intended for any user who wants to monitor three basic component in OpenDaylight
+
+. System Info in which controller is running.
+. Karaf Info
+. Project Specific Information.
+
+
+===== Prerequisites
+There is no as such specific prerequisite. Cardinal can work without installing any third party software. However If one
+wants to see the output of a snmpget/snmpwalk on the CLI prompt, than one can install the SNMP using the below link:
+
+https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-an-snmp-daemon-and-client-on-ubuntu-14-04
+
+Using the above command line utility one can get the same result as the cardinal APIs will give for the snmpget/snmpwalk
+request.
+
+===== Target Environment
+This tutorial is developed considering the following environment:
+
+controller-Linux(Ubuntu 14.02).
+
+
+===== Instructions
+
+====== Install Cardinal feature
+Open karaf and install the cardinal feature using the following command:
+
+----
+feature:install odl-cardinal
+----
+
+Please verify that SNMP daemon is up on port 161 using the following command on the terminal window of Linux machine:
+
+----
+netstat -anp | grep "161"
+----
+
+If the grep on the ``snmpd`` port is successful than SNMP daemon is up and working.
+
+====== APIs Reference
+Please see Developer guide for usage of Cardinal APIs.
+
+====== CLI commands to do snmpget/walk
+
+One can do snmpget/walk on the ODL-CARDINAL-MIB. Open the linux terminal and type the below command:
+
+ snmpget -v2c -c public localhost Oid_Of_the_mib_variable
+
+Or
+
+ snmpget -v2c -c public localhost ODL-CARDINAL-MIB::mib_variable_name
+
+For snmpwalk use the below command:
+
+ snmpwalk -v2c -c public localhost SNMPv2-SMI::experimental
+++ /dev/null
-== Messaging4Transport User Guide
-
-=== Overview
-The OpenDaylight controller is based on an MD-SAL allows the modeling of data, RPCs, and notifications. Because of this model basis, adding new northbound bindings to the controller is simple, and everything modeled becomes exposed automatically. Currently the MD-SAL has RESTCONF northbound bindings, while more bindings such as AMQP and XMPP can easily be implemented and integrated. Messaging4Transport attempts to build more northbound interfaces to MD-SAL, with message-oriented middleware protocols. Messaging4Transport Beryllium offers an AMQP northbound to MD-SAL.
-
-=== Architecture
-http://www.amqp.org[Advanced Message Queuing Protocol (AMQP)] is an open standard application layer protocol for message-oriented middleware. Messaging4Transport adds AMQP bindings to the MD-SAL, which would automatically make all MD-SAL APIs available via that mechanism. Messaging4Transport is built as an independent Karaf feature, that exposes the MD-SAL data tree, RPCs, and notifications via AMQP, when installed. While AMQP is the focus for the Beryllium Release, other message-oriented transport protocols will be considered for future releases.
-
-A message broker internal or external to OpenDaylight receives the messages that are published by the MD-SAL, and sends them to the subscribers. Hence, the broker functions as an intermediary in messages from the controller to the listeners, and vice versa. ActiveMQ has been chosen as the default external broker in the Messaging4Transport Beryllium.
-
-==== Installing Karaf Features
-
-Install Messaging4Transport by using the karaf console.
-
- feature:install odl-mdsal-all odl-messaging4transport-api odl-messaging4transport
-
-
-==== ActiveMQ Integration with Karaf
-ActiveMQ broker can be integrated into the Karaf environment. The http://activemq.apache.org/osgi-integration.html[ActiveMQ OSGi integration instructions page] is for Karaf 2.x. Please see the http://karaf.apache.org/manual/latest/update-notes.html[Karaf updates page] for further updates.
-
-Since OpenDaylight Beryllium is built on Karaf 3.x, the instructions are given below to install and activate ActiveMQ OSGi bundle into Karaf.
-
-* Installing ActiveMQ in Karaf
- feature:repo-add activemq 5.9.0
-
- feature:install activemq-broker
-
-
-* Installing http://hawt.io/getstarted/index.html[hawtio] in Karaf.
-
-hawtio provides a user-friendly web user interface, that can be installed optionally to work with the project.
-
- feature:repo-add hawtio 1.4.51
-
- feature:install hawtio
-
-
-
-=== Administering or Managing Messaging4Transport
-
-The broker can be a stand-alone or a Karaf-based broker integrated into OpenDaylight. Just install the bundles as shown below for Karaf based integration. In such a case, broker will start with OpenDaylight. The publisher publishes the data tree. At least a dummy listener should be started before the publisher to receive the published messages.
-
-
-You may further configure the broker by modifying the ActiveMQ configuration file in ODL_INSTALLATION_DIR/karaf/target/assembly/etc/org.apache.activemq.server-default.cfg
-
-
-Make sure to set the transport connections in karaf/target/assembly/etc/activemq.xml, which is set by default in ActiveMQ stand-alone implementation; but not in the Karaf implementation.
-
-It is suggested to limit concurrent connections to just 1000. However, probably we will need more concurrency, based on the requirements. Setting it to 100,000 for now.
-
- <transportConnectors>
- <!-- DOS protection, limit concurrent connections to 1000 and frame size to 100MB -->
- <!-- Uncomment whatever necessary. -->
- <transportConnector name="openwire" uri="tcp://0.0.0.0:61616?maximumConnections=100000&wireFormat.maxFrameSize=104857600"/>
- <transportConnector name="amqp" uri="amqp://0.0.0.0:5672?maximumConnections=100000&wireFormat.maxFrameSize=104857600"/>
- <!--transportConnector name="stomp" uri="stomp://0.0.0.0:61613?maximumConnections=100000&wireFormat.maxFrameSize=104857600"/ -->
- <!--transportConnector name="mqtt" uri="mqtt://0.0.0.0:1883?maximumConnections=100000&wireFormat.maxFrameSize=104857600"/ -->
- <!--transportConnector name="ws" uri="ws://0.0.0.0:61614?maximumConnections=100000&wireFormat.maxFrameSize=104857600"/ -->
- </transportConnectors>
-
-
-You may need to install/re-install the bundle after that and restart the container for the changes to take effort.
-
-The MD-SAL will be the publisher that publishes the MD-SAL data tree, RPCs, and notifications via AMQP. The listener can be any consumer that consumes the data tree and the other data published by MD-SAL via the AMQP binding.
-
-Once configured, the ActiveMQ console can be accessed from the http://localhost:8181/hawtio/[hawtio web console] with the credentials karaf/karaf.
-
-Messaging4Transport can hence be configured to publish MD-SAL notifications to an external AMQP listener application through the broker. A simple listener application is included in the org.opendaylight.messaging4transport.sample package.
\ No newline at end of file
+++ /dev/null
-== AAA service
-
-Chapter on AAA service.
-
+++ /dev/null
-== Controller
-
-Chapter on the controller
-
+++ /dev/null
-== Defense4All
-
-=== Defense4All Overview
-Defense4All is an SDN application for detecting and mitigating DDoS attacks. The figure below depicts the positioning of Defense4All in OpenDaylight environment. +
-
-.Defense4All Overview
-image::defense4all_overview.jpg[Defense4All Overview,width=500]
-
-The application communicates with OpenDaylight Controller through the ODC north-bound REST API.
-
-Through the REST API Defense4All performs the following tasks:
-
-. Monitoring behavior of protected traffic - the application sets flow entries in selected network locations to read traffic statistics for each of the PNs (aggregating statistics collected for a given PN from multiple locations).
-. Diverting attacked traffic to selected AMSs – the application set flow entries in selected network locations to divert traffic to selected AMSs. When an attack is over the application removes these flow entries, thus returning to normal operation and traffic monitoring.
-
-Defense4All can optionally communicate with the defined AMSs. For example: To dynamically configure them, monitor them or collect and act upon attack statistics from the AMSs. The API to AMS is not standardized, and in any case beyond the scope of the OpenDaylight work.
-Defense4All contains a reference implementation pluggable driver to communicate with Radware’s DefensePro AMS.
-
-The application presents its north-bound REST and CLI APIs to allow its manager to:
-
-Control and configure the application (runtime parameters, ODC connectivity, AMSs in domain, PNs, and so on.).
-Obtain reporting data – operational or security, current or historical, unified from Defense4All and other sources such as, ODC and AMSs).
-Defense4All provides unified management, reporting and monitoring.
-
-*Management* - Important part of Defense4All operation is to allow users simple “one touch” and abstracted provisioning of security services, for both detection and mitigation operations. The user needs to only specify simple security attributes.
-*Reporting and monitoring operations* - Important part of security services is a combination of (near) real-time logs for monitoring as well as historical logs for reporting.
-Defense4All provides a unified interface for both purposes. The monitoring information is based on various events collected from Defense4All, AMSs and ODC, allowing rich and correlated view on events.
-Logged event records can be operational or security related. The former includes failures and errors and informational logs.
-The latter includes detections, attacks and attack mitigation lifecycles, traffic diversion information and periodic traffic averages.
-All logs are persistent (stable storage and replication).
-
-=== Defense4All User Interface
-This section describes how to configure the Defense4All Framework environment. +
-
-==== Configuring the FrameWork Environment
-
-To set Defense4All configuration parameters: +
-
-. From an Internet browser, go to http://<ip address>:8086/controlapps, where _<ip address>_ is the address for the host that is running Defense4All.
-. From the FrameWork Setup pane, select *Framework* > *Setup*.
-. Set the *Framework Control Network Address* to the IP address Defense4All uses to access the control network.
-. To the right of the SDN Controllers label, click *Add*.
-. In the Add SDN Controller pane, set the following parameters:
-
-[options="header"]
-|===
-|Parameter|Description
-|Hostname |Name of the SDN Controller. This is the SDN Controller that supports OpenFlow network programming (OFC stands for OpenFlow Controller).
-OpenDaylight Controller provides this flavor both for OpenFlow enabled network devices and other network devices with adequate plug-ins in the PFC.
-|IP address|IP address of the SDN Controller.
-|Port|Port number of the SDN Controller.
-|Statistics Polling Interval|The frequency that the SDN Controller polls for statistics.
-|Username|Username to log into the SDN Controller.
-|Password|Password to log into the SDN Controller.
-|Confirm Password |Confirmation of the password of the SDN Controller.
-|===
-
-[start = 6]
-. Click Submit. +
-
-NOTE: The SDN controller cannot be changed or removed. Only one (1) SDN controller can be configured. To change the SDN controller, you must reset Defense4All to factory settings.
-. In the FrameWork Setup pane, to the right of the Attack Mitigation Systems (AMSs) label, click Add.
-. In the Add Attack Mitigation System (AMS) pane, set the following parameters:
-
-
-[options="header"]
-|===
-|Parameter|Description
-|Name|AMS descriptive name.
-|Brand|Select the AMS brand from the drop-down list. +
-
-Values: Radware DefensePro, Other +
-
-Default: Radware +
-
-*Note:* The Radware DefensePro device can be removed only when there are no active mitigations (traffic redirections to it).
-|Version|AMS version. +
-
-*Note:* This parameter is only applicable to Radware DefensePro.
-|IP Address| AMS IP address. +
-
-*Note:* This parameter is only applicable to Radware DefensePro.
-|Port|AMS port number. +
-
-*Note:* This parameter is only applicable to Radware DefensePro.
-|Username|AMS username. +
-
-*Note:* This parameter is only applicable to Radware DefensePro.
-|Password|Password to log into the AMS. +
-
-*Note:* This parameter is only applicable to Radware DefensePro.
-|Confirm Password|Confirmation of the password of the AMS. +
-
-*Note:* This parameter is only applicable to Radware DefensePro.
-|Health Check| Interval Time in seconds. +
-
-*Note:* This parameter is only applicable to Radware DefensePro.
-Default: 60 seconds
-|===
---
-NOTE: Only relevant for DefensePro. Layer 2 Broadcast Destination MAC Address, Multicast Destination MAC Address, Unrecognized L2 Format, and TTL Less Than or Equal to 1 blocking must be configured to avoid Layer 2 loops. For more information, refer to the discussion on Packet Anomaly protection in the DefensePro User Guide. +
---
-[start = 9]
-
-. Click *Submit*. +
-. In the FrameWork Setup pane, to the right of the *Net Nodes* label, click *Add*.
-. In the Add Net Node pane, set the following parameters:
-
-+
---
-[options="header"]
-|===
-|Parameter| Description
-|Name| NetNode descriptive name.
-|ID| NetNode ID.
-|Type (read-only)| Default: OpenFlow
-|SDN Node Mode (read-only)| Default: sdnenablednative.
-|Health Check Interval (read- only)| Default: 60 seconds
-|===
---
-+
-
-[Start = 12]
-
-. To the right of the *Protected Links* label, click Add. +
-. In the Add Protected Link pane, set the following parameters: +
-+
---
-[options="header"]
-|===
-|Parameter| Description
-|Incoming Traffic Port|The incoming traffic port number.
-|Outgoing Traffic Port|The outgoing traffic port number.
-|===
---
-+
-
-[Start = 14]
-. Click *OK*.
-. To the right of the AMS Connections label, click *Add*.
-. In the Add AMS Connection pane, set the following parameters:
-
-+
---
-[options="header"]
-|===
-|Parameter| Description
-|Name| AMS connection descriptive name.
-|AMS Name| AMS connection name.
-|NetNode North Port| NetNode NothPort.
-|NetNode South Port| NetNode South Port.
-|AMS North Port| AMS North Port.
-|AMS South Port| AMS South Port.
-|===
---
-+
-
-[Start = 16]
-
-. Click *OK*.
-. In the Add Net Node pane, click *Submit*.
-
-==== FrameWork Maintenance
-
-This section describes how to run maintenance operations on Defense4All
-
-* *Reset to Factory Settings* — If you want to reset Defense4All to its factory settings, at the bottom of the FrameWork Setup pane, click Reset to Factory Settings.
-* *Restart Framework* — To manually restart Defense4All, at the bottom of the FrameWork Setup
-pane, click Restart FrameWork.
-
-==== FrameWork Reports
-
-You can generate reports containing syslog messages that have been saved over a period of time.
-
-To generate FrameWork reports: +
-
-. From an Internet browser enter the IP address for the host that is running Defense4All.
-. In the FrameWork Reports pane, select *Framework > Report*.
-. In the FrameWork Report pane, select one of the tabs: +
-
-.. Query by Time Period +
-* In the *From* and *To* fields, select the appropriate dates to define the range of the query.
-* Select the *Event Types* you want included in the report.
-* Click *Run Query*. The results display at the bottom of the pane.
-* Enter a file path in the *Filename* filed, and click *Export Query to File* to save the query to a file.
-
-.. Query by Last Number of Rows
-* In the *Number of Rows* field, enter the last number of rows in the database you want displayed in your report.
-* Select the *Event Types* you want included in the report.
-* Click *Run Query*. The results display at the bottom of the pane. You cannot save this query to a file
-.. Cleanup +
-
-* In the *Delete events older than* field, enter a number of days. Events older than this number of days are deleted.
-* Click *Submit*. The results display at the bottom of the pane. You cannot save this query to a file.
-
-==== Configuring Defense4All Protected Objects (POs)
-
-This section describes how to configure Defense4All protected objects (POs).
-
-To set up Defense4All protected objects (POs): +
-
-. From an Internet browser, enter the IP address for the host that is running Defense4All.
-. From the Defense4All Setup pane, select *Defense4All* > *Setup*.
-. To the right of the *Protected Objects (POs)* label, click *Add*.
-. In the Add Protected Object (PO) pane, set the following parameters:
-
-[options="header"]
-|===
-|Parameter| Description
-|Name| Name of the PO. +
-Valid characters: A–Z, a–z, 0-9, _ +
-*NOTE:* A PO cannot be removed when under attack.
-|IP Address| IP address and net mask of the PO.
-|===
-[start = 5]
-. Click Submit.
-
-==== Defense4All Reports
-
-You can generate reports containing syslog messages that have been saved over a period of time. +
-
-To generate Defense4All reports: +
-
-. From an Internet browser enter the IP address for the host that is running Defense4All.
-. In the Defense4All Reports pane, select *Defense4All* > *Report*.
-. In the Defense4All Reports pane, select one of the tabs:
-
--Query by Time Period +
-
-* In the *From* and *To* fields, select the appropriate dates to define the range of the query.
-* Select the *Event Types* you want included in the report.
-* Click *Run Queryv*. The results display at the bottom of the pane.
-* To save the query to a file, enter a file path in the *Filename* filed, and click *Export Query* to File.
-
--Query by Last Number of Rows +
-
-* In the *Number of Rows* field, enter the last number of rows in the database you want displayed in your report.
-* Select the *Event Types* you want included in the report.
-* Click *Run Query*. The results display at the bottom of the pane. You cannot save this query to a file.
-
--Cleanup +
-
-* In the *Delete events older* than field, enter a number of days. Events older than this number of days are deleted.
-* Click *Submit*. The results display at the bottom of the pane. You cannot save this query to a file.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+++ /dev/null
-== dLux
-
-Chapter on DLUX
-
+++ /dev/null
-== Group-Based Policy
-
-The Group-Based Policy implementation for Helium is a Proof of Concept. This Proof of Concept implementation includes one example of a group-based policy renderer, based on Open vSwitch, OpenFlow, and OVSDB. Users can create policies and endpoints using the RESTCONF northbound API.
-
-=== Architecture and Model
-
-The Group-Based Policy architecture and model are described in the OpenDaylight Developer's Guide.
-
-=== Tutorial
-
-This section will walk you through setting up a simple demo of the OpenFlow overlay renderer using mininet. This will simulate a scenario with two VM hosts connected over a VXLAN tunnel.
-
-==== Prepare the Environment
-
-Start with two running Ubuntu 14.04 systems, which can be either VMs or physical machines. You'll need a newer version of openvswitch than exists in Ubuntu 14.04, but you only need the user space components so this is easy. We'll start by installing OVS 2.1.2 or later.
-
-Log into one of your Ubuntu systems, and run:
-
-----
- OVS_VERSION=2.1.2
- sudo apt-get install build-essential fakeroot debhelper libssl-dev
- wget http://openvswitch.org/releases/openvswitch-${OVS_VERSION}.tar.gz
- tar -xzf openvswitch-${OVS_VERSION}.tar.gz
- cd openvswitch-${OVS_VERSION}
- DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary
- cd ..
- sudo dpkg -i openvswitch-common_${OVS_VERSION}-1_amd64.deb openvswitch-switch_${OVS_VERSION}-1_amd64.deb
- sudo apt-get install mininet
-----
-
-Now, either run the same commands on the other system, or just copy the openvswitch-common and openvswitch-switch deb files over and install them, plus install mininet from apt.
-
-==== Configuring the Test
-
-The test script is found in the source tree under +util/testOfOverlay+. Copy the +.py+ files from this directory to each of your test systems. Open +config.py+ in an editor. You can play with this file later, but for now, just find the section that reads:
-
-----
- switches = [{'name': 's1',
- 'tunnelIp': '10.160.9.20',
- 'dpid': '1'},
- {'name': 's2',
- 'tunnelIp': '10.160.9.21',
- 'dpid': '2'}]
-----
-
-Change the +tunnelIp+ items to be the IP addresses of each of your test systems. The IP address of host 1 should be assigned to s1 and similarly for host 2 and s2.
-
-==== Running the Test
-
-Now, run the controller. You can run it on one of your test systems or on a third system.
-
-On test host 1, cd to the directory containing the +testOfOverlay+ script and run:
-
-----
- CONTROLLER=10.160.31.238
- sudo ./testOfOverlay.py --local s1 --controller ${CONTROLLER}
-----
-
-You'll need to replace the +CONTROLLER+ address with the IP address of the system where you ran your controller. This will run mininet and set up the hosts that are configured as attached to s1. When you're finished running this, you'll be at a mininet prompt, but you won't be able to do anything because the policy is not set up.
-
-The output will look like:
-
-----
-$ sudo ./testOfOverlay.py --local s1 --controller 10.160.31.238
-*** Configuring hosts
-h35_2 h35_3 h36_2 h36_3
-*** Starting controller
-*** Starting 1 switches
-s1
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "1eaf9a67-a171-42a8-9282-71cf702f61dd",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.35.2",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:35:02",
- "ofoverlay:node-connector-id": "openflow:1:1",
- "ofoverlay:node-id": "openflow:1",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "1eaf9a67-a171-42a8-9282-71cf702f61dd",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.35.3",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:35:03",
- "ofoverlay:node-connector-id": "openflow:1:2",
- "ofoverlay:node-id": "openflow:1",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "e593f05d-96be-47ad-acd5-ba81465680d5",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.36.2",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:36:02",
- "ofoverlay:node-connector-id": "openflow:1:3",
- "ofoverlay:node-id": "openflow:1",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "e593f05d-96be-47ad-acd5-ba81465680d5",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.36.3",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:36:03",
- "ofoverlay:node-connector-id": "openflow:1:4",
- "ofoverlay:node-id": "openflow:1",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-*** Starting CLI:
-mininet>
-----
-
-On test host 2, you'll do the same but run instead:
-
-----
- CONTROLLER=10.160.31.238
- sudo ./testOfOverlay.py --local s2 --controller ${CONTROLLER} --policy
-----
-
-This will run mininet on the other system, and also install all the policy required to enable the connectivity.
-
-The output will look like:
-
-----
-$ sudo ./testOfOverlay.py --local s2 --controller ${CONTROLLER} --policy
-*** Configuring hosts
-h35_4 h35_5 h36_4 h36_5
-*** Starting controller
-*** Starting 1 switches
-s2
-PUT http://10.160.31.238:8080/restconf/config/opendaylight-inventory:nodes
-{
- "opendaylight-inventory:nodes": {
- "node": [
- {
- "id": "openflow:1",
- "ofoverlay:tunnel-ip": "10.160.9.20"
- },
- {
- "id": "openflow:2",
- "ofoverlay:tunnel-ip": "10.160.9.21"
- }
- ]
- }
-}
-
-PUT http://10.160.31.238:8080/restconf/config/policy:tenants
-{
- "policy:tenants": {
- "tenant": [
- {
- "contract": [
- {
- "clause": [
- {
- "name": "allow-http-clause",
- "subject-refs": [
- "allow-http-subject",
- "allow-icmp-subject"
- ]
- }
- ],
- "id": "22282cca-9a13-4d0c-a67e-a933ebb0b0ae",
- "subject": [
- {
- "name": "allow-http-subject",
- "rule": [
- {
- "classifier-ref": [
- {
- "direction": "in",
- "name": "http-dest"
- },
- {
- "direction": "out",
- "name": "http-src"
- }
- ],
- "name": "allow-http-rule"
- }
- ]
- },
- {
- "name": "allow-icmp-subject",
- "rule": [
- {
- "classifier-ref": [
- {
- "name": "icmp"
- }
- ],
- "name": "allow-icmp-rule"
- }
- ]
- }
- ]
- }
- ],
- "endpoint-group": [
- {
- "consumer-named-selector": [
- {
- "contract": [
- "22282cca-9a13-4d0c-a67e-a933ebb0b0ae"
- ],
- "name": "e593f05d-96be-47ad-acd5-ba81465680d5-1eaf9a67-a171-42a8-9282-71cf702f61dd-22282cca-9a13-4d0c-a67e-a933ebb0b0ae"
- }
- ],
- "id": "1eaf9a67-a171-42a8-9282-71cf702f61dd",
- "network-domain": "77284c12-a569-4585-b244-af9b078acfe4",
- "provider-named-selector": []
- },
- {
- "consumer-named-selector": [],
- "id": "e593f05d-96be-47ad-acd5-ba81465680d5",
- "network-domain": "472ab051-554e-45be-a133-281f0a53412a",
- "provider-named-selector": [
- {
- "contract": [
- "22282cca-9a13-4d0c-a67e-a933ebb0b0ae"
- ],
- "name": "e593f05d-96be-47ad-acd5-ba81465680d5-1eaf9a67-a171-42a8-9282-71cf702f61dd-22282cca-9a13-4d0c-a67e-a933ebb0b0ae"
- }
- ]
- }
- ],
- "id": "f5c7d344-d1c7-4208-8531-2c2693657e12",
- "l2-bridge-domain": [
- {
- "id": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "parent": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "l2-flood-domain": [
- {
- "id": "34cc1dd1-2c8c-4e61-a177-588b2d4133b4",
- "parent": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6"
- },
- {
- "id": "6e669acf-2fd9-48ea-a9b0-cd98d933a6b8",
- "parent": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6"
- }
- ],
- "l3-context": [
- {
- "id": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "subject-feature-instances": {
- "classifier-instance": [
- {
- "classifier-definition-id": "4250ab32-e8b8-445a-aebb-e1bd2cdd291f",
- "name": "http-dest",
- "parameter-value": [
- {
- "name": "type",
- "string-value": "TCP"
- },
- {
- "int-value": "80",
- "name": "destport"
- }
- ]
- },
- {
- "classifier-definition-id": "4250ab32-e8b8-445a-aebb-e1bd2cdd291f",
- "name": "http-src",
- "parameter-value": [
- {
- "name": "type",
- "string-value": "TCP"
- },
- {
- "int-value": "80",
- "name": "sourceport"
- }
- ]
- },
- {
- "classifier-definition-id": "79c6fdb2-1e1a-4832-af57-c65baf5c2335",
- "name": "icmp",
- "parameter-value": [
- {
- "int-value": "1",
- "name": "proto"
- }
- ]
- }
- ]
- },
- "subnet": [
- {
- "id": "77284c12-a569-4585-b244-af9b078acfe4",
- "ip-prefix": "10.0.35.1/24",
- "parent": "34cc1dd1-2c8c-4e61-a177-588b2d4133b4",
- "virtual-router-ip": "10.0.35.1"
- },
- {
- "id": "472ab051-554e-45be-a133-281f0a53412a",
- "ip-prefix": "10.0.36.1/24",
- "parent": "6e669acf-2fd9-48ea-a9b0-cd98d933a6b8",
- "virtual-router-ip": "10.0.36.1"
- }
- ]
- }
- ]
- }
-}
-
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "1eaf9a67-a171-42a8-9282-71cf702f61dd",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.35.4",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:35:04",
- "ofoverlay:node-connector-id": "openflow:2:1",
- "ofoverlay:node-id": "openflow:2",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "1eaf9a67-a171-42a8-9282-71cf702f61dd",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.35.5",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:35:05",
- "ofoverlay:node-connector-id": "openflow:2:2",
- "ofoverlay:node-id": "openflow:2",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "e593f05d-96be-47ad-acd5-ba81465680d5",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.36.4",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:36:04",
- "ofoverlay:node-connector-id": "openflow:2:3",
- "ofoverlay:node-id": "openflow:2",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-POST http://10.160.31.238:8080/restconf/operations/endpoint:register-endpoint
-{
- "input": {
- "endpoint-group": "e593f05d-96be-47ad-acd5-ba81465680d5",
- "l2-context": "70aeb9ea-4ca1-4fb9-9780-22b04b84a0d6",
- "l3-address": [
- {
- "ip-address": "10.0.36.5",
- "l3-context": "f2311f52-890f-4095-8b85-485ec8b92b3c"
- }
- ],
- "mac-address": "00:00:00:00:36:05",
- "ofoverlay:node-connector-id": "openflow:2:4",
- "ofoverlay:node-id": "openflow:2",
- "tenant": "f5c7d344-d1c7-4208-8531-2c2693657e12"
- }
-}
-
-*** Starting CLI:
-mininet>
-----
-
-==== Verifying
-
-In the default test, we have a total of 2 hosts on each switch in each of 2 endpoint groups, for a total of eight hosts. The endpoints are in two different subnets, so communicating across the two endpoint groups requires routing. There is a contract set up that allows HTTP from EG1 to EG2, and ICMP in both directions between EG1 and EG2.
-
-===== ICMP
-
-We expect ICMP to work between all pairs of hosts. First, on host one, run pingall as follows:
-
-----
-mininet> pingall
-*** Ping: testing ping reachability
-h35_2 -> h35_3 h36_2 h36_3
-h35_3 -> h35_2 h36_2 h36_3
-h36_2 -> h35_2 h35_3 h36_3
-h36_3 -> h35_2 h35_3 h36_2
-*** Results: 0% dropped (12/12 received)
-----
-
-and the same on host 2:
-
-----
-mininet> pingall
-*** Ping: testing ping reachability
-h35_4 -> h35_5 h36_4 h36_5
-h35_5 -> h35_4 h36_4 h36_5
-h36_4 -> h35_4 h35_5 h36_5
-h36_5 -> h35_4 h35_5 h36_4
-----
-
-The hosts +h35_[n]+ are in EG1, in the subnet 10.0.35.1/24. Hosts +h36_[n]+ are in EG2, in the subnet 10.0.36.1/24. These two tests therefore shows broadcast within the flood domain working to enable ARP, bridging within the endpoint group, and the functioning of the virtual router which is routing traffic between the two subnets. It also shows the ICMP policy allowing the ping between the two groups.
-
-Now we can test connectivity over the tunnel:
-
-----
-mininet> h35_2 ping -c1 10.0.35.4
-PING 10.0.35.4 (10.0.35.4) 56(84) bytes of data.
-64 bytes from 10.0.35.4: icmp_seq=1 ttl=64 time=1.78 ms
-
---- 10.0.35.4 ping statistics ---
-1 packets transmitted, 1 received, 0% packet loss, time 0ms
-rtt min/avg/max/mdev = 1.786/1.786/1.786/0.000 ms
-mininet> h35_2 ping -c1 10.0.35.5
-PING 10.0.35.5 (10.0.35.5) 56(84) bytes of data.
-64 bytes from 10.0.35.5: icmp_seq=1 ttl=64 time=2.59 ms
-
---- 10.0.35.5 ping statistics ---
-1 packets transmitted, 1 received, 0% packet loss, time 0ms
-rtt min/avg/max/mdev = 2.597/2.597/2.597/0.000 ms
-mininet> h35_2 ping -c1 10.0.36.4
-PING 10.0.36.4 (10.0.36.4) 56(84) bytes of data.
-64 bytes from 10.0.36.4: icmp_seq=1 ttl=62 time=2.64 ms
-
---- 10.0.36.4 ping statistics ---
-1 packets transmitted, 1 received, 0% packet loss, time 0ms
-rtt min/avg/max/mdev = 2.641/2.641/2.641/0.000 ms
-mininet> h35_2 ping -c1 10.0.36.5
-PING 10.0.36.5 (10.0.36.5) 56(84) bytes of data.
-64 bytes from 10.0.36.5: icmp_seq=1 ttl=62 time=2.93 ms
-
---- 10.0.36.5 ping statistics ---
-1 packets transmitted, 1 received, 0% packet loss, time 0ms
-rtt min/avg/max/mdev = 2.936/2.936/2.936/0.000 ms
-----
-
-This shows all those same features working transparently across the tunnel to the hosts on the other switch.
-
-===== HTTP
-
-We expect HTTP to work only when going from EG1 to EG2, and only on port 80. Let's check. First, we'll start a web server on +h36_2+ by running this on host 1:
-
-----
- mininet> h36_2 python -m SimpleHTTPServer 80
-----
-
-Note that this will block your prompt until you Ctrl-C it later.
-
-Now on host 2, run:
-
-----
-mininet> h35_4 curl http://10.0.36.2
- % Total % Received % Xferd Average Speed Time Time Time Current
- Dload Upload Total Spent Left Speed
-100 488 100 488 0 0 72944 0 --:--:-- --:--:-- --:--:-- 97600
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html>
-<title>Directory listing for /</title>
-<body>
-<h2>Directory listing for /</h2>
-<hr>
-<ul>
-<li><a href="config.py">config.py</a>
-<li><a href="config.pyc">config.pyc</a>
-<li><a href="mininet_gbp.py">mininet_gbp.py</a>
-<li><a href="mininet_gbp.pyc">mininet_gbp.pyc</a>
-<li><a href="odl_gbp.py">odl_gbp.py</a>
-<li><a href="odl_gbp.pyc">odl_gbp.pyc</a>
-<li><a href="testOfOverlay.py">testOfOverlay.py</a>
-</ul>
-<hr>
-</body>
-</html>
-----
-
-You can see that the host in endpoint group 1 is able to access the server in endpoint group 2.
-
-Let's try the reverse. Ctrl-C the server on host 1 and then run:
-
-----
- mininet> h35_2 python -m SimpleHTTPServer 80
-----
-
-We can still access the server from +h35_4+ on host 2, because it's in the same endpoint group:
-
-----
-mininet> h35_4 curl http://10.0.35.2
- % Total % Received % Xferd Average Speed Time Time Time Current
- Dload Upload Total Spent Left Speed
-100 488 100 488 0 0 55625 0 --:--:-- --:--:-- --:--:-- 61000
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html>
-<title>Directory listing for /</title>
-<body>
-<h2>Directory listing for /</h2>
-<hr>
-<ul>
-<li><a href="config.py">config.py</a>
-<li><a href="config.pyc">config.pyc</a>
-<li><a href="mininet_gbp.py">mininet_gbp.py</a>
-<li><a href="mininet_gbp.pyc">mininet_gbp.pyc</a>
-<li><a href="odl_gbp.py">odl_gbp.py</a>
-<li><a href="odl_gbp.pyc">odl_gbp.pyc</a>
-<li><a href="testOfOverlay.py">testOfOverlay.py</a>
-</ul>
-<hr>
-</body>
-</html>
-----
-
-But we cannot access it from +h36_4+ on host 2, because it's in a different endpoint group and our contract allows HTTP only in the other direction:
-
-----
-mininet> h36_4 curl http://10.0.35.2 --connect-timeout 3
- % Total % Received % Xferd Average Speed Time Time Time Current
- Dload Upload Total Spent Left Speed
- 0 0 0 0 0 0 0 0 --:--:-- 0:00:03 --:--:-- 0
-curl: (28) Connection timed out after 3001 milliseconds
-----
-
-=== Contact Information
-
-Mailing List::
-groupbasedpolicy-users@lists.opendaylight.org
-IRC::
-freenode.net #opendaylight-group-policy
-Repository::
- https://git.opendaylight.org/gerrit/groupbasedpolicy
-
+++ /dev/null
-== L2Switch
-The L2Switch project provides Layer2 switch functionality.
-
-=== Running the L2Switch project
-
-==== 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
-
-=== Components of the L2Switch
-* 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
-
-=== Configuration of L2Switch Components
-This section details 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
-
-* 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.
-
-* 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"
-
-* 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.
-
-* 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"
-
-
+++ /dev/null
-== Lisp Flow Mapping
-
-Please see the OpenDaylight Developer's Guide for detailed instructions and a tutorial.
-
-
-
+++ /dev/null
-== ODL-SDNi
-
-The User Guide for ODL-SDNi can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/ODL-SDNiApp:User_Guide
+++ /dev/null
-== OpenFlow Protocol Library
-
-https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Startup_Guide
-
+++ /dev/null
-== OpenFlow Plugin
-
-Chapter on OpenFlow Plugin
+++ /dev/null
-== Helium Overview
-
-add text and reference to helium project dependency diagram
-
+++ /dev/null
-== OVSDB Integration
-
-The User Guide for OVSDB Integration can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/OVSDB:User_Guide
+++ /dev/null
-== Packet Cable MultiMedia (PCMM) Service
-
-Packet Cable MultiMedia (PCMM) provides an interface to control and management service flow for CMTS network elements. A service flows constitute a DOCSIS data path between a CMTS and a subscriber's cable modem (CM) guaranteed application specific quality of service (QoS), known as Dynamic Quality of Service (DQoS). PCMM offers (MSOs) the ability to deliver new services using existing cable infrastructure. MSOs have already begun to apply PCMM technology for expanding their multimedia service offerings.
-
-=== Overview
-
-The PCMM architecture comprises the following components:
-
-* The Application Manager, which specifies QoS requirements to the Policy Server on a per-application basis.
-* The Policy Server, which allocates network resources per subscriber and per application, ensuring that consumption meets MSO priorities.
-* The Cable Modem Termination System (CMTS), which enforces policies according to bandwidth capacity.
-* The Cable Modem, which resides on the client side and connects the client's network to the cable system.
-
-PacketCable Multimedia defines a service delivery framework that provides general-purpose QoS, event-based accounting, and security functionality founded upon the mechanisms defined in PacketCable 1.x. However, due to the broader spectrum of applications and services addressed by this initiative, each of these functional areas has been revisited and generalized for the present purposes. Telephony-specific requirements and interfaces (e.g., call signaling, PSTN interconnection and electronic surveillance) are not part of PacketCable Multimedia, while core functionality such as QoS resource management mechanisms, has been enhanced. Throughout this process, one of the primary objectives of this work has been to leverage and reuse as much of the existing body of PacketCable 1.x investment, knowledge base, and technical functionality as possible. Key features of the described Multimedia service delivery framework include:
-
-* Simple, powerful access to DOCSIS QoS mechanisms supporting both time and volume-based network resource authorizations,
-* Abstract, event-based network resource auditing and management mechanisms,
-* A robust security infrastructure that provides integrity and appropriate levels of protection across all interfaces.
-
-The goal of this project is to utilizes the OpenDaylight controller platform as for the Application Manager and parts of the Policy Server and leverage the as many existing components offered by the platform.
-
-The initial southbound transport has been written to the following version of the specification: http://www.cablelabs.com/wp-content/uploads/specdocs/PKT-SP-MM-I05-091029.pdf
-
-=== Architecture
-.Architecture Overview
-image::pcmm-docsis.png["Architecture Overview", width=512]
-
-The OpenDaylight Packetcable PCMM includes:
-
-* Packetcable PCMM Provider
-* Packetcable PCMM Consumer
-* Packetcable PCMM Model
-* Southbound ODL plugin supporting PCMM/COPS protocol driver
-* Packetcable PCMM RESTCONF Service API
-
-=== Features
-
-A brief description of some of what this feature has to offer:
-
-* Provision a CMTS
-* Flow Programmer match-only for managing DOCSIS (service) flows
-* RESTCONF APIs for provisioning CMTS network elements
-* HTML Provisioning Interface and some Python examples
-* RESTCONF APIs for provisioning Service Flow values and types
-* RESTCONF APIs for provisioning QoS (or metering) parameters
-* SAL extensions for DOCSIS specific data model and configuration APIs
-* PCMM/COPS protocol transport plugin
-
-==== Install
-
-[source, text]
-----
-opendaylight-user@root>feature:install odl-packetcable-all
-----
-
-=== Support
-
-For support please contact the packetcable project at:
-
-* PCMM PacketCable mailing list: dev@lists.opendaylight.org
+++ /dev/null
-== Plugin for OpenContrail
-
-The User Guide for the Plugin for OpenContrail can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/Southbound_Plugin_to_the_OpenContrail_Platform:User_Guide
+++ /dev/null
-== Secure Network Bootstrapping Infrastructure
-
-Chapter on Secure Network Bootstrapping Infrastructure
-
+++ /dev/null
-== SNMP4SDN
-
-Chapter on SNMP for SDN
-
+++ /dev/null
-== VTN
-
-include::vtn/VTN_Overview.adoc[VTN Overview]
-
-include::vtn/VTN_Installation.adoc[VTN Installation Guide]
-
-include::vtn/VTN_OpenStack_Support_User_Guide.adoc[How to set up OpenStack for the integration with VTN Manager]
-
-=== VTN Usage Examples
-
-include::vtn/VTN_How_To_configure_L2_Network_with_Single_Controller.adoc[How to configure L2 Network with Single Controller]
-
-include::vtn/VTN_How_To_configure_L2_Network_with_Multiple_Controllers.adoc[How to configure L2 Network with Multiple Controllers]
-
-include::vtn/VTN_How_To_test_vlanmap_using_mininet.adoc[How To Test Vlan-Map In Mininet Environment]
-
-include::vtn/VTN_How_To_view_STATIONS.adoc[VTN Station information]
-
-include::vtn/VTN_How_To_view_Dataflows.adoc[Dataflows Path Information]
-
-include::vtn/VTN_How_To_configure_flow_filters.adoc[How To Configure Flow Filters Using VTN]
-
-include::vtn/VTN_How_To_Use_VTN_to_make_packets_take_different_paths.adoc[Change Traffic Path]
-
-include::vtn/VTN_How_To_Troubleshoot_Coordinator_Installation.adoc[Troubleshoot VTN Coordinator]
+++ /dev/null
-== Yangtools
-
-Chapter on Yang tools
-
--- /dev/null
+=== NetVirt
+
+The OVSDB NetVirt project delivers two major pieces of functionality:
+
+. The OVSDB Southbound Protocol, and
+. NetVirt, a network virtualization solution.
+
+The following diagram shows the system-level architecture of OVSDB NetVirt in
+an OpenStack-based solution.
+
+.OVSDB NetVirt Architecture
+image::ovsdb/ovsdb-netvirt-architecture.jpg[align="center",width=250]
+
+NetVirt is a network virtualization solution that is a Neutron service provider, and therefore supports
+the OpenStack Neutron Networking API and extensions.
+
+The OVSDB component implements the OVSDB protocol (RFC 7047), as well as
+plugins to support OVSDB Schemas, such as the Open_vSwitch database schema and
+the hardware_vtep database schema.
+
+NetVirt has MDSAL-based interfaces with Neutron on the northbound side, and
+OVSDB and OpenFlow plugins on the southbound side.
+
+OVSDB NetVirt currently supports Open vSwitch virtual switches
+via OpenFlow and OVSDB. Work is underway to support hardware gateways.
+
+NetVirt services are enabled by installing the odl-ovsdb-openstack feature using the following command:
+
+ feature:install odl-ovsdb-openstack
+
+To enable NetVirt's distributed Layer 3 routing services, the following line must be uncommented in the etc/custom.properties
+file in the OpenDaylight distribution prior to starting karaf:
+
+ ovsdb.l3.fwd.enabled=yes
+
+To start the OpenDaylight controller, run the following application in your distribution:
+
+ bin/karaf
+
+More details about using NetVirt with OpenStack can be found in the following places:
+
+. The "OpenDaylight and OpenStack" guide, and
+. https://wiki.opendaylight.org/view/OVSDB_Integration:Main#Getting_Started_with_OpenDaylight_OVSDB_Plugin_Network_Virtualization[Getting Started with OpenDaylight OVSDB Plugin Network Virtualization]
+
+Some additional details about using OpenStack Security Groups and the Data Plane Development Kit (DPDK) are provided below.
+
+include::odl-ovsdb-security-groups.adoc[]
+
+include::odl-ovs-dpdk-user-guide.adoc[]
--- /dev/null
+==== Using OVS with DPDK hosts and OVSDB NetVirt
+
+The Data Plane Development Kit (http://dpdk.org/[DPDK]) is a userspace set
+of libraries and drivers designed for fast packet processing. The userspace
+datapath variant of OVS can be built with DPDK enabled to provide the
+performance features of DPDK to Open vSwitch (OVS). In the 2.4.0 version of OVS, the
+Open_vSwtich table schema was enhanced to include the lists 'datapath-types' and
+'interface-types'. When the OVS with DPDK variant of OVS is running, the
+'inteface-types' list will include DPDK interface types such as 'dpdk' and 'dpdkvhostuser'.
+The OVSDB Southbound Plugin includes this information in the OVSDB YANG model
+in the MD-SAL, so when a specific OVS host is running OVS with DPDK, it is possible
+for NetVirt to detect that information by checking that DPDK interface types are
+included in the list of supported interface types.
+
+For example, query the operational MD-SAL for OVSDB nodes:
+
+HTTP GET:
+
+ http://{{CONTROLLER-IP}}:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ < content edited out >
+ {
+ "node-id": "ovsdb://uuid/f9b58b6d-04db-459a-b914-fff82b738aec",
+ < content edited out >
+ "ovsdb:interface-type-entry": [
+ {
+ "interface-type": "ovsdb:interface-type-ipsec-gre"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-internal"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-system"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-patch"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-dpdkvhostuser"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-dpdk"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-dpdkr"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-vxlan"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-lisp"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-geneve"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-gre"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-tap"
+ },
+ {
+ "interface-type": "ovsdb:interface-type-stt"
+ }
+ ],
+ < content edited out >
+ "ovsdb:datapath-type-entry": [
+ {
+ "datapath-type": "ovsdb:datapath-type-netdev"
+ },
+ {
+ "datapath-type": "ovsdb:datapath-type-system"
+ }
+ ],
+ < content edited out >
+ },
+ < content edited out >
+ ]
+ }
+ ]
+ }
+
+This example illustrates the output of an OVS with DPDK host because
+the list of interface types includes types supported by DPDK.
+
+Bridges on OVS with DPDK hosts need to be created with the 'netdev' datapath type
+and DPDK specific ports need to be created with the appropriate interface type.
+The OpenDaylight OVSDB Southbound Plugin supports these attributes.
+
+The OpenDaylight NetVirt application checks whether the OVS host is using OVS with DPDK
+when creating the bridges that are expected to be present on the host, e.g. 'br-int'.
+
+Following are some tips for supporting hosts using OVS with DPDK when using NetVirt as the Neutron service
+provider and 'devstack' to deploy Openstack.
+
+In addition to the 'networking-odl' ML2 plugin, enable the 'networking-odl-dpdk' plugin in 'local.conf'.
+
+ For working with Openstack Liberty
+ enable_plugin networking-odl https://github.com/FedericoRessi/networking-odl integration/liberty
+ enable_plugin networking-ovs-dpdk https://github.com/openstack/networking-ovs-dpdk stable/liberty
+
+ For working with Openstack Mitaka (or later) branch
+ enable_plugin networking-odl https://github.com/openstack/networking-odl
+ enable_plugin networking-ovs-dpdk https://github.com/openstack/networking-ovs-dpdk
+
+The order of these plugin lines is important. The 'networking-odl' plugin will install and
+setup 'openvswitch'. The 'networking-ovs-dpdk' plugin will install OVS with DPDK. Note, the 'networking-ovs-dpdk'
+plugin is only being used here to setup OVS with DPDK. The 'networking-odl' plugin will be used as the Neutron ML2 driver.
+
+For VXLAN tenant network support, the NetVirt application interacts with OVS with DPDK host in the same way as OVS hosts
+using the kernel datapath by creating VXLAN ports on 'br-int' to communicate with other tunnel endpoints. The IP address
+for the local tunnel endpoint may be configured in the 'local.conf' file. For example:
+
+ ODL_LOCAL_IP=192.100.200.10
+
+NetVirt will use this information to configure the VXLAN port on 'br-int'. On a host with the OVS kernel datapath, it
+is expected that there will be a networking interface configured with this IP address. On an OVS with DPDK host, an OVS
+bridge is created and a DPDK port is added to the bridge. The local tunnel endpoint address is then assigned to the
+bridge port of the bridge. So, for example, if the physical network interface is associated with 'eth0' on the host,
+a bridge named 'br-eth0' could be created. The DPDK port, such as 'dpdk0' (per the naming conventions of OVS with DPDK), is
+added to bridge 'br-eth0'. The local tunnel endpoint address is assigned to the network interface 'br-eth0' which is
+attached to bridge 'br-eth0'. All of this setup is not done by NetVirt. The 'networking-ovs-dpdk' can be made to
+perform this setup by putting configuration like the following in 'local.conf'.
+
+ ODL_LOCAL_IP=192.168.200.9
+ ODL_PROVIDER_MAPPINGS=physnet1:eth0,physnet2:eht1
+ OVS_DPDK_PORT_MAPPINGS=eth0:br-eth0,eth1:br-ex
+ OVS_BRIDGE_MAPPINGS=physnet1:br-eth0,physnet2:br-ex
+
+The above settings associate the host networking interface 'eth0' with bridge 'br-eth0'. The 'networking-ovs-dpdk' plugin
+will determine the DPDK port name associated with 'eth0' and add it to the bridge 'br-eth0'. If using the NetVirt L3 support,
+these settings will enable setup of the 'br-ex' bridge and attach the DPDK port associated with network interface 'eth1' to it.
+
+The following settings are included in 'local.conf' to specify specific attributes associated with OVS with DPDK. These are
+used by the 'networking-ovs-dpdk' plugin to configure OVS with DPDK.
+
+ OVS_DATAPATH_TYPE=netdev
+ OVS_NUM_HUGEPAGES=8192
+ OVS_DPDK_MEM_SEGMENTS=8192
+ OVS_HUGEPAGE_MOUNT_PAGESIZE=2M
+ OVS_DPDK_RTE_LIBRTE_VHOST=y
+ OVS_DPDK_MODE=compute
+
+Once the stack is up and running virtual machines may be deployed on OVS with DPDK hosts. The 'networking-odl' plugin handles
+ensuring that 'dpdkvhostuser' interfaces are utilized by Nova instead of the default 'tap' interface. The 'dpdkvhostuser' interface
+provides the best performance for VMs on OVS with DPDK hosts.
+
+A Nova flavor is created for VMs that may be deployed on OVS with DPDK hosts.
+
+ nova flavor-create largepage-flavor 1002 1024 4 1
+ nova flavor-key 1002 set "hw:mem_page_size=large"
+
+Then, just specify the flavor when creating a VM.
+
+ nova boot --flavor largepage-flavor --image cirros-0.3.4-x86_64-uec --nic net-id=<NET ID VALUE> vm-name
--- /dev/null
+==== OVSDB Hardware VTEP SouthBound Plugin
+
+===== Overview
+
+Hwvtepsouthbound plugin is used to configure a hardware VTEP which
+implements hardware ovsdb schema. This page will show how to use
+RESTConf API of hwvtepsouthbound. There are two ways to connect to ODL:
+
+.user initiates connection, and
+.switch initiates connection.
+
+Both will be introduced respectively.
+
+===== User Initiates Connection
+
+====== Prerequisite
+
+Configure the hwvtep device/node to listen for the tcp connection in
+passive mode. In addition, management IP and tunnel source IP are also
+configured. After all this configuration is done, a physical switch is
+created automatically by the hwvtep node.
+
+====== Connect to a hwvtep device/node
+
+Send below Restconf request if you want to initiate the connection to a
+hwvtep node from the controller, where listening IP and port of hwvtep
+device/node are provided.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "hwvtep://192.168.1.115:6640",
+ "hwvtep:connection-info":
+ {
+ "hwvtep:remote-port": 6640,
+ "hwvtep:remote-ip": "192.168.1.115"
+ }
+ }
+ ]
+ }
+
+Please replace 'odl' in the URL with the IP address of your OpendayLight
+controller and change '192.168.1.115' to your hwvtep node IP.
+
+**NOTE**: The format of node-id is fixed. It will be one of the two:
+
+User initiates connection from ODL:
+
+ hwvtep://ip:port
+
+Switch initiates connection:
+
+ hwvtep://uuid/<uuid of switch>
+
+The reason for using UUID is that we can distinguish between multiple
+switches if they are behind a NAT.
+
+After this request is completed successfully, we can get the physical
+switch from the operational data store.
+
+REST API: GET
+http://odl:8181/restconf/operational/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+There is no body in this request.
+
+The response of the request is:
+
+ {
+ "node": [
+ {
+ "node-id": "hwvtep://192.168.1.115:6640",
+ "hwvtep:switches": [
+ {
+ "switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640/physicalswitch/br0']"
+ }
+ ],
+ "hwvtep:connection-info": {
+ "local-ip": "192.168.92.145",
+ "local-port": 47802,
+ "remote-port": 6640,
+ "remote-ip": "192.168.1.115"
+ }
+ },
+ {
+ "node-id": "hwvtep://192.168.1.115:6640/physicalswitch/br0",
+ "hwvtep:management-ips": [
+ {
+ "management-ips-key": "192.168.1.115"
+ }
+ ],
+ "hwvtep:physical-switch-uuid": "37eb5abd-a6a3-4aba-9952-a4d301bdf371",
+ "hwvtep:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']",
+ "hwvtep:hwvtep-node-description": "",
+ "hwvtep:tunnel-ips": [
+ {
+ "tunnel-ips-key": "192.168.1.115"
+ }
+ ],
+ "hwvtep:hwvtep-node-name": "br0"
+ }
+ ]
+ }
+
+If there is a physical switch which has already been created by manual
+configuration, we can get the node-id of the physical switch from this
+response, which is presented in “swith-ref”. If the switch does not
+exist, we need to create the physical switch. Currently, most hwvtep
+devices do not support running multiple switches.
+
+====== Create a physical switch
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/
+
+request body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "hwvtep://192.168.1.115:6640/physicalswitch/br0",
+ "hwvtep-node-name": "ps0",
+ "hwvtep-node-description": "",
+ "management-ips": [
+ {
+ "management-ips-key": "192.168.1.115"
+ }
+ ],
+ "tunnel-ips": [
+ {
+ "tunnel-ips-key": "192.168.1.115"
+ }
+ ],
+ "managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']"
+ }
+ ]
+ }
+
+Note: "managed-by" must provided by user. We can get its value after the
+step 'Connect to a hwvtep device/node' since the node-id of hwvtep
+device is provided by user. "managed-by" is a reference typed of
+instance identifier. Though the instance identifier is a little
+complicated for RestConf, the primary user of hwvtepsouthbound plugin
+will be provider-type code such as NetVirt and the instance identifier
+is much easier to write code for.
+
+====== Create a logical switch
+
+Creating a logical switch is effectively creating a logical network. For
+VxLAN, it is a tunnel network with the same VNI.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+request body:
+
+ {
+ "logical-switches": [
+ {
+ "hwvtep-node-name": "ls0",
+ "hwvtep-node-description": "",
+ "tunnel-key": "10000"
+ }
+ ]
+ }
+
+====== Create a physical locator
+
+After the VXLAN network is ready, we will add VTEPs to it. A VTEP is
+described by a physical locator.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+request body:
+
+ {
+ "termination-point": [
+ {
+ "tp-id": "vxlan_over_ipv4:192.168.0.116",
+ "encapsulation-type": "encapsulation-type-vxlan-over-ipv4",
+ "dst-ip": "192.168.0.116"
+ }
+ ]
+ }
+
+The "tp-id" of locator is "\{encapsualation-type}: \{dst-ip}".
+
+Note: As far as we know, the OVSDB database does not allow the insertion
+of a new locator alone. So, no locator is inserted after this request is
+sent. We will trigger off the creation until other entity refer to it,
+such as remote-mcast-macs.
+
+====== Create a remote-mcast-macs entry
+
+After adding a physical locator to a logical switch, we need to create a
+remote-mcast-macs entry to handle unknown traffic.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+request body:
+
+ {
+ "remote-mcast-macs": [
+ {
+ "mac-entry-key": "00:00:00:00:00:00",
+ "logical-switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/hwvtep:logical-switches[hwvtep:hwvtep-node-name='ls0']",
+ "locator-set": [
+ {
+ "locator-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://219.141.189.115:6640']/network-topology:termination-point[network-topology:tp-id='vxlan_over_ipv4:192.168.0.116']"
+ }
+ ]
+ }
+ ]
+ }
+
+The physical locator 'vxlan_over_ipv4:192.168.0.116' is just created in
+"Create a physical locator". It should be noted that list "locator-set"
+is immutable, that is, we must provide a set of "locator-ref" as a
+whole.
+
+Note: "00:00:00:00:00:00" stands for "unknown-dst" since the type of
+mac-entry-key is yang:mac and does not accept "unknown-dst".
+
+====== Create a physical port
+
+Now we add a physical port into the physical switch
+"hwvtep://192.168.1.115:6640/physicalswitch/br0". The port is attached
+with a physical server or an L2 network and with the vlan 100.
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640%2Fphysicalswitch%2Fbr0
+
+ {
+ "network-topology:termination-point": [
+ {
+ "tp-id": "port0",
+ "hwvtep-node-name": "port0",
+ "hwvtep-node-description": "",
+ "vlan-bindings": [
+ {
+ "vlan-id-key": "100",
+ "logical-switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/hwvtep:logical-switches[hwvtep:hwvtep-node-name='ls0']"
+ }
+ ]
+ }
+ ]
+ }
+
+At this point, we have completed the basic configuration.
+
+Typically, hwvtep devices learn local MAC addresses automatically. But
+they also support getting MAC address entries from ODL.
+
+====== Create a local-mcast-macs entry
+
+It is similar to 'Create a remote-mcast-macs entry'.
+
+====== Create a remote-ucast-macs
+
+REST API: POST
+http://odl:8181/restconf/config/network-topology:network-topology/topology/hwvtep:1/node/hwvtep:%2F%2F192.168.1.115:6640
+
+ request body:
+
+ {
+ "remote-ucast-macs": [
+ {
+ "mac-entry-key": "11:11:11:11:11:11",
+ "logical-switch-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/hwvtep:logical-switches[hwvtep:hwvtep-node-name='ls0']",
+ "ipaddr": "1.1.1.1",
+ "locator-ref": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='hwvtep:1']/network-topology:node[network-topology:node-id='hwvtep://192.168.1.115:6640']/network-topology:termination-point[network-topology:tp-id='vxlan_over_ipv4:192.168.0.116']"
+ }
+ ]
+ }
+
+====== Create a local-ucast-macs entry
+
+This is similar to 'Create a remote-ucast-macs'.
+
+===== Switch Initiates Connection
+
+We do not need to connect to a hwvtep device/node when the switch
+initiates the connection. After switches connect to ODL successfully, we
+get the node-id's of switches by reading the operational data store.
+Once the node-id of a hwvtep device is received, the remaining steps are
+the same as when the user initiates the connection.
+
+===== References
+
+https://wiki.opendaylight.org/view/User_talk:Pzhang
--- /dev/null
+== OVSDB NetVirt
+
+include::odl-netvirt-user-guide.adoc[]
+
+include::odl-ovsdb-plugins-user-guide.adoc[]
--- /dev/null
+=== OVSDB Plugins
+
+==== Overview and Architecture
+
+There are currently two OVSDB Southbound plugins:
+
+* odl-ovsdb-southbound: Implements the OVSDB Open_vSwitch database schema.
+
+* odl-ovsdb-hwvtepsouthbound: Implements the OVSDB hardware_vtep database schema.
+
+These plugins are normally installed and used automatically by higher level applications such as
+odl-ovsdb-openstack; however, they can also be installed separately and used via their REST APIs
+as is described in the following sections.
+
+include::odl-ovsdb-southbound-user-guide.adoc[]
+
+include::odl-ovsdb-hwvtep-southbound-user-guide.adoc[]
--- /dev/null
+[[security-groups]]
+==== Security groups
+
+The security group in openstack helps to filter packets based on
+policies configured. The current implementation in openstack uses
+iptables to realize security groups. In Opendaylight instead of iptable
+rules, ovs flows are used. This will remove the many layers of
+bridges/ports required in iptable implementation.
+
+The current rules are applied on the basis of the following attributes:
+ingress/egress, protocol, port range, and prefix. In the pipeline, table
+40 is used for egress acl and table 90 for ingress acl rules.
+
+[[stateful-implementation]]
+===== Stateful Implementation
+
+The security group is implemented in two modes, stateful and stateless.
+Stateful can be enabled by setting false to true in
+etc/opendaylight/karaf/netvirt-impl-default-config.xml
+
+The stateful implementation uses the conntrack capabilities of ovs and
+tracks an existing connection. This mode requires OVS2.5 and linux
+kernel 4.3. The ovs which is integrated with netfilter framework tracks
+the connection using the five tuple(layer-3 protocol, source address,
+destination address, layer-4 protocol, layer-4 key). The connection
+state is independent of the upper level state of connection oriented
+protocols like TCP, and even connectionless protocols like UDP will have
+a pseudo state. With this implementation OVS sends the packet to the
+netfilter framework to know whether there is an entry for to the
+connection. netfilter will return the packet to OVS with the appropriate
+flag set. Below are the states we are interested in:
+
+ -trk - The packet was never send to netfilter framework
+
+ +trk+est - It is already known and connection which was allowed previously,
+ pass it to the next table.
+
+ +trk+new - This is a new connection. So if there is a specific rule in the
+ table which allows this traffic with a commit action an entry will be made
+ in the netfilter framework. If there is no specific rule to allow this
+ traffic the packet will be dropped.
+
+So, by default, a packet is be dropped unless there is a rule to allow
+the packet.
+
+[[stateless-implementation]]
+===== Stateless Implementation
+
+The stateless mode is for OVS 2.4 and below where connection tracking is
+not supported. Here we have pseudo-connection tracking using the TCP SYN
+flag. Other than TCP packets, all protocol packets is allowed by
+default. For TCP packets, the SYN packets will be dropped by default
+unless there is a specific rule which allows TCP SYN packets to a
+particular port.
+
+[[fixed-rules]]
+===== Fixed Rules
+
+The SecurityGroup are associated with the vm port when the vm is
+spawned. By default a set of rules are applied to the vm port referred
+to as fixed security group rule. This includes the DHCP rules the ARP
+rule and the conntrack rules. The conntrack rules will be inserted only
+in the stateful mode.
+
+[[dhcp-rules]]
+====== DHCP rules
+
+The DHCP rules added to the vm port when a vm is spawned. The fixed DHCP
+rules are
+
+* Allow DHCP server traffic ingress.
+
+ cookie=0x0, duration=36.848s, table=90, n_packets=2, n_bytes=717,
+ priority=61006,udp,dl_src=fa:16:3e:a1:f9:d0,
+ tp_src=67,tp_dst=68 actions=goto_table:100
+
+ cookie=0x0, duration=36.566s, table=90, n_packets=0, n_bytes=0,
+ priority=61006,udp6,dl_src=fa:16:3e:a1:f9:d0,
+ tp_src=547,tp_dst=546 actions=goto_table:100
+
+* Allow DHCP client traffic egress.
+
+ cookie=0x0, duration=2165.596s, table=40, n_packets=2, n_bytes=674,
+ priority=61012,udp,tp_src=68,tp_dst=67 actions=goto_table:50
+
+ cookie=0x0, duration=2165.513s, table=40, n_packets=0, n_bytes=0,
+ priority=61012,udp6,tp_src=546,tp_dst=547 actions=goto_table:50
+
+* Prevent DHCP server traffic from the vm port.(DHCP Spoofing)
+
+ cookie=0x0, duration=34.711s, table=40, n_packets=0, n_bytes=0,
+ priority=61011,udp,in_port=2,tp_src=67,tp_dst=68 actions=drop
+
+ cookie=0x0, duration=34.519s, table=40, n_packets=0, n_bytes=0,
+ priority=61011,udp6,in_port=2,tp_src=547,tp_dst=546 actions=drop
+
+[[arp-rules]]
+====== Arp rules
+
+The default arp rules allows the arp traffic to go in and out of the vm
+port.
+
+ cookie=0x0, duration=35.015s, table=40, n_packets=10, n_bytes=420,
+ priority=61010,arp,arp_sha=fa:16:3e:93:88:60 actions=goto_table:50
+
+ cookie=0x0, duration=35.582s, table=90, n_packets=1, n_bytes=42,
+ priority=61010,arp,arp_tha=fa:16:3e:93:88:60 actions=goto_table:100
+
+[[conntrack-rules]]
+====== Conntrack rules
+
+These rules are inserted only in stateful mode. The conntrack rules use
+the netfilter framework to track packets. The below rules are added to
+leverage it.
+
+* If a packet is not tracked(connection state –trk) it is send it to the
+netfilter for tracking
+* If the packet is already tracked (netfilter filter returns connection
+state +trk,+est) and if the connection is established, then allow the
+packet to go through the pipeline.
+* The third rule is the default drop rule which will drop the packet, if
+the packet is tracked and new(netfilter filter returns connection state
++trk,+new). This rule has lower priority than the custom rules which
+shall be added.
+
+ cookie=0x0, duration=35.015s table=40,priority=61021,in_port=3,
+ ct_state=-trk,action=ct"("table=0")"
+
+ cookie=0x0, duration=35.015s table=40,priority=61020,in_port=3,
+ ct_state=+trk+est,action=goto_table:50
+
+ cookie=0x0, duration=35.015s table=40,priority=36002,in_port=3,
+ ct_state=+new,actions=drop
+
+ cookie=0x0, duration=35.015s table=90,priority=61022,
+ dl_dst=fa:16:3e:0d:8d:21,ct_state=+trk+est,action=goto_table:100
+
+ cookie=0x0, duration=35.015s table=90,priority=61021,
+ dl_dst=fa:16:3e:0d:8d:21,ct_state=-trk,action=ct"("table=0")"
+
+ cookie=0x0, duration=35.015s table=90,priority=36002,
+ dl_dst=fa:16:3e:0d:8d:21,ct_state=+new,actions=drop
+
+[[tcp-syn-rule]]
+====== TCP SYN Rule
+
+This rule is inserted in stateless mode only. This rule will drop TCP
+SYN packet by default
+
+[[custom-security-groups]]
+===== Custom Security Groups
+
+ User can add security groups in openstack via command line or UI. When we associate this security group with a vm the flows related to each security group will be added in the related tables. A preconfigured security group called the default security group is available in neutron db.
+
+[[stateful]]
+====== Stateful
+
+If connection tracking is enabled the match will have connection state
+and the action will have commit along with goto. The commit will send
+the packet to the netfilter framework to cache the entry. After a
+commit, for the next packet of this connection netfilter will return
++trk+est and the packet will match the fixed conntrack rule and get
+forwarded to next table.
+
+ cookie=0x0, duration=202.516s, table=40, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,icmp,dl_src=fa:16:3e:ee:a5:ec,
+ nw_dst=0.0.0.0/24,icmp_type=2,icmp_code=4 actions=ct(commit),goto_table:50
+
+ cookie=0x0, duration=60.701s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,udp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=2222 actions=ct(commit),goto_table:100
+
+ cookie=0x0, duration=58.988s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,tcp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=1111 actions=ct(commit),goto_table:100
+
+[[stateless]]
+====== Stateless
+
+If the mode is stateless the match will have only the parameter
+specified in the security rule and a goto in the action. The ct_state
+and commit action will be missing.
+
+ cookie=0x0, duration=13211.171s, table=40, n_packets=0, n_bytes=0,
+ priority=61007,icmp,dl_src=fa:16:3e:93:88:60,nw_dst=0.0.0.0/24,
+ icmp_type=2,icmp_code=4 actions=goto_table:50
+
+ cookie=0x0, duration=199.674s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:dc:49:ff,nw_src=10.100.5.3,tp_dst=2222
+ actions=goto_table:100
+
+ cookie=0x0, duration=199.780s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,tcp,dl_dst=fa:16:3e:93:88:60,nw_src=10.100.5.4,tp_dst=3333
+ actions=goto_table:100
+
+[[tcpudp-port-range]]
+====== TCP/UDP Port Range
+
+The TCP/UDP port range is supported with the help of port mask. This
+will dramatically reduce the number of flows required to cover a port
+range. The below 7 rules can cover a port range from 333 to 777.
+
+ cookie=0x0, duration=56.129s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x200/0xff00 actions=goto_table:100
+
+ cookie=0x0, duration=55.805s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x160/0xffe0 actions=goto_table:100
+
+ cookie=0x0, duration=55.587s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x300/0xfff8 actions=goto_table:100
+
+ cookie=0x0, duration=55.437s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x150/0xfff0 actions=goto_table:100
+
+ cookie=0x0, duration=55.282s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x14e/0xfffe actions=goto_table:100
+
+ cookie=0x0, duration=54.063s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=0x308/0xfffe actions=goto_table:100
+
+ cookie=0x0, duration=55.130s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,udp,dl_dst=fa:16:3e:f9:2c:42,nw_src=0.0.0.0/24,
+ tp_dst=333 actions=goto_table:100
+
+[[cidrremote-security-group]]
+===== CIDR/Remote Security Group
+
+ When adding a security group we can select the rule to applicable to a
+ set of CIDR or to a set of VMs which has a particular security group
+ associated with it.
+
+If CIDR is selected there will be only one flow rule added allowing the
+traffic from/to the IP’s belonging to that CIDR.
+
+ cookie=0x0, duration=202.516s, table=40, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,icmp,dl_src=fa:16:3e:ee:a5:ec,
+ nw_dst=0.0.0.0/24,icmp_type=2,icmp_code=4 actions=ct(commit),goto_table:50
+
+If a remote security group is selected a flow will be inserted for every
+vm which has that security group associated.
+
+ cookie=0x0, duration=60.701s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,udp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=2222 actions=ct(commit),goto_table:100
+
+ cookie=0x0, duration=58.988s, table=90, n_packets=0, n_bytes=0,
+ priority=61007,ct_state=+new+trk,tcp,dl_dst=fa:16:3e:22:59:2f,
+ nw_src=10.100.5.3,tp_dst=1111 actions=ct(commit),goto_table:100
+
+[[rules-supported-in-odl]]
+===== Rules supported in ODL
+
+The following rules are supported in the current implementation. The
+direction (ingress/egress) is always expected.
+
+.Table Supported Rules
+|====
+|Protocol |Port Range |IP Prefix |Remote Security Group supported
+|Any |Any |Any |Yes
+|TCP |1 - 65535 |0.0.0.0/0 |Yes
+|UDP |1 - 65535 |0.0.0.0/0 |Yes
+|ICMP |Any |0.0.0.0/0 |Yes
+|====
+
+Note : IPV6 and port-range feature is not supported as of today
--- /dev/null
+==== OVSDB Southbound Plugin
+
+The OVSDB Southbound Plugin provides support for managing OVS hosts
+via an OVSDB model in the MD-SAL which maps to important tables and
+attributes present in the Open_vSwitch schema. The OVSDB Southbound Plugin
+is able to connect actively or passively to OVS hosts and operate
+as the OVSDB manager of the OVS host. Using the OVSDB protocol it is able
+to manage the OVS database (OVSDB) on the OVS host as defined by the Open_vSwitch schema.
+
+===== OVSDB YANG Model
+
+The OVSDB Southbound Plugin provides a YANG model which is based on the
+abstract
+https://github.com/opendaylight/yangtools/blob/stable/beryllium/yang/yang-parser-impl/src/test/resources/ietf/network-topology%402013-10-21.yang[network topology model].
+
+The details of the OVSDB YANG model are defined in the
+https://github.com/opendaylight/ovsdb/blob/stable/beryllium/southbound/southbound-api/src/main/yang/ovsdb.yang[ovsdb.yang] file.
+
+The OVSDB YANG model defines three augmentations:
+
+*ovsdb-node-augmentation*::
+This augments the network-topology node and maps primarily to the Open_vSwitch table of
+the OVSDB schema. The ovsdb-node-augmentation is a representation of the OVS host. It contains the following attributes.
+ * *connection-info* - holds the local and remote IP address and TCP port numbers for the OpenDaylight to OVSDB node connections
+ * *db-version* - version of the OVSDB database
+ * *ovs-version* - version of OVS
+ * *list managed-node-entry* - a list of references to ovsdb-bridge-augmentation nodes, which are the OVS bridges managed by this OVSDB node
+ * *list datapath-type-entry* - a list of the datapath types supported by the OVSDB node (e.g. 'system', 'netdev') - depends on newer OVS versions
+ * *list interface-type-entry* - a list of the interface types supported by the OVSDB node (e.g. 'internal', 'vxlan', 'gre', 'dpdk', etc.) - depends on newer OVS verions
+ * *list openvswitch-external-ids* - a list of the key/value pairs in the Open_vSwitch table external_ids column
+ * *list openvswitch-other-config* - a list of the key/value pairs in the Open_vSwitch table other_config column
+ * *list managery-entry* - list of manager information entries and connection status
+ * *list qos-entries* - list of QoS entries present in the QoS table
+ * *list queues* - list of queue entries present in the queue table
+*ovsdb-bridge-augmentation*::
+This augments the network-topology node and maps to an specific bridge in the OVSDB
+bridge table of the associated OVSDB node. It contains the following attributes.
+ * *bridge-uuid* - UUID of the OVSDB bridge
+ * *bridge-name* - name of the OVSDB bridge
+ * *bridge-openflow-node-ref* - a reference (instance-identifier) of the OpenFlow node associated with this bridge
+ * *list protocol-entry* - the version of OpenFlow protocol to use with the OpenFlow controller
+ * *list controller-entry* - a list of controller-uuid and is-connected status of the OpenFlow controllers associated with this bridge
+ * *datapath-id* - the datapath ID associated with this bridge on the OVSDB node
+ * *datapath-type* - the datapath type of this bridge
+ * *fail-mode* - the OVSDB fail mode setting of this bridge
+ * *flow-node* - a reference to the flow node corresponding to this bridge
+ * *managed-by* - a reference to the ovsdb-node-augmentation (OVSDB node) that is managing this bridge
+ * *list bridge-external-ids* - a list of the key/value pairs in the bridge table external_ids column for this bridge
+ * *list bridge-other-configs* - a list of the key/value pairs in the bridge table other_config column for this bridge
+*ovsdb-termination-point-augmentation*::
+This augments the topology termination point model. The OVSDB Southbound
+Plugin uses this model to represent both the OVSDB port and OVSDB interface for
+a given port/interface in the OVSDB schema. It contains the following
+attributes.
+ * *port-uuid* - UUID of an OVSDB port row
+ * *interface-uuid* - UUID of an OVSDB interface row
+ * *name* - name of the port and interface
+ * *interface-type* - the interface type
+ * *list options* - a list of port options
+ * *ofport* - the OpenFlow port number of the interface
+ * *ofport_request* - the requested OpenFlow port number for the interface
+ * *vlan-tag* - the VLAN tag value
+ * *list trunks* - list of VLAN tag values for trunk mode
+ * *vlan-mode* - the VLAN mode (e.g. access, native-tagged, native-untagged, trunk)
+ * *list port-external-ids* - a list of the key/value pairs in the port table external_ids column for this port
+ * *list interface-external-ids* - a list of the key/value pairs in the interface table external_ids interface for this interface
+ * *list port-other-configs* - a list of the key/value pairs in the port table other_config column for this port
+ * *list interface-other-configs* - a list of the key/value pairs in the interface table other_config column for this interface
+ * *list inteface-lldp* - LLDP Auto Attach configuration for the interface
+ * *qos* - UUID of the QoS entry in the QoS table assigned to this port
+
+===== Getting Started
+
+To install the OVSDB Southbound Plugin, use the following command at the Karaf console:
+
+ feature:install odl-ovsdb-southbound-impl-ui
+
+After installing the OVSDB Southbound Plugin, and before any OVSDB topology nodes have been created,
+the OVSDB topology will appear as follows in the configuration and operational MD-SAL.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+ or
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1"
+ }
+ ]
+ }
+
+Where
+
+'<controller-ip>' is the IP address of the OpenDaylight controller
+
+===== OpenDaylight as the OVSDB Manager
+
+An OVS host is a system which is running the OVS software and is capable of being managed
+by an OVSDB manager. The OVSDB Southbound Plugin is capable of connecting to
+an OVS host and operating as an OVSDB manager. Depending on the configuration of the
+OVS host, the connection of OpenDaylight to the OVS host will be active or passive.
+
+===== Active Connection to OVS Hosts
+
+An active connection is when the OVSDB Southbound Plugin initiates the connection to
+an OVS host. This happens when the OVS host is configured to listen for the
+connection (i.e. the OVSDB Southbound Plugin is active the the OVS host is passive).
+The OVS host is configured with the following command:
+
+ sudo ovs-vsctl set-manager ptcp:6640
+
+This configures the OVS host to listen on TCP port 6640.
+
+The OVSDB Southbound Plugin can be configured via the configuration MD-SAL to
+actively connect to an OVS host.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb://HOST1",
+ "connection-info": {
+ "ovsdb:remote-port": "6640",
+ "ovsdb:remote-ip": "<ovs-host-ip>"
+ }
+ }
+ ]
+ }
+
+Where
+
+'<ovs-host-ip>' is the IP address of the OVS Host
+
+
+Note that the configuration assigns a 'node-id' of "ovsdb://HOST1" to the OVSDB node.
+This 'node-id' will be used as the identifier for this OVSDB node in the MD-SAL.
+
+Query the configuration MD-SAL for the OVSDB topology.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb://HOST1",
+ "ovsdb:connection-info": {
+ "remote-ip": "<ovs-host-ip>",
+ "remote-port": 6640
+ }
+ }
+ ]
+ }
+ ]
+ }
+
+As a result of the OVSDB node configuration being added to the configuration MD-SAL, the OVSDB
+Southbound Plugin will attempt to connect with the specified OVS host. If the connection is
+successful, the plugin will connect to the OVS host as an OVSDB manager, query the schemas and
+databases supported by the OVS host, and register to monitor changes made to the OVSDB tables
+on the OVS host. It will also set an external id key and value in the external-ids column
+of the Open_vSwtich table of the OVS host which identifies the MD-SAL instance identifier
+of the OVSDB node. This ensures that the OVSDB node will use the same 'node-id' in both the
+configuration and operational MD-SAL.
+
+ "opendaylight-iid" = "instance identifier of OVSDB node in the MD-SAL"
+
+When the OVS host sends the OVSDB Southbound Plugin the first update message after the monitoring has
+been established, the plugin will populate the operational MD-SAL with the information it
+receives from the OVS host.
+
+Query the operational MD-SAL for the OVSDB topology.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb://HOST1",
+ "ovsdb:openvswitch-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']"
+ }
+ ],
+ "ovsdb:connection-info": {
+ "local-ip": "<controller-ip>",
+ "remote-port": 6640,
+ "remote-ip": "<ovs-host-ip>",
+ "local-port": 39042
+ },
+ "ovsdb:ovs-version": "2.3.1-git4750c96",
+ "ovsdb:manager-entry": [
+ {
+ "target": "ptcp:6640",
+ "connected": true,
+ "number_of_connections": 1
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+
+
+To disconnect an active connection, just delete the configuration MD-SAL entry.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1
+
+Note in the above example, that '/' characters which are part of the 'node-id' are specified in hexadecimal format as "%2F".
+
+===== Passive Connection to OVS Hosts
+
+A passive connection is when the OVS host initiates the connection to
+the OVSDB Southbound Plugin. This happens when the OVS host is configured to connect
+to the OVSDB Southbound Plugin.
+The OVS host is configured with the following command:
+
+ sudo ovs-vsctl set-manager tcp:<controller-ip>:6640
+
+The OVSDB Southbound Plugin is configured to listen for OVSDB connections
+on TCP port 6640. This value can be changed by editing the "./karaf/target/assembly/etc/custom.properties"
+file and changing the value of the "ovsdb.listenPort" attribute.
+
+When a passive connection is made, the OVSDB node will appear first in the operational MD-SAL.
+If the Open_vSwitch table does not contain an external-ids value of 'opendaylight-iid', then
+the 'node-id' of the new OVSDB node will be created in the format:
+
+ "ovsdb://uuid/<actual UUID value>"
+
+If there an 'opendaylight-iid' value was already present in the external-ids column, then the
+instance identifier defined there will be used to create the 'node-id' instead.
+
+Query the operational MD-SAL for an OVSDB node after a passive connection.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+
+Result Body:
+
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb://uuid/163724f4-6a70-428a-a8a0-63b2a21f12dd",
+ "ovsdb:openvswitch-external-ids": [
+ {
+ "external-id-key": "system-id",
+ "external-id-value": "ecf160af-e78c-4f6b-a005-83a6baa5c979"
+ }
+ ],
+ "ovsdb:connection-info": {
+ "local-ip": "<controller-ip>",
+ "remote-port": 46731,
+ "remote-ip": "<ovs-host-ip>",
+ "local-port": 6640
+ },
+ "ovsdb:ovs-version": "2.3.1-git4750c96",
+ "ovsdb:manager-entry": [
+ {
+ "target": "tcp:10.11.21.7:6640",
+ "connected": true,
+ "number_of_connections": 1
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+
+Take note of the 'node-id' that was created in this case.
+
+===== Manage Bridges
+
+The OVSDB Southbound Plugin can be used to manage bridges on an OVS host.
+
+This example shows how to add a bridge to the OVSDB node 'ovsdb://HOST1'.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb://HOST1/bridge/brtest",
+ "ovsdb:bridge-name": "brtest",
+ "ovsdb:protocol-entry": [
+ {
+ "protocol": "ovsdb:ovsdb-bridge-protocol-openflow-13"
+ }
+ ],
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']"
+ }
+ ]
+ }
+
+Notice that the 'ovsdb:managed-by' attribute is specified in the command. This indicates the association of the new bridge node with its OVSDB node.
+
+Bridges can be updated. In the following example, OpenDaylight is configured to be the OpenFlow controller for the bridge.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb://HOST1/bridge/brtest",
+ "ovsdb:bridge-name": "brtest",
+ "ovsdb:controller-entry": [
+ {
+ "target": "tcp:<controller-ip>:6653"
+ }
+ ],
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']"
+ }
+ ]
+ }
+
+If the OpenDaylight OpenFlow Plugin is installed, then checking on the OVS host will show that OpenDaylight has successfully connected as the controller for the bridge.
+
+ $ sudo ovs-vsctl show
+ Manager "ptcp:6640"
+ is_connected: true
+ Bridge brtest
+ Controller "tcp:<controller-ip>:6653"
+ is_connected: true
+ Port brtest
+ Interface brtest
+ type: internal
+ ovs_version: "2.3.1-git4750c96"
+
+Query the operational MD-SAL to see how the bridge appears.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/
+
+Result Body:
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb://HOST1/bridge/brtest",
+ "ovsdb:bridge-name": "brtest",
+ "ovsdb:datapath-type": "ovsdb:datapath-type-system",
+ "ovsdb:datapath-id": "00:00:da:e9:0c:08:2d:45",
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1']",
+ "ovsdb:bridge-external-ids": [
+ {
+ "bridge-external-id-key": "opendaylight-iid",
+ "bridge-external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1/bridge/brtest']"
+ }
+ ],
+ "ovsdb:protocol-entry": [
+ {
+ "protocol": "ovsdb:ovsdb-bridge-protocol-openflow-13"
+ }
+ ],
+ "ovsdb:bridge-uuid": "080ce9da-101e-452d-94cd-ee8bef8a4b69",
+ "ovsdb:controller-entry": [
+ {
+ "target": "tcp:10.11.21.7:6653",
+ "is-connected": true,
+ "controller-uuid": "c39b1262-0876-4613-8bfd-c67eec1a991b"
+ }
+ ],
+ "termination-point": [
+ {
+ "tp-id": "brtest",
+ "ovsdb:port-uuid": "c808ae8d-7af2-4323-83c1-e397696dc9c8",
+ "ovsdb:ofport": 65534,
+ "ovsdb:interface-type": "ovsdb:interface-type-internal",
+ "ovsdb:interface-uuid": "49e9417f-4479-4ede-8faf-7c873b8c0413",
+ "ovsdb:name": "brtest"
+ }
+ ]
+ }
+ ]
+ }
+
+Notice that just like with the OVSDB node, an 'opendaylight-iid' has been added to the external-ids column of the bridge since it was created via the configuration MD-SAL.
+
+
+A bridge node may be deleted as well.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest
+
+===== Manage Ports
+
+Similarly, ports may be managed by the OVSDB Southbound Plugin.
+
+This example illustrates how a port and various attributes may be created on a bridge.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:options": [
+ {
+ "ovsdb:option": "remote_ip",
+ "ovsdb:value" : "10.10.14.11"
+ }
+ ],
+ "ovsdb:name": "testport",
+ "ovsdb:interface-type": "ovsdb:interface-type-vxlan",
+ "tp-id": "testport",
+ "vlan-tag": "1",
+ "trunks": [
+ {
+ "trunk": "5"
+ }
+ ],
+ "vlan-mode":"access"
+ }
+ ]
+ }
+
+
+Ports can be updated - add another VLAN trunk.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport",
+ "trunks": [
+ {
+ "trunk": "5"
+ },
+ {
+ "trunk": "500"
+ }
+ ]
+ }
+ ]
+ }
+
+Query the operational MD-SAL for the port.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest/termination-point/testport/
+
+Result Body:
+
+ {
+ "termination-point": [
+ {
+ "tp-id": "testport",
+ "ovsdb:port-uuid": "b1262110-2a4f-4442-b0df-84faf145488d",
+ "ovsdb:options": [
+ {
+ "option": "remote_ip",
+ "value": "10.10.14.11"
+ }
+ ],
+ "ovsdb:port-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb://HOST1/bridge/brtest']/network-topology:termination-point[network-topology:tp-id='testport']"
+ }
+ ],
+ "ovsdb:interface-type": "ovsdb:interface-type-vxlan",
+ "ovsdb:trunks": [
+ {
+ "trunk": 5
+ },
+ {
+ "trunk": 500
+ }
+ ],
+ "ovsdb:vlan-mode": "access",
+ "ovsdb:vlan-tag": 1,
+ "ovsdb:interface-uuid": "7cec653b-f407-45a8-baec-7eb36b6791c9",
+ "ovsdb:name": "testport",
+ "ovsdb:ofport": 1
+ }
+ ]
+ }
+
+Remember that the OVSDB YANG model includes both OVSDB port and interface table attributes in the termination-point augmentation.
+Both kinds of attributes can be seen in the examples above. Again, note the creation of an 'opendaylight-iid' value in the external-ids column of the port table.
+
+Delete a port.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:%2F%2FHOST1%2Fbridge%2Fbrtest2/termination-point/testport/
+
+
+
+
+===== Overview of QoS and Queue
+The OVSDB Southbound Plugin provides the capability of managing the QoS
+and Queue tables on an OVS host with OpenDaylight configured
+as the OVSDB manager.
+
+====== QoS and Queue Tables in OVSDB
+The OVSDB includes a QoS and Queue table. Unlike most of the other tables
+in the OVSDB, except the Open_vSwitch table, the QoS and Queue tables are
+"root set" tables, which means that entries, or rows, in these tables are
+not automatically deleted if they can not be reached directly or indirectly
+from the Open_vSwitch table. This means that QoS entries can exist and be
+managed independently of whether or not they are referenced in a Port entry.
+Similarly, Queue entries can be managed independently of whether or not they are
+referenced by a QoS entry.
+
+
+====== Modelling of QoS and Queue Tables in OpenDaylight MD-SAL
+
+Since the QoS and Queue tables are "root set" tables, they are modeled
+in the OpenDaylight MD-SAL as lists which are part of the attributes
+of the OVSDB node model.
+
+The MD-SAL QoS and Queue models have an additonal identifier attribute per
+entry (e.g. "qos-id" or "queue-id") which is not present
+in the OVSDB schema. This identifier is used by the MD-SAL as a key for referencing
+the entry. If the entry is created originally from the
+configuration MD-SAL, then the value of the identifier is whatever is specified
+by the configuration. If the entry is created on the OVSDB node and received
+by OpenDaylight in an operational update, then the id will be created in
+the following format.
+
+ "queue-id": "queue://<UUID>"
+ "qos-id": "qos://<UUID>"
+
+The UUID in the above identifiers is the actual UUID of the entry in the
+OVSDB database.
+
+When the QoS or Queue entry is created by the configuration MD-SAL, the
+identifier will be configured as part of the external-ids column of the
+entry. This will ensure that the corresponding entry that is created
+in the operational MD-SAL uses the same identifier.
+
+ "queues-external-ids": [
+ {
+ "queues-external-id-key": "opendaylight-queue-id",
+ "queues-external-id-value": "QUEUE-1"
+ }
+ ]
+
+See more in the examples that follow in this section.
+
+The QoS schema in OVSDB currently defines two types of QoS entries.
+
+* linux-htb
+* linux-hfsc
+
+These QoS types are defined in the QoS model. Additional types will
+need to be added to the model in order to be supported. See the examples
+that folow for how the QoS type is specified in the model.
+
+QoS entries can be configured with addtional attritubes such as "max-rate".
+These are configured via the 'other-config' column of the QoS entry. Refer
+to OVSDB schema (in the reference section below) for all of the relevant
+attributes that can be configured. The examples in the rest of this section
+will demonstrate how the other-config column may be configured.
+
+Similarly, the Queue entries may be configured with additional attributes
+via the other-config column.
+
+===== Managing QoS and Queues via Configuration MD-SAL
+This section will show some examples on how to manage QoS and
+Queue entries via the configuration MD-SAL. The examples will
+be illustrated by using RESTCONF (see
+https://github.com/opendaylight/ovsdb/blob/stable/beryllium/resources/commons/Qos-and-Queue-Collection.json.postman_collection[QoS and Queue Postman Collection] ).
+
+A pre-requisite for managing QoS and Queue entries is that the
+OVS host must be present in the configuration MD-SAL.
+
+For the following examples, the following OVS host is configured.
+
+HTTP POST:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+
+Body:
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ "connection-info": {
+ "ovsdb:remote-ip": "<ovs-host-ip>",
+ "ovsdb:remote-port": "<ovs-host-ovsdb-port>"
+ }
+ }
+ ]
+ }
+
+Where
+
+* '<controller-ip>' is the IP address of the OpenDaylight controller
+* '<ovs-host-ip>' is the IP address of the OVS host
+* '<ovs-host-ovsdb-port>' is the TCP port of the OVSDB server on the OVS host (e.g. 6640)
+
+This command creates an OVSDB node with the node-id "ovsdb:HOST1". This OVSDB node will be used in the following
+examples.
+
+QoS and Queue entries can be created and managed without a port, but ultimately, QoS entries are
+associated with a port in order to use them. For the following examples a test bridge and port will
+be created.
+
+Create the test bridge.
+
+HTTP PUT
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test
+
+Body:
+
+ {
+ "network-topology:node": [
+ {
+ "node-id": "ovsdb:HOST1/bridge/br-test",
+ "ovsdb:bridge-name": "br-test",
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1']"
+ }
+ ]
+ }
+
+Create the test port (which is modeled as a termination point in the OpenDaylight MD-SAL).
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport"
+ }
+ ]
+ }
+
+If all of the previous steps were successful, a query of the operational MD-SAL should look something like the following results. This indicates that the configuration commands have been successfully instantiated on the OVS host.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test
+
+Result Body:
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1/bridge/br-test",
+ "ovsdb:bridge-name": "br-test",
+ "ovsdb:datapath-type": "ovsdb:datapath-type-system",
+ "ovsdb:managed-by": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1']",
+ "ovsdb:datapath-id": "00:00:8e:5d:22:3d:09:49",
+ "ovsdb:bridge-external-ids": [
+ {
+ "bridge-external-id-key": "opendaylight-iid",
+ "bridge-external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1/bridge/br-test']"
+ }
+ ],
+ "ovsdb:bridge-uuid": "3d225d8d-d060-4909-93ef-6f4db58ef7cc",
+ "termination-point": [
+ {
+ "tp-id": "br=-est",
+ "ovsdb:port-uuid": "f85f7aa7-4956-40e4-9c94-e6ca2d5cd254",
+ "ovsdb:ofport": 65534,
+ "ovsdb:interface-type": "ovsdb:interface-type-internal",
+ "ovsdb:interface-uuid": "29ff3692-6ed4-4ad7-a077-1edc277ecb1a",
+ "ovsdb:name": "br-test"
+ },
+ {
+ "tp-id": "testport",
+ "ovsdb:port-uuid": "aa79a8e2-147f-403a-9fa9-6ee5ec276f08",
+ "ovsdb:port-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1/bridge/br-test']/network-topology:termination-point[network-topology:tp-id='testport']"
+ }
+ ],
+ "ovsdb:interface-uuid": "e96f282e-882c-41dd-a870-80e6b29136ac",
+ "ovsdb:name": "testport"
+ }
+ ]
+ }
+ ]
+ }
+
+====== Create Queue
+Create a new Queue in the configuration MD-SAL.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:queues/QUEUE-1/
+
+Body:
+
+ {
+ "ovsdb:queues": [
+ {
+ "queue-id": "QUEUE-1",
+ "dscp": 25,
+ "queues-other-config": [
+ {
+ "queue-other-config-key": "max-rate",
+ "queue-other-config-value": "3600000"
+ }
+ ]
+ }
+ ]
+ }
+
+
+====== Query Queue
+Now query the operational MD-SAL for the Queue entry.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:queues/QUEUE-1/
+
+Result Body:
+
+ {
+ "ovsdb:queues": [
+ {
+ "queue-id": "QUEUE-1",
+ "queues-other-config": [
+ {
+ "queue-other-config-key": "max-rate",
+ "queue-other-config-value": "3600000"
+ }
+ ],
+ "queues-external-ids": [
+ {
+ "queues-external-id-key": "opendaylight-queue-id",
+ "queues-external-id-value": "QUEUE-1"
+ }
+ ],
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69",
+ "dscp": 25
+ }
+ ]
+ }
+
+====== Create QoS
+
+Create a QoS entry. Note that the UUID of the Queue entry, obtained by querying the operational MD-SAL of the Queue entry, is
+specified in the queue-list of the QoS entry. Queue entries may be added to the QoS entry at the creation of the QoS entry, or
+by a subsequent update to the QoS entry.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/
+
+Body:
+
+ {
+ "ovsdb:qos-entries": [
+ {
+ "qos-id": "QOS-1",
+ "qos-type": "ovsdb:qos-type-linux-htb",
+ "qos-other-config": [
+ {
+ "other-config-key": "max-rate",
+ "other-config-value": "4400000"
+ }
+ ],
+ "queue-list": [
+ {
+ "queue-number": "0",
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69"
+ }
+ ]
+ }
+ ]
+ }
+
+====== Query QoS
+
+Query the operational MD-SAL for the QoS entry.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/
+
+Result Body:
+
+ {
+ "ovsdb:qos-entries": [
+ {
+ "qos-id": "QOS-1",
+ "qos-other-config": [
+ {
+ "other-config-key": "max-rate",
+ "other-config-value": "4400000"
+ }
+ ],
+ "queue-list": [
+ {
+ "queue-number": 0,
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69"
+ }
+ ],
+ "qos-type": "ovsdb:qos-type-linux-htb",
+ "qos-external-ids": [
+ {
+ "qos-external-id-key": "opendaylight-qos-id",
+ "qos-external-id-value": "QOS-1"
+ }
+ ],
+ "qos-uuid": "90ba9c60-3aac-499d-9be7-555f19a6bb31"
+ }
+ ]
+ }
+
+====== Add QoS to a Port
+Update the termination point entry to include the UUID of the QoS entry, obtained by querying the operational MD-SAL, to associate a QoS entry with a port.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport",
+ "qos": "90ba9c60-3aac-499d-9be7-555f19a6bb31"
+ }
+ ]
+ }
+
+====== Query the Port
+Query the operational MD-SAL to see how the QoS entry appears in the termination point model.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Result Body:
+
+ {
+ "termination-point": [
+ {
+ "tp-id": "testport",
+ "ovsdb:port-uuid": "aa79a8e2-147f-403a-9fa9-6ee5ec276f08",
+ "ovsdb:port-external-ids": [
+ {
+ "external-id-key": "opendaylight-iid",
+ "external-id-value": "/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1/bridge/br-test']/network-topology:termination-point[network-topology:tp-id='testport']"
+ }
+ ],
+ "ovsdb:qos": "90ba9c60-3aac-499d-9be7-555f19a6bb31",
+ "ovsdb:interface-uuid": "e96f282e-882c-41dd-a870-80e6b29136ac",
+ "ovsdb:name": "testport"
+ }
+ ]
+ }
+
+
+====== Query the OVSDB Node
+Query the operational MD-SAL for the OVS host to see how the QoS and Queue entries appear as lists in the OVS node model.
+
+HTTP GET:
+
+ http://<controller-ip>:8181/restconf/operational/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/
+
+Result Body (edited to only show information relevant to the QoS and Queue entries):
+
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ <content edited out>
+ "ovsdb:queues": [
+ {
+ "queue-id": "QUEUE-1",
+ "queues-other-config": [
+ {
+ "queue-other-config-key": "max-rate",
+ "queue-other-config-value": "3600000"
+ }
+ ],
+ "queues-external-ids": [
+ {
+ "queues-external-id-key": "opendaylight-queue-id",
+ "queues-external-id-value": "QUEUE-1"
+ }
+ ],
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69",
+ "dscp": 25
+ }
+ ],
+ "ovsdb:qos-entries": [
+ {
+ "qos-id": "QOS-1",
+ "qos-other-config": [
+ {
+ "other-config-key": "max-rate",
+ "other-config-value": "4400000"
+ }
+ ],
+ "queue-list": [
+ {
+ "queue-number": 0,
+ "queue-uuid": "83640357-3596-4877-9527-b472aa854d69"
+ }
+ ],
+ "qos-type": "ovsdb:qos-type-linux-htb",
+ "qos-external-ids": [
+ {
+ "qos-external-id-key": "opendaylight-qos-id",
+ "qos-external-id-value": "QOS-1"
+ }
+ ],
+ "qos-uuid": "90ba9c60-3aac-499d-9be7-555f19a6bb31"
+ }
+ ]
+ <content edited out>
+ }
+ ]
+ }
+
+
+====== Remove QoS from a Port
+This example removes a QoS entry from the termination point and associated port. Note that this is a PUT command on the termination point with the
+QoS attribute absent. Other attributes of the termination point should be included in the body of the command so that they are not inadvertantly removed.
+
+HTTP PUT:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1%2Fbridge%2Fbr-test/termination-point/testport/
+
+Body:
+
+ {
+ "network-topology:termination-point": [
+ {
+ "ovsdb:name": "testport",
+ "tp-id": "testport"
+ }
+ ]
+ }
+
+====== Remove a Queue from QoS
+
+This example removes the specific Queue entry from the queue list in the QoS entry. The queue entry is specified by the queue number, which is "0" in this example.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/queue-list/0/
+
+====== Remove Queue
+Once all references to a specific queue entry have been removed from QoS entries, the Queue itself can be removed.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:queues/QUEUE-1/
+
+====== Remove QoS
+The QoS entry may be removed when it is no longer referenced by any ports.
+
+HTTP DELETE:
+
+ http://<controller-ip>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/node/ovsdb:HOST1/ovsdb:qos-entries/QOS-1/
+
+
+===== References
+http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf[Openvswitch schema]
+
+https://github.com/opendaylight/ovsdb/blob/stable/beryllium/resources/commons[OVSDB and Netvirt Postman Collection]
+
+++ /dev/null
-== TCP-MD5
-
-The User Guide for TCP-MD5 can be found on the OpenDaylight wiki here: https://wiki.opendaylight.org/view/TCPMD5:Helium_User_Guide
-
+++ /dev/null
-== TCPMD5 User Guide
-
-This user guide describes the configuration for Border Gateway Protocol (BGP) and Path Computation Element Protocol (PCEP)
-using MD5 authentication. It is destined for users who build applications using MD5 library.
-
-=== Overview
-
-The TCPMD5 library provides access to link:http://tools.ietf.org/html/rfc2385[RFC-2385] MD5 Signature Option on operating systems which support it in their TCP stack.
-This option has been historically used to protect BGP sessions, but is equally useful for protecting PCEP sessions.
-
-IMPORTANT: *Before you continue with steps in this user guide, make sure BGP and/or PCEP is configured properly.*
-
-TCPMD5 authentication is *disabled* by default. To enable it (for both protocols), uncomment the contents of _20-tcpmd5.xml_.
-You can find this configuration file in your OpenDaylight directory _etc/opendaylight/karaf_ .
-
-CAUTION: [big]#*If the connection can not be established, there are no warnings or errors,
-so be sure to double check your configuration and passwords.*#
-
-=== Configuring TCPMD5 manually
-
-==== BGP
-
-IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.*
-
-To enable TCPMD5 for the BGP protocol, perform the following steps:
-
-. In _31-bgp.xml_ uncomment the TCP MD5 section:
-+
-[source,xml]
-----
-<!--
- Uncomment this block to enable TCPMD5 Signature support
--->
-<md5-channel-factory>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-channel-factory</type>
- <name>md5-client-channel-factory</name>
-</md5-channel-factory>
-<md5-server-channel-factory>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
- <name>md5-server-channel-factory</name>
-</md5-server-channel-factory>
-----
-. In _41-bgp-example.xml_ add <password> tag to module example-bgp-peer.
-+
-[source,xml]
-----
-<!--
- For TCPMD5 support, make sure the dispatcher associated with the rib has
- "md5-channel-factory" attribute set and then add a "password" attribute here.
- Note that the peer has to have the same password configured, otherwise the
- connection will not be established.
--->
-<module>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-peer</type>
- <name>example-bgp-peer</name>
- <host>10.25.2.27</host>
- <holdtimer>180</holdtimer>
- <rib>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:cfg">prefix:rib</type>
- <name>example-bgp-rib</name>
- </rib>
- <advertized-table>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
- <name>ipv4-unicast</name>
- </advertized-table>
- <advertized-table>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
- <name>ipv6-unicast</name>
- </advertized-table>
- <advertized-table>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">prefix:bgp-table-type</type>
- <name>linkstate</name>
- </advertized-table>
- <password>changeme</password>
-</module>
-----
-
-NOTE: Setting a password on other BGP devices is out of scope for this document.
-
-==== PCEP
-
-IMPORTANT: *Make sure your _20-tcpmd5.xml_ has its content uncommented.*
-
-To enable TCPMD5 for PCE protocol, perform the following steps:
-
-. In _32-pcep.xml_ uncomment the TCPMD5 section:
-+
-[source,xml]
-----
-<!--
- Uncomment this block to enable TCPMD5 Signature support
--->
-<md5-channel-factory>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-channel-factory</type>
- <name>md5-client-channel-factory</name>
-</md5-channel-factory>
-<md5-server-channel-factory>
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
- <name>md5-server-channel-factory</name>
-</md5-server-channel-factory>
-----
-
-. In _39-pcep-provider.xml_ uncomment following section:
-+
-[source,xml]
-----
-<!--
- For TCPMD5 support make sure the dispatcher has the "md5-server-channel-factory"
- attribute set and then set the appropriate client entries here. Note that if this
- option is configured, the PCCs connecting here must have the same password,
- otherwise they will not be able to connect.
- -->
- <client>
- <address>192.0.2.2</address>
- <password>changeme</password>
- </client>
-----
-
-IMPORTANT: *Change the <address> value to the address of PCC, the one that is advertized to PCE and provide password matching the one set on PCC.*
-
-NOTE: Setting a password on PCC is out of scope for this document.
-
-
-=== Configuring TCPMD5 through RESTCONF
-
-IMPORTANT: Before you start, make sure, you have installed features for BGP and/or PCEP. Install another feature, that will provide you the access to _restconf/config/_ URLs.
-[source,xml]
-----
-feature:install odl-netconf-connector-all
-----
-
-This log message indicates successful start of netconf-connector: _Netconf connector initialized successfully_
-
-- To check what modules you have currently configured, check following link: http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
-
-- To check what services you have currently configured, check following link: http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:services/
-
-These URLs are also used to POST new configuration. If you want to change any other configuration that is listed here,
-make sure you include the correct namespaces. The correct namespace for <module> is always _urn:opendaylight:params:xml:ns:yang:controller:config_.
-The namespace for any other fields can be found by finding given module in configuration yang files.
-
-NOTE: RESTCONF will tell you if some namespace is wrong.
-
-To enable TCPMD5 for either one of the protocols, enable TCPMD5 modules and services:
-
-CAUTION: You have to make *separate* POST requests for each module/service!
-
-[big]#*URL:# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/
-
-[big]#*POST:*#
-
-[source,xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:jni:cfg">x:native-key-access-factory</type>
- <name>global-key-access-factory</name>
-</module>
-----
-[source,xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-client-channel-factory</type>
- <name>md5-client-channel-factory</name>
- <key-access-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
- <name>global-key-access-factory</name>
- </key-access-factory>
-</module>
-----
-[source,xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory-impl</type>
- <name>md5-server-channel-factory</name>
- <server-key-access-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
- <name>global-key-access-factory</name>
- </server-key-access-factory>
-</module>
-----
-
-[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:services/
-
-[big]#*POST:*#
-
-[source,xml]
-----
-<service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:cfg">x:key-access-factory</type>
- <instance>
- <name>global-key-access-factory</name>
- <provider>/modules/module[type='native-key-access-factory'][name='global-key-access-factory']</provider>
- </instance>
-</service>
-----
-[source,xml]
-----
-<service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
- <instance>
- <name>md5-client-channel-factory</name>
- <provider>/modules/module[type='md5-client-channel-factory'][name='md5-client-channel-factory']</provider>
- </instance>
-</service>
-----
-[source,xml]
-----
-<service xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">prefix:md5-server-channel-factory</type>
- <instance>
- <name>md5-server-channel-factory</name>
- <provider>/modules/module[type='md5-server-channel-factory-impl'][name='md5-server-channel-factory']</provider>
- </instance>
-</service>
-----
-
-==== BGP
-
-CAUTION: You have to introduce modules and services mentioned in the previous section. Your BGP client needs to be *ALREADY* configured. Check User Guide for BGP.
-
-CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
-
-. Enabling TCPMD5 in BGP configuration:
-+
-[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-bgp-rib-impl-cfg:bgp-dispatcher-impl/global-bgp-dispatcher
-
-[big]#*PUT:*#
-
-[source,xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">x:bgp-dispatcher-impl</type>
- <name>global-bgp-dispatcher</name>
- <md5-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
- <name>md5-client-channel-factory</name>
- </md5-channel-factory>
- <md5-server-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-server-channel-factory</type>
- <name>md5-server-channel-factory</name>
- </md5-server-channel-factory>
- ...
-</module>
-----
-
-CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
-
-. Set password:
-+
-[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-bgp-rib-impl-cfg:bgp-peer/example-bgp-peer
-
-[big]#*PUT:*#
-
-[source,xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">x:bgp-peer</type>
- <name>example-bgp-peer</name>
- <password xmlns="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:impl">changeme</password>
- ...
-</module>
-----
-
-==== PCEP
-
-CAUTION: You have to introduce modules and services mentioned in the previous section.
-
-CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
-
-. Enable TCPMD5 in PCEP configuration:
-+
-[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-pcep-impl-cfg:pcep-dispatcher-impl/global-pcep-dispatcher
-
-[big]#*PUT:*#
-
-[source,xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">x:pcep-dispatcher-impl</type>
- <name>global-pcep-dispatcher</name>
- <md5-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-channel-factory</type>
- <name>md5-client-channel-factory</name>
- </md5-channel-factory>
- <md5-server-channel-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:impl">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:tcpmd5:netty:cfg">x:md5-server-channel-factory</type>
- <name>md5-server-channel-factory</name>
- </md5-server-channel-factory>
- ...
-</module>
-----
-
-CAUTION: You need to copy and paste FULL module in order to replace it. This guide shows you part you need to change.
-
-. Set password:
-+
-[big]#*URL:*# http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/odl-pcep-impl-cfg:pcep-topology-provider/pcep-topology
-
-[big]#*PUT:*#
-[source,xml]
-----
-<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
- <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">x:pcep-topology-provider</type>
- <name>pcep-topology</name>
- <client xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">
- <address xmlns="urn:opendaylight:params:xml:ns:yang:controller:pcep:topology:provider">192.0.2.2</address> <!--CHANGE THE VALUE -->
- <password>changeme</password> <!--CHANGE THE VALUE -->
- </client>
- ...
-</module>
-----
-sphinx
-sphinx_bootstrap_theme
+sphinx>=1.4.4
+sphinx_bootstrap_theme>=0.4.11
robotframework
+
[testenv:docs]
deps = -rrequirements.txt
-commands = sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+commands =
+ sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+ echo "Generated docs available in {toxinidir}/docs/_build/html"
+whitelist_externals = echo
[testenv:docs-linkcheck]
deps = -rrequirements.txt
Code Review / docs.git / commitdiff
