--- /dev/null
+[submodule "source/submodules/releng/builder"]
+ path = docs/submodules/releng/builder
+ url = ../releng/builder
+ branch = master
--- /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
+#!/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
+
+# 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 = []
+
+# 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 = '0.3.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.3.0'
+
+# 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 = 'alabaster'
+
+# 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 = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#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 = None
+
+# 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
--- /dev/null
+API
+===
+
+We are in the process of creating automatically generated API documentation for
+all of OpenDaylight. The following are links to the preliminary documentation
+that you can reference. We will continue to add more API documentation as it
+becomes available.
+
+* mdsal_
+* odlparent_
+* yangtools_
+
+.. _mdsal: https://nexus.opendaylight.org/content/sites/site/org.opendaylight.mdsal/beryllium/apidocs/
+.. _odlparent: https://nexus.opendaylight.org/content/sites/site/org.opendaylight.odlparent/beryllium/apidocs/index.html
+.. _yangtools: https://nexus.opendaylight.org/content/sites/site/org.opendaylight.yangtools/beryllium/apidocs/index.html
--- /dev/null
+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
+in a subsequent section, but for now familiarize yourself with the information
+below.
+
+* To date, OpenDaylight developers have formed more than 50 projects to address
+ ways to extend network functionality. The projects are a formal structure for
+ developers from the community to meet, document release plans, code, and
+ release the functionality they create in an OpenDaylight release.
+
+ *The typical OpenDaylight user will not join a project team*, but you should
+ know what projects are as we refer to their activities and the functionality
+ they create. The Karaf features to install that functionality often share the
+ project team’s name.
+
+* **Apache Karaf** provides a lightweight runtime to install the Karaf features
+ you want to implement and is included in the OpenDaylight platform software.
+ By default, OpenDaylight has no pre-installed features.
+* After installing OpenDaylight, you install your selected features using the
+ Karaf console to expand networking capabilities. In the Karaf feature list
+ below are the ones you’re most likely to use when creating your network
+ environment.
+
+ As a short example of installing a Karaf feature, OpenDaylight Beryllium
+ offers Application Layer Traffic Optimization (ALTO). The Karaf feature to
+ install ALTO is odl-alto-all. On the Karaf console, the command to install it
+ is:
+
+ feature:install odl-alto-all
+
+* **DLUX** is a web-based interface that OpenDaylight provides for you to manage
+ your network. Its Karaf feature installation name is “odl-dlux-core”.
+
+ a. DLUX draws information from OpenDaylight’s topology and host databases to
+ display the following information:
+
+ i. The network
+ #. Flow statistics
+ #. Host locations
+
+ #. To enable the DLUX UI after installing OpenDaylight, run:
+
+ feature:install odl-dlux-core
+
+ on the Karaf console.
+
+* **Network embedded Experience (NeXt)** is a developer toolkit that provides
+ tools to draw network-centric topology UI elements that offer visualizations
+ of the following:
+
+ a. Large complex network topologies
+ #. Aggregated network nodes
+ #. Traffic/path/tunnel/group visualizations
+ #. Different layout algorithms
+ #. Map overlays
+ #. Preset user-friendly interactions
+
+ NeXt can work with DLUX to build OpenDaylight applications. Check out the
+ NeXt_demo_ for more information on the interface.
+
+* Model-Driven Service Abstraction Layer (MD-SAL) is the OpenDaylight framework
+ that allows developers to create new Karaf features in the form of services
+ and protocol drivers and connects them to one another. You can think of the
+ MD-SAL as having the following two components:
+
+ a. A shared datastore that maintains the following tree-based structures:
+
+ i. The Config Datastore, which maintains a representation of the desired
+ network state.
+ #. The Operational Datastore, which is a representation of the actual
+ network state based on data from the managed network elements.
+
+ b. A message bus that provides a way for the various services and protocol
+ drivers to notify and communicate with one another.
+
+* If you’re interacting with OpenDaylight through DLUX or the REST APIs while
+ using the the OpenDaylight interfaces, the microservices architecture allows
+ you to select available services, protocols, and REST APIs.
+
+.. _NeXt_demo: https://www.youtube.com/watch?v=gBsUDu8aucs
--- /dev/null
+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
+requirements and transforms the details of the desired state to OpenDaylight.
+NIC has four features:
+
+* odl-nic-core-hazelcast: Provides the following:
+
+ * A distributed intent mapping service implemented using hazelcast, which
+ stores metadata needed to process Intent correctly
+ * An intent REST API to external applications for Create, Read, Update, and
+ Delete (CRUD) operations on intents, conflict resolution, and event handling
+
+* odl-nic-core-mdsal: Provides the following:
+
+ * A distributed Intent mapping service implemented using MD-SAL, which stores
+ metadata needed to process Intent correctly
+ * An Intent rest API to external applications for CRUD operations on Intents,
+ conflict resolution, and event handling
+
+* odl-nic-console: Provides a Karaf CLI extension for Intent CRUD operations
+ and mapping service operations
+* Four renderers to provide specific implementations to render the Intent:
+
+ * Virtual Tenant Network Renderer
+ * Group Based Policy Renderer
+ * OpenFlow Renderer
+ * 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
+specified and don’t require OpenDaylight to make continuous fetch requests.
+YANG-PUBSUB is developed as a Java project. Development requires Maven version
+3.1.1 or later.
--- /dev/null
+Getting Started Guide
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ introduction
+ overview
+ who_should_use
+ concepts_and_tools
+ karaf_features
+ experimental_features
+ other_features
+ api
+ installing_opendaylight
--- /dev/null
+Installing OpenDaylight
+=======================
+
+You complete the following steps to install your networking environment, with
+specific instructions provided in the subsections below.
+
+Before detailing the instructions for these, we address the following:
+Java Runtime Environment (JRE) and operating system information
+Target environment
+Known issues and limitations
+
+
+Install OpenDaylight
+--------------------
+
+Install the Karaf features
+--------------------------
+To install a feature, use the following command, where feature1 is the feature
+name listed in the table below::
+
+ feature:install <feature1>
+
+You can install multiple features using the following command::
+
+
+ feature:install <feature1> <feature2> ... <featureN-name>
+
+.. note:: For compatibility reasons, you cannot enable all Karaf features
+ simultaneously. The table below documents feature installation names and
+ known incompatibilities.Compatibility values indicate the following:
+
+* *all* - the feature can be run with other features.
+* *self+all* - the feature can be installed with other features with a value of
+ *all*, but may interact badly with other features that have a value of
+ *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.
+
+.. important:: Uninstalling a feature using the Karaf feature:uninstall command
+ 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
+
+To list the installed Karaf features, run the following command::
+
+ feature:list -i
+
+Features to implement networking functionality provide release notes you can
+access on the OpenDaylight Wiki: https://wiki.opendaylight.org/view/Project_list
+
+* Authentication, Authorization and Accounting (AAA_)
+* ALTO_
+* BGPCEP_
+* Controller_
+* Control And Provisioning of Wireless Access Points (CAPWAP_)
+* Identification and Driver Management (DIDM_)
+* DLUX_
+* FaaS_
+* Group_Based_Policy_ (GPB)
+* Internet of Things Data Management (IoTDM_)
+* L2_Switch_
+* Link Aggregation Control Protocol (LACP_)
+* LISP_Flow_Mapping_
+* MDSAL_
+* NEMO_
+* NETCONF_
+* NetIDE_
+* NeXt_
+* Network Intent Composition (NIC_)
+* Neutron_Northbound_
+* OF-Config_
+* OpFlex_
+* OpenFlow_Plugin_
+* OpenFlow_Protocol_Library_
+* OVSDB_Netvirt_
+* Packet_Cable_ / PCMM
+* SDN_Interface_Application_
+* Secure Network Bootstrapping Infrastructure (SNBI_)
+* SNMP4SDN_
+* SNMP_Plugin_
+* Secure tag eXchange Protocol (SXP_)
+* Service Function Chaining (SFC_)
+* TCPMD5_
+* Time Series Data Repository (TSDR_)
+* Table Type Patterns (TTP_)
+* Topology_Processing_Framework_
+* Unified Secure Channel (USC_)
+* VPN_Service_
+* Virtual Tenant Network (VTN_)
+* YANG_Tools_
+
+Projects without Release Notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following projects participated in Beryllium, but intentionally do not have
+release notes:
+
+* The Documentation Project produced this and the other downloadable
+ documentation.
+* The Integration Group hosted the OpenDaylight-wide tests and main release
+ distribution.
+* Controller Core Functionality Tutorials provided a single test suite
+ (dsbenchmark) that was used as part of integration testing
+* Release Engineering used autorelease to build the Beryllium release artifacts,
+ including the main release download.
+
+Beryllium features
+------------------
+
+.. list-table:: Beryllium features
+ :widths: 10 25 10 5
+ :header-rows: 1
+
+ * - Feature Name
+ - Feature Description
+ - Karaf feature name
+ - Compatibility
+
+ * - Authentication
+ - Enables authentication with support for federation using Apache Shiro
+ - odl-aaa-shiro
+ - all
+
+ * - BGP
+ - Provides support for Border Gateway Protocol (including Link-State
+ Distribution) as a source of L3 topology information
+ - odl-bgpcep-bgp
+ - all
+
+ * - BMP
+ - Provides support for BGP Monitoring Protocol as a monitoring station
+ - odl-bgpcep-bmp
+ - all
+
+ * - DIDM
+ - Device Identification and Driver Management
+ - odl-didm-all
+ - all
+
+ * - Centinel
+ - Provides interfaces for streaming analytics
+ - odl-centinel-all
+ - all
+
+ * - DLUX
+ - Provides an intuitive graphical user interface for OpenDaylight
+ - odl-dlux-all
+ - all
+ * - Fabric as a Service (Faas)
+ - Creates a common abstraction layer on top of a physical network so
+ northbound APIs or services can be more easiliy mapped onto the
+ physical network as a concrete device configuration
+ - odl-faas-all
+ - all
+
+ * - Group Based Policy
+ - Enables Endpoint Registry and Policy Repository REST APIs and associated
+ functionality for Group Based Policy with the default renderer for
+ OpenFlow renderers
+ - odl-groupbasedpolicy-ofoverlay
+ - all
+
+ * - GBP User Interface
+ - Enables a web-based user interface for Group Based Policy
+ - odl-groupbasedpolicyi-ui
+ - all
+
+ * - GBP FaaS renderer
+ - Enables the Fabric as a Service renderer for Group Based Policy
+ - odl-groupbasedpolicy-faas
+ - self+all
+
+ * - GBP Neutron Support
+ - Provides OpenStack Neutron support using Group Based Policy
+ - odl-groupbasedpolicy-neutronmapper
+ - all
+
+ * - L2 Switch
+ - Provides L2 (Ethernet) forwarding across connected OpenFlow switches and
+ support for host tracking
+ - odl-l2switch-switch-ui
+ - self+all
+
+ * - LACP
+ - Enables support for the Link Aggregation Control Protocol
+ - odl-lacp-ui
+ - self+all
+
+ * - LISP Flow Mapping
+ - Enables LISP control plane services including the mapping system
+ services REST API and LISP protocol SB plugin
+ - odl-lispflowmapping-msmr
+ - all
+
+ * - NEMO CLI
+ - Provides intent mappings and implementation with CLI for legacy devices
+ - odl-nemo-cli-renderer
+ - all
+
+ * - NEMO OpenFlow
+ - Provides intent mapping and implementation for OpenFlow devices
+ - odl-nemo-openflow-renderer
+ - self+all
+
+ * - NetIDE
+ - Enables portabilty and cooperation inside a single network by using a
+ client/server multi-controller architecture
+ - odl-netide-rest
+ - all
+
+ * - NETCONF over SSH
+ - Provides support to manage NETCONF-enabled devices over SSH
+ - odl-netconf-connector-ssh
+ - all
+
+ * - OF-CONFIG
+ - Enables remote configuration of OpenFlow datapaths
+ - odl-of-config-rest
+ - all
+
+ * - OVSDB OpenStack Neutron
+ - OpenStack Network Virtualization using OpenDaylight's OVSDB support
+ - odl-ovsdb-openstack
+ - all
+
+ * - OVSDB Southbound
+ - OVSDB MDSAL southbound plugin for Open_vSwitch schema
+ - odl-ovsdb-southbound-impl-ui
+ - all
+
+ * - OVSDB HWVTEP Southbound
+ - OVSDB MDSAL hwvtep southbound plugin for the hw_vtep schema
+ - odl-ovsdb-hwvtepsouthbound-ui
+ - all
+
+ * - OVSDB NetVirt SFC
+ - OVSDB NetVirt support for SFC
+ - odl-ovsdb-sfc-ui
+ - all
+
+ * - OpenFlow Flow Programming
+ - Enables discovery and control of OpenFlow switches and the topoology
+ between them
+ - odl-openflowplugin-flow-services-ui
+ - all
+
+ * - OpenFlow Table Type Patterns
+ - Allows OpenFlow Table Type Patterns to be manually associated with
+ network elements
+ - odl-ttp-all
+ - all
+
+ * - Packetcable PCMM
+ - Enables flow-based dynamic QoS management of CMTS use in the DOCSIS
+ infrastructure and a policy server
+ - odl-packetcable-policy-server
+ - self+all
+
+ * - PCEP
+ - Enables support for PCEP
+ - odl-bgpcep-pcep
+ - all
+
+ * - RESTCONF API Support
+ - Enables REST API access to the MD-SAL including the data store
+ - odl-restconf
+ - all
+
+ * - SDNinterface
+ - Provides support for interaction and sharing of state between
+ (non-clustered) OpenDaylight instances
+ - odl-sdninterfaceapp-all
+ - all
+
+ * - SFC over L2
+ - Supports implementing Service Function Chaining using Layer 2
+ forwarding
+ - odl-sfcofl2
+ - self+all
+
+ * - SFC over LISP
+ - Supports implementing Service Function Chaining using LISP
+ - odl-sfclisp
+ - all
+
+ * - SFC over REST
+ - Supports implementing Service Function Chaining using REST CRUD
+ operations on network elements
+ - odl-sfc-sb-rest
+ - all
+
+ * - SFC over VXLAN
+ - Supports implementing Service Function Chaining using VXLAN tunnels
+ - odl-sfc-ovs
+ - self+all
+
+ * - SNMP Plugin
+ - Enables monitoring and control of network elements via SNMP
+ - odl-snmp-plugin
+ - all
+
+ * - SNMP4SDN
+ - Enables OpenFlow-like control of network elements via SNMP
+ - odl-snmp4sdn-all
+ - all
+
+ * - SSSD Federated Authentication
+ - Enables support for federated authentication using SSSD
+ - odl-aaa-sssd-plugin
+ - all
+
+ * - Secure tag eXchange Protocol (SXP)
+ - Enables distribution of shared tags to network devices
+ - odl-sxp-controller
+ - all
+
+ * - Time Series Data Repository (TSDR)
+ - Enables support for storing and querying time series data with the
+ default data collector for OpenFlow statistics the default data store
+ for HSQLDB
+ - odl-tsdr-hsqldb-all
+ - all
+
+ * - TSDR Data Collectors
+ - Enables support for various TSDR data sources (collectors) including
+ OpenFlow statistics, NetFlow statistics, NetFlow statistics, SNMP data,
+ Syslog, and OpenDaylight (controller) metrics
+ - odl-tsdr-openflow-statistics-collector,
+ odl-tsdr-netflow-statistics-collector,
+ odl-tsdr-snmp-data-collector,
+ odl-tsdr-syslog-collector,
+ odl-tsdr-controller-metrics-collector
+ - all
+
+ * - TSDR Data Stores
+ - Enables support for TSDR data stores including HSQLDB, HBase, and
+ Cassandra
+ - odl-tsdr-hsqldb, odl-tsdr-hbase, or odl-tsdr-cassandra
+ - all
+
+ * - Topology Processing Framework
+ - Enables merged and filtered views of network topologies
+ - odl-topoprocessing-framework
+ - all
+
+ * - Unified Secure Channel (USC)
+ - Enables support for secure, remote connections to network devices
+ - odl-usc-channel-ui
+ - all
+
+ * - VPN Service
+ - Enables support for OpenStack VPNaaS
+ - odl-vpnservice-core
+ - all
+
+ * - VTN Manager
+ - Enables Virtual Tenant Network support
+ - odl-vtn-manager-rest
+ - self+all
+
+ * - VTN Manager Neutron
+ - Enables OpenStack Neutron support of VTN Manager
+ - odl-vtn-manager-neutron
+ - self+all
+
+
+Other Beryllium features
+------------------------
+
+.. list-table:: Other Beryllium features
+ :widths: 10 25 10 5
+ :header-rows: 1
+
+ * - Feature Name
+ - Feature Description
+ - Karaf feature name
+ - Compatibility
+
+ * - OpFlex
+ - Provides OpFlex agent for Open vSwitch to enforce network policy, such
+ as GBP, for locally-attached virtual machines or containers
+ - n/a
+ - all
+
+ * - NeXt
+ - Provides a developer toolkit for designing network-centric topology
+ user interfaces
+ - n/a
+ - all
+
+
+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
+deploying it.
+
+.. list-table:: Other Beryllium features
+ :widths: 10 25 10 5
+ :header-rows: 1
+
+ * - Feature Name
+ - Feature Description
+ - Karaf feature name
+ - Compatibility
+
+ * - Authorization
+ - Enables configurable role-based authorization
+ - odl-aaa-authz
+ - all
+
+ * - ALTO
+ - Enables support for Application-Layer Traffic Optimization
+ - odl-alto-core
+ - self+all
+
+ * - CAPWAP
+ - Enables control of supported wireless APs
+ - odl-capwap-ac-rest
+ - all
+
+ * - Clustered Authentication
+ - Enables the use of the MD-SAL clustered data store for the
+ authentication database
+ - odl-aaa-authn-mdsal-cluster
+ - all
+
+ * - Controller Shield
+ - Provides controller security information to northbound applications
+ - odl-usecplugin
+ - all
+
+ * - GBP IO Visor Renderer
+ - Provides support for rendering Group Based Policy to IO Visor
+ - odl-groupbasedpolicy-iovisor
+ - all
+
+ * - Internet of Things Data Management
+ - Enables support for the oneM2M specification
+ - odl-iotdm-onem2m
+ - all
+
+ * - LISP Flow Mapping OpenStack Network Virtualization
+ - Experimental support for OpenStack Neutron virtualization
+ - odl-lispflowmapping-neutron
+ - self+all
+
+ * - Messaging4Transport
+ - Introduces an AMQP Northbound to MD-SAL
+ - odl-messaging4transport
+ - all
+
+ * - Network Intent Composition (NIC)
+ - Provides abstraction layer for communcating network intents (including
+ a distributed intent mapping service REST API) using either Hazelcast
+ or the MD-SAL as the backing data store for intents
+ - odl-nic-core-hazelcast or odl-nic-core-mdsal
+ - all
+
+ * - NIC Console
+ - Provides a Karaf CLI extension for intent CRUD operations and mapping
+ service operations
+ - odl-nic-console
+ - all
+
+ * - NIC VTN renderer
+ - Virtual Tenant Network renderer for Network Intent Composition
+ - odl-nic-renderer-vtn
+ - self+all
+
+ * - NIC GBP renderer
+ - Group Based Policy renderer for Network Intent Composition
+ - odl-nic-renderer-gbp
+ - self+all
+
+ * - NIC OpenFlow renderer
+ - OpenFlow renderer for Network Intent Composition
+ - odl-nic-renderer-of
+ - self+all
+
+ * - NIC NEMO renderer
+ - NEtwork MOdeling renderer for Network Intent Composition
+ - odl-nic-renderer-nemo
+ - self+all
+
+ * - OVSDB NetVirt UI
+ - OVSDB DLUX UI
+ - odl-ovsdb-ui
+ - all
+
+ * - Secure Networking Bootstrap
+ - Defines a SNBi domain and associated white lists of devices to be
+ accommodated to the domain
+ - odl-snbi-all
+ - self+all
+
+ * - UNI Manager
+ - Initiates the development of data models and APIs to facilitate
+ configuration and provisioning connectivity services for OpenDaylight
+ applications and services
+ - odl-unimgr
+ - all
+
+ * - YANG PUBSUB
+ - Allows subscriptions to be placed on targeted subtrees of YANG
+ datastores residing on remote devices to obviate the need for
+ OpenDaylight to make continuous fetch requests
+ - odl-yangpush-rest
+ - 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.
+
+
+Install the DLUX interface
+--------------------------
+OpenDaylight’s DLUX web interface draws information from topology and host
+databases to display information about the topology of the network, flow
+statistics, and host locations.
+
+To integrate with OpenDaylight you must enable the DLUX Karaf feature. Each
+feature can be enabled or disabled separately. Ensure that you have created a
+topology and enabled the MD-SAL feature in the Karaf distribution before you
+use DLUX for network management. For more information about enabling the Karaf
+features for DLUX, refer to Enable_DLUX_Feature_.
+
+MD-SAL clustering
+-----------------
+In the Beryllium release and newer, the odl-mdsal-broker installs MD-SAL
+clustering automatically.
+
+.. _Enable_DLUX_Feature: https://wiki.opendaylight.org/view/DLUX:Beryllium_System_Test_Plan#Enabling_The_Feature
+
+
+.. _AAA: https://wiki.opendaylight.org/view/AAA:Beryllium_Release_Notes
+.. _ALTO: https://wiki.opendaylight.org/view/ALTO:Beryllium:Release_Notes
+.. _BGPCEP: https://wiki.opendaylight.org/view/BGP_LS_PCEP:Beryllium_Release_Notes
+.. _CAPWAP: https://wiki.opendaylight.org/view/CAPWAP:Beryllium:Release_Notes
+.. _Controller: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Beryllium:Release_Notes
+.. _DIDM: https://wiki.opendaylight.org/view/DIDM:_Beryllium_Release_Notes
+.. _DLUX: https://wiki.opendaylight.org/view/OpenDaylight_DLUX:Beryllium:Release_Notes
+.. _FaaS: https://wiki.opendaylight.org/view/FaaS:Beryllium_Release_Notes
+.. _Group_Based_Policy: https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)/Releases/Beryllium:Beryllium_Release_Notes
+.. _IoTDM: https://wiki.opendaylight.org/view/Iotdm:Beryllium_Release_Notes
+.. _L2_Switch: https://wiki.opendaylight.org/view/L2_Switch:Beryllium:Release_Notes
+.. _LACP: https://wiki.opendaylight.org/view/LACP:Beryllium:Release_Notes
+.. _LISP_Flow_Mapping: https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Beryllium_Release_Notes
+.. _MDSAL: https://wiki.opendaylight.org/view/MD-SAL:Beryllium:Release_Notes
+.. _NEMO: https://wiki.opendaylight.org/view/NEMO:Beryllium:Release_Notes
+.. _NETCONF: https://wiki.opendaylight.org/view/OpenDaylight_NETCONF:Beryllium_Release_Notes
+.. _NetIDE: https://wiki.opendaylight.org/view/NetIDE:Release_Notes
+.. _NeXt: https://wiki.opendaylight.org/view/NeXt:Beryllium_Release_Notes
+.. _NIC: https://wiki.opendaylight.org/view/Network_Intent_Composition:Release_Notes
+.. _Neutron_Northbound: https://wiki.opendaylight.org/view/NeutronNorthbound:Beryllium:Release_Notes
+.. _OF-Config: https://wiki.opendaylight.org/view/OF-CONFIG:Beryllium:Release_Notes
+.. _OpFlex: https://wiki.opendaylight.org/view/OpFlex:Beryllium_Release_Notes
+.. _OpenFlow_Plugin: https://wiki.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin:Beryllium_Release_Notes
+.. _OpenFlow_Protocol_Library: https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Release_Notes:Beryllium_Release_Notes
+.. _OVSDB_Netvirt: https://wiki.opendaylight.org/view/OpenDaylight_OVSDB:Beryllium_Release_Notes
+.. _Packet_Cable: https://wiki.opendaylight.org/view/PacketCablePCMM:BerylliumReleaseNotes
+.. _SDN_Interface_Application: https://wiki.opendaylight.org/view/ODL-SDNi:Beryllium_Release_Notes
+.. _SNBI: https://wiki.opendaylight.org/view/SNBI_Berrylium_Release_Notes
+.. _SNMP4SDN: https://wiki.opendaylight.org/view/SNMP4SDN:Beryllium_Release_Note
+.. _SNMP_Plugin: https://wiki.opendaylight.org/view/SNMP_Plugin:SNMP_Plugin:Beryllium_Release_Notes
+.. _SXP: https://wiki.opendaylight.org/view/SXP:Beryllium:Release_Notes
+.. _SFC: https://wiki.opendaylight.org/view/Service_Function_Chaining:Beryllium_Release_Notes
+.. _TCPMD5: https://wiki.opendaylight.org/view/TCPMD5:Beryllium_Release_Notes
+.. _TSDR: https://wiki.opendaylight.org/view/TSDR:Beryllium:Release_Notes
+.. _TTP: https://wiki.opendaylight.org/view/Table_Type_Patterns/Beryllium/Release_Notes
+.. _Topology_Processing_Framework: https://wiki.opendaylight.org/view/Topology_Processing_Framework:BERYLLIUM_Release_Notes
+.. _USC: https://wiki.opendaylight.org/view/USC:Beryllium:Release_Notes
+.. _VPN_Service: https://wiki.opendaylight.org/view/Vpnservice:Beryllium_Release_Notes
+.. _VTN: https://wiki.opendaylight.org/view/VTN:Beryllium:Release_Notes
+.. _YANG_Tools: https://wiki.opendaylight.org/view/YANG_Tools:Beryllium:Release_Notes
--- /dev/null
+Introduction
+============
+
+The OpenDaylight project is an open source platform for Software Defined
+Networking (SDN) that uses open protocols to provide centralized, programmatic
+control and network device monitoring. Like many other SDN controllers,
+OpenDaylight supports OpenFlow, as well as offering ready-to-install network
+solutions as part of its platform.
+
+Much as your operating system provides an interface for the devices that
+comprise your computer, OpenDaylight provides an interface that allows you to
+connect network devices quickly and intelligently for optimal network
+performance.
+
+It’s extremely helpful to understand that setting up your networking environment
+with OpenDaylight is not a single software installation. While your first
+chronological step is to install OpenDaylight, you install additional
+functionality packaged as Karaf features to suit your specific needs.
+
+Before walking you through the initial OpenDaylight installation, this guide
+presents a fuller picture of OpenDaylight’s framework and functionality so you
+understand how to set up your networking environment. The guide then takes you
+through the installation process.
+
+What’s different about OpenDaylight
+-----------------------------------
+
+Major distinctions of OpenDaylight’s SDN compared to traditional SDN options are
+the following:
+
+* A microservices architecture, in which a “microservice” is a particular
+ protocol or service that a user wants to enable within their installation of
+ the OpenDaylight controller, for example:
+
+ * A plugin that provides connectivity to devices via the OpenFlow or BGP
+ protocols
+ * An L2-Switch or a service such as Authentication, Authorization, and
+ Accounting (AAA).
+
+* Support for a wide and growing range of network protocols beyond OpenFlow,
+ including SNMP, NETCONF, OVSDB, BGP, PCEP, LISP, and more.
+* Support for developing new functionality comprised of additional networking
+ protocols and services.
+
+.. note:: A thorough understanding of the microservices architecture is
+ important for experienced network developers who want to create new solutions
+ in OpenDaylight. If you are new to networking and OpenDaylight, you most
+ likely won’t design solutions, but you should comprehend the microservices
+ concept to understand how OpenDaylight works and how it differs from other
+ 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
+Getting Started Guide covers feature descriptions, OpenDaylight installation
+procedures, and feature installation.
+
+
+The Getting Started Guide also includes other helpful information, with the
+following organization:
+
+#. An overview of OpenDaylight and common use models
+#. Who should use this guide?
+#. OpenDaylight concepts and tools
+#. Explanations of OpenDaylight Apache Karaf features and other features that
+ extend network functionality
+#. OpenDaylight Beryllium system requirements and Release Notes
+#. OpenDaylight installation instructions
+#. Feature tables with installation names and compatibility notes
--- /dev/null
+OpenDaylight Karaf Features
+===========================
+
+This section provides brief descriptions of the most commonly used Karaf
+features developed by OpenDaylight project teams. They are presented in
+alphabetical order. OpenDaylight installation instructions and a feature table
+that lists installation commands and compatibility follow.
+
+.. contents::
+ :depth: 1
+ :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:
+
+* Support for persistent data stores
+* Federation and SSO with OpenStack Keystone
+
+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
+application usage of network resources and includes five services:
+
+#. Network Map Service - Provides batch information to ALTO clients in the forms
+ of ALTO network maps.
+#. Cost Map Service - Provides costs between defined groupings.
+#. Filtered Map Service - Allows ALTO clients to query an ALTO server on ALTO
+ network maps and/or cost maps based on additional parameters.
+#. Endpoint Property Service - Allows ALTO clients to look up properties for
+ individual endpoints.
+#. Endpoint Cost Service - Allows an ALTO server to return costs directly
+ 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:
+
+* Collating the source of different attacks reported in southbound plugins
+* Gathering information on suspected controller intrusions and trusted
+ controllers in the network
+
+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
+different implementations for different device types. Device-specific
+functionality is implemented as Device Drivers.
+
+DLUX
+----
+Web based OpenDaylight user interface that includes:
+
+* An MD-SAL flow viewer
+* Network topology visualizer
+* 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:
+
+* Integration with OpenStack Neutron
+* Service Function Chaining
+* 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.
+
+*LISP Mapping Service* provides the EID-to-RLOC mapping information, including
+forwarding policy (load balancing, traffic engineering, and so on) to LISP
+routers for tunneling and forwarding purposes. The LISP Mapping Service can
+serve the mapping data to data plane nodes as well as to OpenDaylight
+applications.
+
+To leverage this service, a northbound API allows OpenDaylight applications and
+services to define the mappings and policies in the LISP Mapping Service. A
+southbound LISP plugin enables LISP data plane devices to interact with
+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-netconf-connector: NETCONF Southbound plugin - configured through the
+ configuration subsystem
+* odl-netconf-topology: NETCONF Southbound plugin - configured through the
+ MD-SAL configuration datastore
+* 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
+OpenDaylight. NetIDE details:
+
+* Architecture follows a client/server model: other SDN controllers represent
+ clients with OpenDaylight acting as the server.
+* OpenFlow v1.0/v1.3 is the only southbound protocol supported in this initial
+ release. We are planning for other southbound protocols in later releases.
+* The developer documentation contains the protocol specifications required for
+ developing plugins for other client SDN controllers.
+* The NetIDE Configuration file contains the configurable elements for the
+ 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
+OpenDaylight to provide enhanced network services to OpenStack.
+
+OVSDB Services are at parity with the Neutron Reference Implementation in
+OpenStack, including support for:
+
+* L2/L3
+
+ * The OpenDaylight Layer-3 Distributed Virtual Router is fully on par with
+ what OpenStack offers and now provides completely decentralized Layer 3
+ routing for OpenStack. ICMP rules for responding on behalf of the L3 router
+ are fully distributed as well.
+ * Full support for distributed Layer-2 switching and distributed IPv4 routing
+ is now available.
+
+* Clustering - Full support for clustering and High Availability (HA) is
+ available in the OpenDaylight Beryllium release. In particular, the OVSDB
+ southbound plugin supports clustering that any application can use, and the
+ Openstack network integration with OpenDaylight (through OVSDB Net-Virt) has
+ full clustering support. While there is no specific limit on cluster size, a
+ 3-node cluster has been tested extensively as part of the Beryllium release.
+
+* Security Groups - Security Group support is available and implemented using
+ OpenFlow rules that provide superior functionality and performance over
+ OpenStack Security Groups, which use IPTables. Security Groups also provide
+ support for ConnTrack with stateful tracking of existing connections.
+ Contract-based Security Groups require OVS v2.5 with contract support.
+
+* Hardware Virtual Tunnel End Point (HW-VTEP) - Full HW-VTEP schema support has
+ been implemented in the OVSDB protocol driver. Support for HW-VTEP via
+ OpenStack through the OVSDB-NetVirt implementation has not yet been provided
+ as we wait for full support of Layer-2 Gateway (L2GW) to be implemented within
+ OpenStack.
+
+* Service Function Chaining
+
+* Open vSwitch southbound support for quality of service and Queue configuration
+ Load Balancer as service (LBaaS) with Distributed Virtual Router, as offered
+ in the Lithium release
+
+* 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.
+
+In addition to support for the core OpenFlow specification, OpenDaylight
+Beryllium also includes preliminary support for the Table Type Patterns and
+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:
+
+#. Discover each other, which includes:
+
+ a. Revealing the physical topology of the network
+ #. Exposing each type of a device
+ #. Assigning the domain for each device
+
+#. Get assigned an IP-address
+#. Establish secure IP connectivity
+
+SNBi creates a basic infrastructure to host, run, and lifecycle-manage multiple
+network functions within a network device, including individual network element
+services, such as:
+
+* Performance measurement
+* Traffic-sniffing functionality
+* Traffic transformation functionality
+
+SNBi also provides a Linux side abstraction layer to forward elements as well
+as enhancements to feature the abstraction and bootstrapping infrastructure.
+You can also use the device type and domain information to initiate controller
+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
+OpenDaylight to provision a service chain in the network and an end-user
+application for defining such chains. It includes:
+
+* YANG models to express service function chains
+* SFC receiver for Intent expressions from REST & RPC
+* UI for service chain construction
+* LISP support
+* Function grouping for load balancing
+* OpenFlow renderer for Network Service Headers, MPLS, and VLAN
+* Southbound REST interface
+* IP Tables-based classifier for grouping packets into selected service chains
+* Integration with OpenDaylight GBP project
+* 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
+leverages only select SNMP features to implement the specific use case of
+making an SNMP-enabled device emulate some features of an OpenFlow-enabled
+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
+information about the tags to network devices so they can enforce the tags
+appropriately.
+
+More specifically, SXP Is an IETF-published control protocol designed to
+propagate the binding between an IP address and a source group, which has a
+unique source group tag (SGT). Within the SXP protocol, source groups with
+common network policies are endpoints connecting to the network. SXP updates
+the firewall with SGTs, enabling the firewalls to create topology-independent
+Access Control Lists (ACLs) and provide ACL automation.
+
+SXP source groups have the same meaning as endpoint groups in OpenDaylight’s
+Group Based Policy (GBP), which is used to manipulate policy groups, so you can
+use OpenDaylight GPB with SXP SGTs. The SXP topology-independent policy
+definition and automation can be extended through OpenDaylight for other
+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.
+
+Functionality of TDSR includes:
+
+* Data Query Service - For external data-driven applications to query data from
+ TSDR through REST APIs
+* NBI integration with Grafana - Allows visualization of data collected in TSDR
+ using Grafana
+* Data Purging Service - Periodically purges data from TSDR
+* Data Collection Framework - Data Collection framework to allow plugging in of
+ various types of collectors
+* HSQL data store - Replacement of H2 data store to remove third party
+ component dependency from TSDR
+* Enhancement of existing data stores including HBase to support new features
+ introduced in Beryllium
+* Cassandra data store - Cassandra implementation of TSDR SPIs
+* NetFlow data collector - Collect NetFlow data from network elements
+* SNMP Data Collector - Integrates with SNMP plugin to bring SNMP data into TSDR
+* Syslog data collector - Collects syslog data from network elements
+
+TSDR has multiple features to enable the functionality above. To begin,
+select one of these data stores:
+
+* odl-tsdr-hsqldb-all
+* odl-tsdr-hbase
+* odl-tsdr-cassandra
+
+Then select any “collectors” you want to use:
+
+* odl-tsdr-openflow-statistics-collector
+* odl-tsdr-netflow-statistics-collector
+* odl-tsdr-controller-metrics-collector
+* odl-tsdr-snmp-data-collector
+* odl-tsdr-syslog-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
+policies.
+
+A possible use case is encrypting controller-to-controller communications;
+however, the framework is very flexible, and client side software is available
+for multiple platforms and device types, enabling USC and OpenDaylight to
+centralize the coordination of encryption across a wide array of endpoint and
+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:
+
+* The L3 VPN Manager
+* MP-BGP Routing Stack
+* MPLS Label Manager
+* NextHop Manager
+* FIB Service & Openstack Neutron Service
+
+The VPN Service offers:
+
+* An API for L3 VPN Services
+* Integration with open source routing suites, including Quagga & Ryu
+* OpenStack Integration with BGPVPN_Blueprint_ for end-to-end integration
+* OpenStack Neutron integration
+* VPN Service upstreamed as part of SDN-distributed routing and the VPN (SDNVPN)
+ project of Open Platform for NFV project (OPNFV) (available in Brahmaputra
+ release)
+* 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
+physical network and is then configured on the individual switch, leveraging
+the SDN control protocol.
+
+By defining a logical plane with VTN, you can conceal the complexity of the
+underlying network and better manage network resources to reduce network
+configuration time and errors.
+
+.. _BGPVPN_Blueprint: http://docs.openstack.org/developer/networking-bgpvpn/
+.. _oneM2M: http://www.onem2m.org/
+.. _TSDR_Directions: https://wiki.opendaylight.org/view/Grafana_Integration_with_TSDR_Step-by-Step
--- /dev/null
+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:
+
+a. Large complex network topologies
+#. Aggregated network nodes
+#. Traffic/path/tunnel/group visualizations
+#. Different layout algorithms
+#. Map overlays
+#. Preset user-friendly interactions
+
+NeXt can work with DLUX to build OpenDaylight applications. NeXt does not
+support Internet Explorer. Check out the NeXt_demo_ for more information on the
+interface.
+
+.. _NeXt_demo: https://www.youtube.com/watch?v=gBsUDu8aucs
--- /dev/null
+Overview
+========
+
+OpenDaylight performs the following functions:
+
+* Logically centralizes programmatic control of the physical and virtual devices
+ in your network.
+* Controls devices with standard, open protocols.
+* Provides higher-level abstractions of its capabilities so experienced network
+ engineers and developers can create new applications to customize network
+ setup and administration.
+
+Common use cases for SDN are as follows:
+
+#. Centralized network monitoring, management, and orchestration
+#. Proactive network management and traffic engineering
+#. Chaining packets through the different VMs, which is known as service
+ function chaining (SFC). SFC enables Network Functions Virtualization (NFV),
+ which is a network architecture concept that virtualizes entire classes of
+ network node functions into building blocks that may connect, or chain
+ together, to create communication services.
+#. Cloud - managing both the virtual overlay and the physical underlay beneath
+ it.
--- /dev/null
+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:
+
+#. Those new to OpenDaylight who want to install it and select the features they
+ need to run their network environment using only the command line and GUI.
+ Such users include:
+
+ a. Students
+ #. Network administrators and engineers.
+
+#. Network engineers and network application developers who want to use
+ OpenDaylight’s REST APIs to manage their network programmatically.
+#. Network engineers and network application developers who want to write their
+ own OpenDaylight services and plugins for greater functionality. This group
+ of users needs a significant level of expertise in the following areas, which
+ is beyond the scope of this document:
+
+ a. The YANG modeling language
+ #. The Model-Driven Service Abstraction Layer (MD-SAL)
+ #. Maven build tool
+ #. Management of the shared data store
+ #. How to handle notifications and/or Remote Procedure Calls (RPCs)
+
+#. Developers who would like to join the OpenDaylight community and contribute
+ code upstream. People in this group design offerings such as
+ applications/services, protocol implementations, and so on, to increase
+ OpenDaylight functionality for the benefit of all end-users.
+
+.. note:: If you develop code to build new functionality for OpenDaylight and
+ push it upstream (not required), it can become part of the OpenDaylight
+ release. Users can then install the features to implement the solution you’ve
+ created.
--- /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!
+=====================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ getting-started-guide/index
+ opendaylight-with-openstack/index
+ submodules/releng/builder/docs/index
+
+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
+OpenDaylight with Openstack Guide
+=================================
+
+Overview
+--------
+
+OpenStack_ is a popular open source Infrastructure
+as a service project, covering compute, storage and network management.
+OpenStack can use OpenDaylight as its network management provider through the
+Modular Layer 2 (ML2) north-bound plug-in. OpenDaylight manages the network
+flows for the OpenStack compute nodes via the OVSDB south-bound plug-in. This
+page describes how to set that up, and how to tell when everything is working.
+
+Installing OpenStack
+--------------------
+
+Installing OpenStack is out of scope for this document, but to get started, it
+is useful to have a minimal multi-node OpenStack deployment.
+
+The reference deployment we will use for this document is a 3 node cluster:
+
+* One control node containing all of the management services for OpenStack_
+ (Nova, Neutron, Glance, Swift, Cinder, Keystone)
+* Two compute nodes running nova-compute
+* Neutron using the OVS back-end and vxlan for tunnels
+
+Once you have installed OpenStack_, verify that it is working by connecting
+to Horizon and performing a few operations. To check the Neutron
+configuration, create two instances on a private subnet bridging to your
+public network, and verify that you can connect to them, and that they can
+see each other.
+
+
+Installing OpenDaylight
+-----------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ openstack-with-ovsdb
+ openstack-with-gbp
+ openstack-with-vtn
+
+.. _OpenStack: https://www.openstack.org/
--- /dev/null
+OpenStack with GroupBasedPolicy
+===============================
+
+This section is for Application Developers and Network Administrators
+who are looking to integrate Group Based Policy with OpenStack.
+
+To enable the **GBP** Neutron Mapper feature, at the karaf console:
+
+.. code-block:: bash
+
+ feature:install odl-groupbasedpolicy-neutronmapper
+
+Neutron Mapper has the following dependencies that are automatically loaded:
+
+.. code-block:: bash
+
+ odl-neutron-service
+
+Neutron Northbound implementing REST API used by OpenStack
+
+.. code-block:: bash
+
+ odl-groupbasedpolicy-base
+
+Base **GBP** feature set, such as policy resolution, data model etc.
+
+.. code-block:: bash
+
+ odl-groupbasedpolicy-ofoverlay
+
+For Lithium, **GBP** has one renderer, hence this is loaded by default.
+
+REST calls from OpenStack Neutron are by the Neutron NorthBound project.
+
+**GBP** provides the implementation of the `Neutron V2.0 API <neutron_v2api_>`_.
+
+Features
+--------
+
+List of supported Neutron entities:
+
+* Port
+* Network
+
+ * Standard Internal
+ * External provider L2/L3 network
+
+* Subnet
+* Security-groups
+* Routers
+
+ * Distributed functionality with local routing per compute
+ * External gateway access per compute node (dedicated port required)
+ * Multiple routers per tenant
+
+* FloatingIP NAT
+* IPv4/IPv6 support
+
+The mapping of Neutron entities to **GBP** entities is as follows:
+
+**Neutron Port**
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-port.png
+
+ Neutron Port
+
+The Neutron port is mapped to an endpoint.
+
+The current implementation supports one IP address per Neutron port.
+
+An endpoint and L3-endpoint belong to multiple EndpointGroups if the Neutron
+port is in multiple Neutron Security Groups.
+
+The key for endpoint is L2-bridge-domain obtained as the parent of
+L2-flood-domain representing Neutron network. The MAC address is from the
+Neutron port.
+An L3-endpoint is created based on L3-context (the parent of the
+L2-bridge-domain) and IP address of Neutron Port.
+
+**Neutron Network**
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-network.png
+
+ Neutron Network
+
+A Neutron network has the following characteristics:
+
+* defines a broadcast domain
+* defines a L2 transmission domain
+* defines a L2 name space.
+
+To represent this, a Neutron Network is mapped to multiple **GBP** entities.
+The first mapping is to an L2 flood-domain to reflect that the Neutron network
+is one flooding or broadcast domain.
+An L2-bridge-domain is then associated as the parent of L2 flood-domain. This
+reflects both the L2 transmission domain as well as the L2 addressing namespace.
+
+The third mapping is to L3-context, which represents the distinct L3 address space.
+The L3-context is the parent of L2-bridge-domain.
+
+**Neutron Subnet**
+
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet.png
+
+ Neutron Subnet
+
+Neutron subnet is associated with a Neutron network. The Neutron subnet is
+mapped to a *GBP* subnet where the parent of the subnet is L2-flood-domain
+representing the Neutron network.
+
+**Neutron Security Group**
+
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-securitygroup.png
+
+ Neutron Security Group and Rules
+
+**GBP** entity representing Neutron security-group is EndpointGroup.
+
+**Infrastructure EndpointGroups**
+
+Neutron-mapper automatically creates EndpointGroups to manage key infrastructure
+items such as:
+
+* DHCP EndpointGroup - contains endpoints representing Neutron DHCP ports
+* Router EndpointGroup - contains endpoints representing Neutron router
+ interfaces
+* External EndpointGroup - holds L3-endpoints representing Neutron router
+ gateway ports, also associated with FloatingIP ports.
+
+**Neutron Security Group Rules**
+
+This mapping is most complicated among all others because Neutron
+security-group-rules are mapped to contracts with clauses,
+subjects, rules, action-refs, classifier-refs, etc.
+Contracts are used between endpoint groups representing Neutron Security Groups.
+For simplification it is important to note that Neutron security-group-rules are
+similar to a **GBP** rule containing:
+
+* classifier with direction
+* action of *allow*.
+
+
+**Neutron Routers**
+
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-router.png
+
+ Neutron Router
+
+Neutron router is represented as a L3-context. This treats a router as a Layer3
+namespace, and hence every network attached to it a part
+of that Layer3 namespace.
+
+This allows for multiple routers per tenant with complete isolation.
+
+The mapping of the router to an endpoint represents the router's interface or
+gateway port.
+
+The mapping to an EndpointGroup represents the internal infrastructure
+EndpointGroups created by the **GBP** Neutron Mapper
+
+When a Neutron router interface is attached to a network/subnet, that
+network/subnet and its associated endpoints or Neutron Ports are seamlessly
+added to the namespace.
+
+**Neutron FloatingIP**
+
+When associated with a Neutron Port, this leverages the *GBP* OfOverlay
+renderer's NAT capabilities.
+
+A dedicated *external* interface on each Nova compute host allows for
+disitributed external access. Each Nova instance associated with a
+FloatingIP address can access the external network directly without having to
+route via the Neutron controller, or having to enable any form
+of Neutron distributed routing functionality.
+
+Assuming the gateway provisioned in the Neutron Subnet command for the external
+network is reachable, the combination of *GBP* Neutron Mapper and
+OfOverlay renderer will automatically ARP for this default gateway, requiring
+no user intervention.
+
+
+**Troubleshooting within GBP**
+
+Logging level for the mapping functionality can be set for package
+org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling TRACE
+logging level on karaf console:
+
+.. code-block:: bash
+
+ log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
+
+**Neutron mapping example**
+
+As an example for mapping can be used creation of Neutron network, subnet and
+port. When a Neutron network is created 3 **GBP** entities are created:
+l2-flood-domain, l2-bridge-domain, l3-context.
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-network-example.png
+
+ Neutron network mapping
+
+After an subnet is created in the network mapping looks like this.
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-subnet-example.png
+
+ Neutron subnet mapping
+
+If an Neutron port is created in the subnet an endpoint and l3-endpoint are
+created. The endpoint has key composed from l2-bridge-domain and MAC address
+from Neutron port. A key of l3-endpoint is compesed from l3-context and IP
+address. The network containment of endpoint and l3-endpoint points to the
+subnet.
+
+
+.. figure:: images/groupbasedpolicy/neutronmapper-gbp-mapping-port-example.png
+
+ Neutron port mapping
+
+Configuring GBP Neutron
+-----------------------
+
+No intervention passed initial OpenStack setup is required by the user.
+
+More information about configuration can be found in our DevStack demo
+environment on the `GBP wiki <gbp_wiki_>`_.
+
+Administering or Managing GBP Neutron
+-------------------------------------
+
+For consistencies sake, all provisioning should be performed via the Neutron API. (CLI or Horizon).
+
+The mapped policies can be augmented via the **GBP** UX,UX, to:
+
+* Enable Service Function Chaining
+* Add endpoints from outside of Neutron i.e. VMs/containers not provisioned in OpenStack
+* Augment policies/contracts derived from Security Group Rules
+* Overlay additional contracts or groupings
+
+Tutorials
+---------
+
+A DevStack demo environment can be found on the
+`GBP wiki <gbp_wiki_>`_.
+
+.. _gbp_wiki: https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)
+.. _neutron_v2api: http://developer.openstack.org/api-ref-networking-v2.html
--- /dev/null
+OpenStack with OVSDB
+====================
+
+**Prerequisites**: OpenDaylight requires Java 1.7.0.
+
+* On the control host, `Download
+ the latest OpenDaylight release <ODL_Downloads_>`_ (at the time of writing,
+ this is Beryllium-SR2)
+* Uncompress it as root, and start OpenDaylight (you can start OpenDaylight
+ by running karaf directly, but exiting from the shell will shut it down):
+
+.. code-block:: bash
+
+ tar xvfz distribution-karaf-0.4.2-Beryllium-SR2.tar.gz
+ cd distribution-karaf-0.4.2-Beryllium-SR2
+ ./bin/start # Start OpenDaylight as a server process
+
+* Connect to the Karaf shell, and install the odl-ovsdb-openstack bundle,
+ dlux and their dependencies:
+
+.. code-block:: bash
+
+ ./bin/client # Connect to OpenDaylight with the client
+ opendaylight-user@root> feature:install odl-base-all odl-aaa-authn odl-restconf odl-nsf-all odl-adsal-northbound odl-mdsal-apidocs odl-ovsdb-openstack odl-ovsdb-northbound odl-dlux-core
+
+* If everything is installed correctly, you should now be able to log in to
+ the dlux interface on http://$CONTROL_HOST:8181/dlux/index.html - the
+ default username and password is "admin/admin" (see screenshot below)
+
+.. image:: images/dlux-default.png
+
+Ensuring OpenStack network state is clean
+-----------------------------------------
+
+When using OpenDaylight as the Neutron back-end, ODL expects to be the only
+source of truth for Open vSwitch configuration. Because of this, it is
+necessary to remove existing OpenStack and Open vSwitch configurations to
+give OpenDaylight a clean slate.
+
+* Delete instances
+
+.. code-block:: bash
+
+ nova list
+ nova delete <instance names>
+
+* Remove link from subnets to routers
+
+.. code-block:: bash
+
+ neutron subnet-list
+ neutron router-list
+ neutron router-port-list <router name>
+ neutron router-interface-delete <router name> <subnet ID or name>
+
+* Delete subnets, nets, routers
+
+.. code-block:: bash
+
+ neutron subnet-delete <subnet name>
+ neutron net-list
+ neutron net-delete <net name>
+ neutron router-delete <router name>
+
+* Check that all ports have been cleared - at this point, this should be an
+ empty list
+
+.. code-block:: bash
+
+ neutron port-list
+
+
+Ensure Neutron is stopped
+-------------------------
+
+While Neutron is managing the OVS instances on compute and control nodes,
+OpenDaylight and Neutron can be in conflict. To prevent issues, we turn off
+Neutron server on the network controller, and Neutron's Open vSwitch agents
+on all hosts.
+
+* Turn off neutron-server on control node
+
+.. code-block:: bash
+
+ systemctl stop neutron-server
+
+* On each node in the cluster, shut down and disable Neutron's agent services to ensure that they do not restart after a reboot:
+
+.. code-block:: bash
+
+ systemctl stop neutron-openvswitch-agent
+ systemctl disable neutron-openvswitch-agent
+
+
+Configuring Open vSwitch to be managed by OpenDaylight
+------------------------------------------------------
+
+On each host (both compute and control nodes) we will clear the pre-existing
+Open vSwitch config and set OpenDaylight to manage the switch:
+
+* Stop the Open vSwitch service, and clear existing OVSDB (ODL expects to
+ manage vSwitches completely)
+
+.. code-block:: bash
+
+ systemctl stop openvswitch
+ rm -rf /var/log/openvswitch/*
+ rm -rf /etc/openvswitch/conf.db
+ systemctl start openvswitch
+
+* At this stage, your Open vSwitch configuration should be empty:
+
+.. code-block:: bash
+
+ [root@dneary-odl-compute2 ~]# ovs-vsctl show
+ 9f3b38cb-eefc-4bc7-828b-084b1f66fbfd
+ ovs_version: "2.1.3"
+
+* Set OpenDaylight as the manager on all nodes
+
+.. code-block:: bash
+
+ ovs-vsctl set-manager tcp:${CONTROL_HOST}:6640
+
+
+* You should now see a new section in your Open vSwitch configuration
+ showing that you are connected to the OpenDaylight server, and OpenDaylight
+ will automatically create a br-int bridge:
+
+.. code-block:: bash
+
+ [root@dneary-odl-compute2 ~]# ovs-vsctl show
+ 9f3b38cb-eefc-4bc7-828b-084b1f66fbfd
+ Manager "tcp:172.16.21.56:6640"
+ is_connected: true
+ Bridge br-int
+ Controller "tcp:172.16.21.56:6633"
+ fail_mode: secure
+ Port br-int
+ Interface br-int
+ ovs_version: "2.1.3"
+
+
+* (BUG WORKAROUND) If SELinux is enabled, you may not have a security
+ context in place which allows Open vSwitch remote administration. If you
+ do not see the result above (specifically, if you do not see
+ "is_connected: true" in the Manager section), set SELinux to Permissive
+ mode on all nodes and ensure it stays that way after boot:
+
+.. code-block:: bash
+
+ setenforce 0
+ sed -i -e 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config
+
+* Make sure all nodes, including the control node, are connected to
+ OpenDaylight
+* If you reload DLUX, you should now see that all of your Open vSwitch nodes
+ are now connected to OpenDaylight
+
+.. image:: images/dlux-with-switches.png
+
+* If something has gone wrong, check <code>data/log/karaf.log</code> under
+ the OpenDaylight distribution directory. If you do not see any interesting
+ log entries, set logging for OVSDB to TRACE level inside Karaf and try again:
+
+.. code-block:: bash
+
+ log:set TRACE ovsdb
+
+
+Configuring Neutron to use OpenDaylight
+---------------------------------------
+
+Once you have configured the vSwitches to connect to OpenDaylight, you can
+now ensure that OpenStack Neutron is using OpenDaylight.
+
+First, ensure that port 8080 (which will be used by OpenDaylight to listen
+for REST calls) is available. By default, swift-proxy-service listens on the
+same port, and you may need to move it (to another port or another host), or
+disable that service. I moved it to port 8081 by editing
+<code>/etc/swift/proxy-server.conf</code> and
+<code>/etc/cinder/cinder.conf</code>, modifying iptables appropriately, and
+restarting swift-proxy-service and OpenDaylight.
+
+* Configure Neutron to use OpenDaylight's ML2 driver:
+
+.. code-block:: bash
+
+ crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 mechanism_drivers opendaylight
+ crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 tenant_network_types vxlan
+
+ cat <<EOT>> /etc/neutron/plugins/ml2/ml2_conf.ini
+ [ml2_odl]
+ password = admin
+ username = admin
+ url = http://${CONTROL_HOST}:8080/controller/nb/v2/neutron
+ EOT
+
+* Reset Neutron's ML2 database
+
+.. code-block:: bash
+
+ mysql -e "drop database if exists neutron_ml2;"
+ mysql -e "create database neutron_ml2 character set utf8;"
+ mysql -e "grant all on neutron_ml2.* to 'neutron'@'%';"
+ neutron-db-manage --config-file /usr/share/neutron/neutron-dist.conf --config-file /etc/neutron/neutron.conf \
+ --config-file /etc/neutron/plugin.ini upgrade head
+
+* Restart neutron-server:
+
+.. code-block:: bash
+
+ systemctl start neutron-server
+
+
+Verifying it works
+------------------
+
+* Verify that OpenDaylight's ML2 interface is working:
+
+.. code-block:: bash
+
+ curl -u admin:admin http://${CONTROL_HOST}:8080/controller/nb/v2/neutron/networks
+
+ {
+ "networks" : [ ]
+ }
+
+If this does not work or gives an error, check Neutron's log file in
+<code>/var/log/neutron/server.log</code>. Error messages here should give
+some clue as to what the problem is in the connection with OpenDaylight
+
+* Create a net, subnet, router, connect ports, and start an instance using
+ the Neutron CLI:
+
+.. code-block:: bash
+
+ neutron router-create router1
+ neutron net-create private
+ neutron subnet-create private --name=private_subnet 10.10.5.0/24
+ neutron router-interface-add router1 private_subnet
+ nova boot --flavor <flavor> --image <image id> --nic net-id=<network id> test1
+ nova boot --flavor <flavor> --image <image id> --nic net-id=<network id> test2
+
+At this point, you have confirmed that OpenDaylight is creating network
+end-points for instances on your network and managing traffic to them.
+
+Congratulations! You're done!
+
+
+.. _ODL_Downloads: https://www.opendaylight.org/software/downloads
--- /dev/null
+OpenStack with Virtual Tenant Network
+=====================================
+
+This section describes using OpenDaylight with the VTN manager feature providing
+network service for OpenStack. VTN manager utilizes the OVSDB southbound service
+and Neutron for this implementation. The below diagram depicts the communication
+of OpenDaylight and two virtual networks connected by an OpenFlow switch using
+this implementation.
+
+.. figure:: images/vtn/OpenStackDeveloperGuide.png
+
+ OpenStack Architecture
+
+Configure OpenStack to work with OpenDaylight(VTN Feature) using PackStack
+--------------------------------------------------------------------------
+
+Prerequisites to install OpenStack using PackStack
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Fresh CentOS 7.1 minimal install
+* Use the below commands to disable and remove Network Manager in CentOS 7.1,
+
+.. code-block:: bash
+
+ systemctl stop NetworkManager
+ systemctl disable NetworkManager
+
+* To make SELINUX as permissive, please open the file "/etc/sysconfig/selinux" and change it as "SELINUX=permissive".
+* After making selinux as permissive, please restart the CentOS 7.1 machine.
+
+Steps to install OpenStack PackStack in CentOS 7.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* To install OpenStack juno, use the following command,
+
+.. code-block:: bash
+
+ yum update -y
+ yum -y install https://repos.fedorapeople.org/repos/openstack/openstack-juno/rdo-release-juno-1.noarch.rpm
+
+
+* To install the packstack installer, please use the below command,
+
+.. code-block:: bash
+
+ yum -y install openstack-packstack
+
+* To create all-in-one setup, please use the below command,
+
+.. code-block:: bash
+
+ packstack --allinone --provision-demo=n --provision-all-in-one-ovs-bridge=n
+
+* This will end up with Horizon started successfully message.
+
+Steps to install and deploy OpenDaylight in CentOS 7.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Download the latest Lithium distribution code in the below link,
+
+.. code-block:: bash
+
+ wget https://nexus.opendaylight.org/content/groups/public/org/opendaylight/integration/distribution-karaf/0.3.4-Lithium-SR4/distribution-karaf-0.3.4-Lithium-SR4.zip
+
+
+* Unzip the lithium distribution code by using the below command,
+
+.. code-block:: bash
+
+ unzip distribution-karaf-0.3.4-Lithium-SR4.zip
+
+* Please do the below steps in the OpenDaylight to change jetty port,
+
+ * Change the jetty port from 8080 to something else as swift proxy of
+ OpenStack is using it.
+ * Open the file "etc/jetty.xml" and change the jetty port from 8080 to 8910
+ (we have used 8910 as jetty port you can use any other number).
+ * Start VTN Manager and install odl-vtn-manager-neutron in it.
+ * Ensure all the required ports(6633/6653,6640 and 8910) are in the listen
+ mode by using the command "netstat -tunpl" in OpenDaylight.
+
+Steps to reconfigure OpenStack in CentOS 7.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Steps to stop Open vSwitch Agent and clean up ovs
+
+.. code-block:: bash
+
+ sudo systemctl stop neutron-openvswitch-agent
+ sudo systemctl disable neutron-openvswitch-agent
+ sudo systemctl stop openvswitch
+ sudo rm -rf /var/log/openvswitch/*
+ sudo rm -rf /etc/openvswitch/conf.db
+ sudo systemctl start openvswitch
+ sudo ovs-vsctl show
+
+
+* Stop Neutron Server
+
+.. code-block:: bash
+
+ systemctl stop neutron-server
+
+
+* Verify that OpenDaylight's ML2 interface is working:
+
+.. code-block:: bash
+
+ curl -v admin:admin http://{CONTROL_HOST}:{PORT}/controller/nb/v2/neutron/networks
+
+ {
+ "networks" : [ ]
+ }
+
+If this does not work or gives an error, check Neutron's log file in
+*/var/log/neutron/server.log*. Error messages here should give
+some clue as to what the problem is in the connection with OpenDaylight
+
+* Configure Neutron to use OpenDaylight's ML2 driver:
+
+.. code-block:: bash
+
+ sudo crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 mechanism_drivers opendaylight
+ sudo crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 tenant_network_types local
+ sudo crudini --set /etc/neutron/plugins/ml2/ml2_conf.ini ml2 type_drivers local
+ sudo crudini --set /etc/neutron/dhcp_agent.ini DEFAULT ovs_use_veth True
+
+ cat <<EOT | sudo tee -a /etc/neutron/plugins/ml2/ml2_conf.ini > /dev/null
+ [ml2_odl]
+ password = admin
+ username = admin
+ url = http://{CONTROL_HOST}:{PORT}/controller/nb/v2/neutron
+ EOT
+
+* Reset Neutron's ML2 database
+
+.. code-block:: bash
+
+ sudo mysql -e "drop database if exists neutron_ml2;"
+ sudo mysql -e "create database neutron_ml2 character set utf8;"
+ sudo mysql -e "grant all on neutron_ml2.* to 'neutron'@'%';"
+ sudo neutron-db-manage --config-file /usr/share/neutron/neutron-dist.conf --config-file /etc/neutron/neutron.conf --config-file /etc/neutron/plugin.ini upgrade head
+
+* Start Neutron Server
+
+.. code-block:: bash
+
+ sudo systemctl start neutron-server
+
+* Restart the Neutron DHCP service
+
+.. code-block:: bash
+
+ system restart neutron-dhcp-agent.service
+
+* At this stage, your Open vSwitch configuration should be empty:
+
+.. code-block:: bash
+
+ [root@dneary-odl-compute2 ~]# ovs-vsctl show
+ 686989e8-7113-4991-a066-1431e7277e1f
+ ovs_version: "2.3.1"
+
+
+* Set OpenDaylight as the manager on all nodes
+
+.. code-block:: bash
+
+ ovs-vsctl set-manager tcp:127.0.0.1:6640
+
+
+* You should now see a section in your Open vSwitch configuration
+ showing that you are connected to the OpenDaylight server, and OpenDaylight
+ will automatically create a br-int bridge:
+
+.. code-block:: bash
+
+ [root@dneary-odl-compute2 ~]# ovs-vsctl show
+ 686989e8-7113-4991-a066-1431e7277e1f
+ Manager "tcp:127.0.0.1:6640"
+ is_connected: true
+ Bridge br-int
+ Controller "tcp:127.0.0.1:6633"
+ is_connected: true
+ fail_mode: secure
+ Port "ens33"
+ Interface "ens33"
+ ovs_version: "2.3.1"
+
+* Add the default flow to OVS to forward packets to controller when there is a table-miss,
+
+.. code-block:: bash
+
+ ovs-ofctl --protocols=OpenFlow13 add-flow br-int priority=0,actions=output:CONTROLLER
+
+* Please see the `VTN OpenStack PackStack support guide <VTN_OpenStack_PackStack_>`_
+ on the wiki to create VM's from OpenStack Horizon GUI.
+
+Implementation details
+----------------------
+
+VTN Manager
+^^^^^^^^^^^
+Install **odl-vtn-manager-neutron** feature which provides the integration with
+Neutron interface.
+
+.. code-block:: bash
+
+ feature:install odl-vtn-manager-neutron
+
+It subscribes to the events from Open vSwitch and also implements the Neutron
+requests received by OpenDaylight.
+
+Functional Behavior
+^^^^^^^^^^^^^^^^^^^
+
+**StartUp**
+
+* The ML2 implementation for OpenDaylight will ensure that when Open vSwitch is
+ started, the ODL_IP_ADDRESS configured will be set as manager.
+* When OpenDaylight receives the update of the Open vSwitch on port 6640
+ (manager port), VTN Manager handles the event and adds a bridge with required
+ port mappings to the Open vSwitch at the OpenStack node.
+* When Neutron starts up, a new network create is POSTed to OpenDaylight, for
+ which VTN Manager creates a Virtual Tenant Network.
+* *Network and Sub-Network Create:* Whenever a new sub network is created, VTN
+ Manager will handle the same and create a vbridge under the VTN.
+* *VM Creation in OpenStack:* The interface mentioned as integration bridge in
+ the configuration file will be added with more interfaces on creation of a
+ new VM in OpenStack and the network is provisioned for it by the VTN Neutron
+ feature. The addition of a new port is captured by the VTN Manager and it
+ creates a vbridge interface with port mapping for the particular port. When
+ the VM starts to communicate with other VMs, the VTN Manger will install flows
+ in the Open vSwitch and other OpenFlow switches to facilitate communication
+ between them.
+
+.. note::
+
+ To use this feature, VTN feature should be installed
+
+Reference
+---------
+
+https://wiki.opendaylight.org/images/5/5c/Integration_of_vtn_and_ovsdb_for_helium.pdf
+
+
+.. _VTN_OpenStack_PackStack: https://wiki.opendaylight.org/view/Release/Lithium/VTN/User_Guide/Openstack_Packstack_Support
--- /dev/null
+Subproject commit ac385949dd2bec52a819305ddf343c7e753cec25
--- /dev/null
+== BGP Monitoring Protocol Developer Guide
+
+=== Overview
+This section provides an overview of *feature odl-bgpcep-bmp*. This
+feature will install everything needed for BMP (BGP Monitoring Protocol)
+including establishing the connection, processing messages, storing
+information about monitored routers, peers and their Adj-RIB-In
+(unprocessed routing information) and Post-Policy Adj-RIB-In
+and displaying data in BGP RIBs overview.
+The OpenDaylight BMP plugin plays the role of a monitoring station.
+
+=== Key APIs and Interfaces
+
+==== Session handling
+
+_32-bmp.xml_ defines only bmp-dispatcher the parser should be
+using (global-bmp-extensions).
+
+[source,xml]
+----
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">prefix:bmp-dispatcher-impl</type>
+ <name>global-bmp-dispatcher</name>
+ <bmp-extensions>
+ <type xmlns:bmp-spi="urn:opendaylight:params:xml:ns:yang:controller:bmp:spi">bmp-spi:extensions</type>
+ <name>global-bmp-extensions</name>
+ </bmp-extensions>
+ <boss-group>
+ <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
+ <name>global-boss-group</name>
+ </boss-group>
+ <worker-group>
+ <type xmlns:netty="urn:opendaylight:params:xml:ns:yang:controller:netty">netty:netty-threadgroup</type>
+ <name>global-worker-group</name>
+ </worker-group>
+ </module>
+----
+
+For user configuration of BMP, check User Guide.
+
+==== Parser
+
+The base BMP parser includes messages and attributes from
+https://tools.ietf.org/html/draft-ietf-grow-bmp-15
+
+==== Registration
+
+All parsers and serializers need to be registered
+into _Extension provider_. This _Extension provider_ is configured in
+initial configuration of the parser (_32-bmp.xml_).
+
+[source,xml]
+----
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bmp:spi">prefix:bmp-extensions-impl</type>
+ <name>global-bmp-extensions</name>
+ <extension>
+ <type xmlns:bmp-spi="urn:opendaylight:params:xml:ns:yang:controller:bmp:spi">bmp-spi:extension</type>
+ <name>bmp-parser-base</name>
+ </extension>
+ </module>
+----
+
+* _bmp-parser-base_ - will register parsers and serializers
+implemented in bmp-impl module
+
+==== Parsing
+
+Parsing of BMP elements is mostly done equally to BGP. Some of the BMP messages includes wrapped
+BGP messages.
+
+==== BMP Monitoring Station
+
+The BMP application (Monitoring Station) serves as message processor incoming from monitored routers.
+The processed message is transformed and relevant information is stored. Route information is stored in a BGP
+RIB data structure.
+
+BMP data is displayed only through one URL that is accessible from the base BMP URL:
+
+_http://<controllerIP>:8181/restconf/operational/bmp-monitor:bmp-monitor_
+
+Each Monitor station will be displayed and it may contains multiple monitored routers and peers within:
+
+[source,xml]
+----
+<bmp-monitor xmlns="urn:opendaylight:params:xml:ns:yang:bmp-monitor">
+ <monitor>
+ <monitor-id>example-bmp-monitor</monitor-id>
+ <router>
+ <router-id>127.0.0.11</router-id>
+ <status>up</status>
+ <peer>
+ <peer-id>20.20.20.20</peer-id>
+ <as>72</as>
+ <type>global</type>
+ <peer-session>
+ <remote-port>5000</remote-port>
+ <timestamp-sec>5</timestamp-sec>
+ <status>up</status>
+ <local-address>10.10.10.10</local-address>
+ <local-port>220</local-port>
+ </peer-session>
+ <pre-policy-rib>
+ <tables>
+ <afi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:ipv4-address-family</afi>
+ <safi xmlns:x="urn:opendaylight:params:xml:ns:yang:bgp-types">x:unicast-subsequent-address-family</safi>
+ <ipv4-routes xmlns="urn:opendaylight:params:xml:ns:yang:bgp-inet">
+ <ipv4-route>
+ <prefix>10.10.10.0/24</prefix>
+ <attributes>
+ ...
+ </attributes>
+ </ipv4-route>
+ </ipv4-routes>
+ <attributes>
+ <uptodate>true</uptodate>
+ </attributes>
+ </tables>
+ </pre-policy-rib>
+ <address>10.10.10.10</address>
+ <post-policy-rib>
+ ...
+ </post-policy-rib>
+ <bgp-id>20.20.20.20</bgp-id>
+ <stats>
+ <timestamp-sec>5</timestamp-sec>
+ <invalidated-cluster-list-loop>53</invalidated-cluster-list-loop>
+ <duplicate-prefix-advertisements>16</duplicate-prefix-advertisements>
+ <loc-rib-routes>100</loc-rib-routes>
+ <duplicate-withdraws>11</duplicate-withdraws>
+ <invalidated-as-confed-loop>55</invalidated-as-confed-loop>
+ <adj-ribs-in-routes>10</adj-ribs-in-routes>
+ <invalidated-as-path-loop>66</invalidated-as-path-loop>
+ <invalidated-originator-id>70</invalidated-originator-id>
+ <rejected-prefixes>8</rejected-prefixes>
+ </stats>
+ </peer>
+ <name>name</name>
+ <description>description</description>
+ <info>some info;</info>
+ </router>
+ </monitor>
+</bmp-monitor>
+</source>
+----
+
+=== API Reference Documentation
+Javadocs are generated while creating mvn:site
+and they are located in target/ directory in each module.
include::bgpcep/odl-bgpcep-bgp-all-dev.adoc[BGP]
+include::bgpcep/odl-bgpcep-bmp-dev.adoc[BGP]
+
include::capwap/capwap-dev.adoc[CAPWAP]
include::controller/controller.adoc[Controller]
include::lacp/lacp-dev.adoc[]
+include::messaging4transport/messaging4transport-developer.adoc[]
+
include::controller/netconf/odl-netconf-dev.adoc[]
include::nic/nic-dev.adoc[]
include::sfc/sfc.adoc[]
+include::snmp4sdn/snmp4sdn-developer.adoc[SNMP4SDN]
+
include::sxp/odl-sxp-dev.adoc[]
include::tcpmd5/odl-tcpmd5-all-dev.adoc[TCP-MD5]
--- /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
=== Overview ===
The NetIDE Network Engine enables portability and cooperation inside a single
-network by using a client/server multi-controller architecture. Separate
-“Client SDN Controllers” host the various SDN Applications with their access
+network by using a client/server multi-controller SDN architecture. Separate
+"Client SDN Controllers" host the various SDN Applications with their access
to the actual physical network abstracted and coordinated through a single
-“Server SDN Controller”, in this instance OpenDaylight. This allows
+"Server SDN Controller", in this instance OpenDaylight. This allows
applications written for Ryu/Floodlight/Pyretic to execute on OpenDaylight
managed infrastructure.
The "Network Engine" is modular by design:
-. An OpenDaylight plugin, "shim", sends/receives messages to/from subscribed SDN Client Controllers. This consumes the ODL Openflow Plugin
-. An initial suite of SDN Client Controller "Backends": Floodlight, Ryu, Pyretic. Further controllers may be added over time as the engine is extensible.
-=== How to develop with the NetIDE project ===
+* An OpenDaylight plugin, "shim", sends/receives messages to/from subscribed SDN
+Client Controllers. This consumes the ODL OpenFlow Plugin
+* An initial suite of SDN Client Controller "Backends": Floodlight, Ryu, Pyretic.
+Further controllers may be added over time as the engine is extensible.
+
+The Network Engine provides a compatibility layer capable of translating calls of
+the network applications running on top of the client controllers, into calls for
+the server controller framework. The communication between the client and the
+server layers is achieved through the NetIDE intermediate protocol,
+which is an application-layer protocol on top of TCP that transmits the network
+control/management messages from the client to the server controller and vice-versa.
+Between client and server controller sits the Core Layer which also "speaks" the
+intermediate protocol. The core layer implements three main functions:
+
+... interfacing with the client backends and server shim, controlling the lifecycle
+of controllers as well as modules in them,
+... orchestrating the execution of individual modules (in one client controller)
+or complete applications (possibly spread across multiple client controllers),
+... interfacing with the tools.
+
+.NetIDE Network Engine Architecture
+image::netide/arch-engine.jpg[width=500]
+
+=== NetIDE Intermediate Protocol ===
+
+The Intermediate Protocol serves several needs, it has to:
+
+... carry control messages between core and shim/backend, e.g., to start up/take
+down a particular module, providing unique identifiers for modules,
+... carry event and action messages between shim, core, and backend, properly
+demultiplexing such messages to the right module based on identifiers,
+... encapsulate messages specific to a particular SBI protocol version (e.g.,
+OpenFlow 1.X, NETCONF, etc.) towards the client controllers with proper information
+to recognize these messages as such.
The NetIDE packages can be added as dependencies in Maven projects by putting the
following code in the _pom.xml_ file.
The current stable version for NetIDE is `0.1.0-Beryllium`.
+
+
+==== Protocol specification
+
+Messages of the NetIDE protocol contain two basic elements: the NetIDE header and
+the data (or payload). The NetIDE header, described below, is placed
+before the payload and serves as the communication and control link between the
+different components of the Network Engine. The payload can contain management
+messages, used by the components of the Network Engine to exchange relevant
+information, or control/configuration messages (such as OpenFlow, NETCONF, etc.)
+crossing the Network Engine generated by either network application modules or by
+the network elements.
+
+The NetIDE header is defined as follows:
+
+ 0 1 2 3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | netide_ver | type | length |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | xid |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | module_id |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+ | |
+ + datapath_id +
+ | |
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+where each tick mark represents one bit position. Alternatively, in a C-style coding
+format, the NetIDE header can be represented with the following structure:
+
+ struct netide_header {
+ uint8_t netide_ver ;
+ uint8_t type ;
+ uint16_t length ;
+ uint32_t xid
+ uint32_t module_id
+ uint64_t datapath_id
+ };
+
+* +netide_ver+ is the version of the NetIDE protocol (the current version is v1.2, which
+is identified with value 0x03).
+* +length+ is the total length of the payload in bytes.
+* +type+ contains a code that indicates the type of the message according with the
+following values:
++
+ enum type {
+ NETIDE_HELLO = 0x01 ,
+ NETIDE_ERROR = 0x02 ,
+ NETIDE_MGMT = 0x03 ,
+ MODULE_ANNOUNCEMENT = 0x04 ,
+ MODULE_ACKNOWLEDGE = 0x05 ,
+ NETIDE_HEARTBEAT = 0x06 ,
+ NETIDE_OPENFLOW = 0x11 ,
+ NETIDE_NETCONF = 0x12 ,
+ NETIDE_OPFLEX = 0x13
+ };
++
+* +datapath_id+ is a 64-bit field that uniquely identifies the network elements.
+* +module_id+ is a 32-bits field that uniquely identifies Backends and application modules running
+on top of each client controller. The composition mechanism in the core layer leverages
+on this field to implement the correct execution flow of these modules.
+* +xid+ is the transaction identifier associated to the each message. Replies must use the same
+value to facilitate the pairing.
+
+
+==== Module announcement
+
+The first operation performed by a Backend is registering itself and the modules that
+it is running to the Core. This is done by using the +MODULE_ANNOUNCEMENT+ and
++MODULE_ACKNOWLEDGE+ message types. As a result of this process, each Backend and
+application module can be recognized by the Core through an identifier (the +module_id+)
+placed in the NetIDE header. First, a Backend registers itself by using the following
+schema: backend-<platform name>-<pid>.
+
+For example,odule a Ryu Backend will register by using the following name in the message
+backend-ryu-12345 where 12345 is the process ID of the registering instance of the
+Ryu platform. The format of the message is the following:
+
+ struct NetIDE_message {
+ netide_ver = 0x03
+ type = MODULE_ANNOUNCEMENT
+ length = len(" backend -< platform_name >-<pid >")
+ xid = 0
+ module_id = 0
+ datapath_id = 0
+ data = " backend -< platform_name >-<pid >"
+ }
+
+The answer generated by the Core will include a +module_id+ number and the Backend name in
+the payload (the same indicated in the +MODULE_ANNOUNCEMENT+ message):
+
+ struct NetIDE_message {
+ netide_ver = 0x03
+ type = MODULE_ACKNOWLEDGE
+ length = len(" backend -< platform_name >-<pid >")
+ xid = 0
+ module_id = MODULE_ID
+ datapath_id = 0
+ data = " backend -< platform_name >-<pid >"
+ }
+
+Once a Backend has successfully registered itself, it can start registering its modules with the same
+procedure described above by indicating the name of the module in the data (e.g. data="Firewall").
+From this point on, the Backend will insert its own +module_id+ in the header of the messages it generates
+ (e.g. heartbeat, hello messages, OpenFlow echo messages from the client controllers, etc.).
+Otherwise, it will encapsulate the control/configuration messages (e.g. FlowMod, PacketOut,
+FeatureRequest, NETCONF request, etc.) generated by network application modules with the specific
++module_id+s.
+
+
+==== Heartbeat
+
+The heartbeat mechanism has been introduced after the adoption of the ZeroMQ messaging queuing
+library to transmit the NetIDE messages. Unfortunately, the ZeroMQ library does not offer any
+mechanism to find out about disrupted connections (and also completely unresponsive peers).
+This limitation of the ZeroMQ library can be an issue for the Core's composition mechanism and for
+the tools connected to the Network Engine, as they cannot understand when an client controller
+disconnects or crashes. As a consequence, Backends must periodically send (let's say every 5
+seconds) a "heartbeat" message to the Core. If the Core does not receive at least one "heartbeat"
+message from the Backend within a certain timeframe, the Core considers it disconnected, removes
+all the related data from its memory structures and informs the relevant tools. The format of the
+message is the following:
+
+ struct NetIDE_message {
+ netide_ver = 0x03
+ type = NETIDE_HEARTBEAT
+ length = 0
+ xid = 0
+ module_id = backend -id
+ datapath_id = 0
+ data = 0
+ }
+
+==== Handshake
+
+Upon a successful connection with the Core, the client controller must immediately send a hello
+message with the list of the control and/or management protocols needed by the applications
+deployed on top of it.
+
+ struct NetIDE_message {
+ struct netide_header header ;
+ uint8 data [0]
+ };
+
+The header contains the following values:
+
+* +netide ver=0x03+
+* +type=NETIDE_HELLO+
+* +length=2*NR_PROTOCOLS+
+* +data+ contains one 2-byte word (in big endian order) for each protocol, with the first
+byte containing the code of the protocol according to the above enum, while the second byte in-
+dictates the version of the protocol (e.g. according to the ONF specification, 0x01 for OpenFlow
+v1.0, 0x02 for OpenFlow v1.1, etc.). NETCONF version is marked with 0x01 that refers to the
+specification in the RFC6241, while OpFlex version is marked with 0x00 since this protocol is
+still in work-in-progress stage.
+
+The Core relays hello messages to the server controller which responds with another hello message
+containing the following:
+
+* +netide ver=0x03+
+* +type=NETIDE_HELLO+
+* +length=2*NR_PROTOCOLS+
+
+If at least one of the protocols requested by the client is supported. In particular, +data+ contains the
+codes of the protocols that match the client's request (2-bytes words, big endian order). If the hand-
+shake fails because none of the requested protocols is supported by the server controller, the header
+of the answer is as follows:
+
+* +netide ver=0x03+
+* +type=NETIDE_ERROR+
+* +length=2*NR_PROTOCOLS+
+* +data+ contains the codes of all the protocols supported by the server
+controller (2-bytes words, big endian order). In this case, the TCP session is terminated by the
+server controller just after the answer is received by the client.
+`
\ No newline at end of file
-== PCMM Developer and Testing (*Preliminary*)
+== PacketCable Developer Guide
-[[specification]]
-=== Specification
+[[pcmm-specification]]
+=== PCMM Specification
-http://www.cablelabs.com/wp-content/uploads/specdocs/PKT-SP-MM-I05-091029.pdf[PacketCable™
-Specification Multimedia Specification PKT-SP-MM-I05-091029]
+http://www.cablelabs.com/specification/packetcable-multimedia-specification[PacketCable™
+ Multimedia Specification]
[[system-overview]]
=== System Overview
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
+Gate Control messages and transmitted via COPS to the CCAP/CMTS. This plugin
adheres to the PCMM/COPS/PDP functionality defined in the CableLabs
specification. PacketCable solution is an MDSAL compliant component.
-// image:Screenshot6.png[width=500]
-//
-// image:Odp_diagram_helium_v6.jpg[width=500]
-
[[packetcable-components]]
-=== Packetcable Components
-
-packetcable is comprised of three OpenDaylight bundles
-
-[options=="header"]
-|========================================================================
-|Bundle |Description
-|packetcable-model |Contains the YANG information model for flows and
-nodes
+=== PacketCable Components
-|packetcable-provider |Provider hosts the model processing, RESTCONF,
-API implementation, and brokers requests to consumer
+The packetcable maven project is comprised of several modules.
-|packetcable-consumer |Consumer hosts packet codec and sends requests to
-driver
-|packetcable-driver |The codec for transforming the model into the
-appropriate PCMM Gate message for flows and CMTS connections.
-|========================================================================
+[options="header"]
+|=======================
+|Bundle |Description
+|packetcable-driver |A common module that containts the COPS stack and
+ manages all connections to CCAPS/CMTSes.
+|packetcable-emulator |A basic CCAP emulator to facilitate testing the
+ the plugin when no physical CCAP is avaible.
+|packetcable-policy-karaf |Generates a Karaf distribution with a config that
+ loads all the packetcable features at runtime.
+|packetcable-policy-model |Contains the YANG information model.
+|packetcable-policy-server |Provider hosts the model processing, RESTCONF,
+ and API implementation.
+|=======================
-See
-https://github.com/opendaylight/packetcable/tree/stable/lithium/packetcable-model/src/main/yang[YANG
-Model]
-[[tell-a-bundle-to-log-debug]]
-==== Tell a Bundle to Log Debug
+[[loging-levels]]
+==== Setting Logging Levels
+From the Karaf console
-`log:set org.opendaylight.packetcable.packetcable-provider`
+ log:set <LEVEL> (<PACKAGE>|<BUNDLE>)
+ Example
+ log:set DEBUG org.opendaylight.packetcable.packetcable-policy-server
[[tools-for-testing]]
=== Tools for Testing
-[[custom-testsuite]]
-==== Custom Testsuite
-
-Most of the
-https://wiki.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin::Python_test_scripts[Openflow tests for RESTCONF]
-can be adapted for PCMM and service flow
-testing.
-https://github.com/opendaylight/packetcable/tree/stable/lithium/packetcable-client[Browse
-this folder] for WIP of tests and examples used for minimum acceptance
-testing.
-
-[[restconfapi.py]]
-===== restconfapi.py
-
-Scripted series of packetcable actions testing minimum compliance.
-
-For example, adding a CMTS, adding IPv4 flow, delete flow and delete
-CMTS.
+[[postman]]
+==== Postman REST client for Chrome
-Other flows can be formulated and added to create a regression test of
-what kind of flows are interesting for use cases. Multicast?
+https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Install
+the Chrome extension]
-[[flow_config_perf_pcmm.py]]
-===== flow_config_perf_pcmm.py
+https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-policy-server/doc/restconf-samples[Download
+and import sample packetcable collection]
-For load testing there is this nice tool that could be repurpose to load
-test a CMTS.
-//TODO: Adapt this script for load testing PCMM on a CMTS.
+[[view-rest-api]]
+==== View Rest API
+1. Install the `odl-mdsal-apidocs` feature from the karaf console.
+2. Open http://localhost:8181/apidoc/explorer/index.html default dev build user/pass is admin/admin
+3. Navigate to the PacketCable section.
[[yang-ide]]
==== Yang-IDE
+Editing yang can be done in any text editor but Yang-IDE will help prevent mistakes.
https://github.com/xored/yang-ide/wiki/Setup-and-build[Setup and Build
Yang-IDE for Eclipse]
image:Screenshot8.png[width=500]
[[debugging-and-verifying-dqos-gate-flows-on-the-cmts]]
-=== Debugging and Verifying DQoS Gate (Flows) on the CMTS
+=== Debugging and Verifying DQoS Gate (Flows) on the CCAP/CMTS
-http://books.google.com/books?id==zNnCLUa8CHQC&pg==PA701&lpg==PA701&dq==show+packetcable+gate[This
-book] serves as a good reference. Below are some of the most useful CMTS
-commands to verify flows have been enabled on the CMTS.
+Below are some of the most useful CCAP/CMTS commands to verify flows have been
+enabled on the CMTS.
[[cisco]]
==== Cisco
--- /dev/null
+== SNMP4SDN Developer Guide
+=== Overview
+We propose a southbound plugin that can control the off-the-shelf commodity Ethernet switches for the purpose of building SDN using Ethernet switches. For Ethernet switches, forwarding table, VLAN table, and ACL are where one can install flow configuration on, and this is done via SNMP and CLI in the proposed plugin. In addition, some settings required for Ethernet switches in SDN, e.g., disabling STP and flooding, are proposed.
+
+.SNMP4SDN as an OpenDaylight southbound plugin
+image::snmp4sdn_in_odl_architecture.jpg["SNMP4SDN as an OpenDaylight southbound plugin",width=400]
+
+=== Architecture
+The modules in the plugin are depicted as the following figure.
+
+.Modules in the SNMP4SDN Plugin
+image::snmp4sdn_modules.jpg["Modules in the SNMP4SDN Plugin",width=400]
+
+* AclService: add/remove ACL profile and rule on the switches.
+* FdbService: add/modify/remove FDB table entry on the switches.
+* VlanService: add/modify/remove VLAN table entry on the switches.
+* TopologyService: query and acquire the subnet topology.
+* InventoryService: acquire the switches and their ports.
+* DiscoveryService: probe and resolve the underlying switches as well as the port pairs connecting the switches. The probing is realized by SNMP queries. The updates from discovery will also be reflected to the TopologyService.
+* MiscConfigService: do kinds of settings on switches
+** Supported STP and ARP settings such as enable/disable STP, get port's STP state, get ARP table, set ARP entry, and others
+* VendorSpecificHandler: to assist the flow configuration services to call the switch-talking modules with correct parameters value and order.
+* Switch-talking modules
+** For the services above, when they need to read or configure the underlying switches via SNMP or CLI, these queries are dealt with the modules SNMPHandler and CLIHandler which directly talk with the switches. The SNMPListener is to listen to snmp trap such as link up/down event or switch on/off event.
+
+=== Design
+In terms of the architecture of the SNMP4SDN Plugin's features, the features include flow configuration, topology discovery, and multi-vendor support. Their architectures please refer to Wiki (https://wiki.opendaylight.org/view/SNMP4SDN:Developer_Guide#Design[Developer Guide - Design]).
+
+=== Installation and Configuration Guide
+* Please refer to the 'Getting Started Guide' in https://www.opendaylight.org/downloads, find the SNMP4SDN section.
+* For the latest full guide, please refer to Wiki (https://wiki.opendaylight.org/view/SNMP4SDN:Installation_Guide[Installation Guide], https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Configuration[User Guide - Configuration]).
+
+=== Tutorial
+* For the latest full guide, please refer to Wiki (https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Tutorial_.2F_How-To[User Guide - Tutorial]).
+
+// === Commit the code via Git CLI
+// The steps to commit code is the same with controller's project, please refer to Wiki (https://wiki.opendaylight.org/view/OpenDaylight_Controller:Pulling,_Hacking,_and_Pushing_the_Code_from_the_CLI#Commit_the_code_via_Git_CLI[here]). Just note to replace the Git location as
+// ----
+// ssh://username@git.opendaylight.org29418/snmp4sdn.git
+// ----
+
+=== Programmatic Interface(s)
+SNMP4SDN Plugin exposes APIs via MD-SAL with YANG model. The methods (RPC call) and data structures for them are listed below.
+
+==== TopologyService
+* RPC call
+** get-edge-list
+** get-node-list
+** get-node-connector-list
+** set-discovery-interval (given interval time in seconds)
+** rediscover
+
+* Data structure
+** node: composed of node-id, node-type
+** node-connector: composed of node-connector-id, node-connector-type, node
+** topo-edge: composed of head-node-connector-id, head-node-connector-type, head-node-id, head-node-type, tail-node-connector-id, tail-node-connector-type, tail-node-id, tail-node-type
+
+==== VlanService
+* RPC call
+** add-vlan (given node ID, VLAN ID, VLAN name)
+** add-vlan-and-set-ports (given node ID, VLAN ID, VLAN name, tagged ports, untagged ports)
+** set-vlan-ports (given node ID, VLAN ID, tagged ports, untagged ports)
+** delete-vlan (given node ID, VLAN ID)
+** get-vlan-table (given node ID)
+
+==== AclService
+* RPC call
+** create-acl-profile (given node ID, acl-profile-index, acl-profile)
+** del-acl-profile (given node ID, acl-profile-index)
+** set-acl-rule (given node ID, acl-index, acl-rule)
+** del-acl-rule (given node ID, acl-index)
+** clear-acl-table (given node ID)
+
+* Data structure
+** acl-profile-index: composed of profile-id, profile name
+** acl-profile: composed of acl-layer, vlan-mask, src-ip-mask, dst-ip-mask
+** acl-layer: IP or ETHERNET
+** acl-index: composed of acl-profile-index, acl-rule-index
+** acl-rule-index: composed of rule-id, rule-name
+** acl-rule: composed of port-list, acl-layer, acl-field, acl-action
+** acl-field: composed of vlan-id, src-ip, dst-ip
+** acl-action: PERMIT or DENY
+
+==== FdbService
+* RPC call
+** set-fdb-entry (given fdb-entry)
+** del-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
+** get-fdb-entry (given node-id, vlan-id, dest-mac-adddr)
+** get-fdb-table (given node-id)
+
+* Data structure
+** fdb-entry: composed of node-id, vlan-id, dest-mac-addr, port, fdb-entry-type
+** fdb-entry-type: OTHER/INVALID/LEARNED/SELF/MGMT
+
+==== MiscConfigService
+* RPC call
+** set-stp-port-state (given node-id, port, is_nable)
+** get-stp-port-state (given node-id, port)
+** get-stp-port-root (given node-id, port)
+** enable-stp (given node-id)
+** disable-stp (given node-id)
+** delete-arp-entry (given node-id, ip-address)
+** set-arp-entry (given node-id, arp-entry)
+** get-arp-entry (given node-id, ip-address)
+** get-arp-table (given node-id)
+
+* Data structure
+** stp-port-state: DISABLE/BLOCKING/LISTENING/LEARNING/FORWARDING/BROKEN
+** arp-entry: composed of ip-address and mac-address
+
+==== SwitchDbService
+* RPC call
+** reload-db
+(The following 4 RPC implemention is TBD)
+** add-switch-entry
+** delete-switch-entry
+** clear-db
+** update-db
+
+* Data structure
+** switch-info: compose of node-ip, node-mac, community, cli-user-name, cli-password, model
+
+=== Help
+* https://wiki.opendaylight.org/view/SNMP4SDN:Main[SNMP4SDN Wiki]
+* SNMP4SDN Mailing List (https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-users[user], https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-dev[developer])
+* https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Troubleshooting[Latest troubleshooting in Wiki]
+
include::ovsdb/ovsdb-install.adoc[]
-include::tsdr/tsdr-h2-install.adoc[]
-
-include::tsdr/tsdr-hbase-install.adoc[]
+include::tsdr/tsdr-installation-guide.adoc[]
include::vtn/vtn-install.adoc[]
+++ /dev/null
-== TSDR H2 Default Datastore Installation Guide
-This document is for the user to install the artifacts that are needed
-for using Time Series Data Repository (TSDR) functionality in the ODL Controller by enabling the default JPA (H2) Datastore. TSDR is new functionality added in OpenDaylight in Lithium Release.
-
-=== Overview
-In Lithium Release the time deries data records of OpenFlow statistics are collected periodically and stored in a persistent store. For non-production usage, the bundled default JPA based datastore (H2) is utilized based on odl-tsdr-all feature installation. The TSDR records get persisted in H2 store in <install folder>/tsdr/ folder by default.
-
-=== Pre Requisites for Installing TSDR with default H2 datastore
-There are no additional pre-requisites for TSDR based on default datastore
-
-=== Preparing for Installation
-No additional steps required for preparation of installing TSDR feature
-
-=== Installing TSDR with default H2 datastore
-Once OpenDaylight distribution is up, from karaf console install the TSDR feature with default datastore (JPA based datastore H2 store used) can be installed by
-
-feature:install odl-tsdr-all
-
-This will install all dependency features (and can take sometime) before returning control to the console.
-
-=== Verifying your Installation
-If the feature install was successful you should be able to see the following tsdr commands added
-
-**tsdr:list
-**tsdr:purgeAll
-
-==== Troubleshooting
-Check the ../data/log/karaf.log for any exception related to TSDR or JPA related features
-
-=== Post Installation Configuration
-The feature installation takes care of automated configuration of the datasource by installing a file in <install folder>/etc named org.ops4j.datasource-metric.cfg. This contains the default location of <install folder>/tsdr where the H2 datastore files are stored. If you want to change the default location of the datastore files to some other location update the last portion of the url property in the org.ops4j.datasource-metric.cfg and then restart the karaf container
-
-=== Upgrading From a Previous Release
-Lithium being the first release supporting TSDR functionality, only fresh installation is possible.However if you want to move to production usage by enabling the store HBase for TSDR usage, you can do it by uninstalling the TSDR with default H2 datastore, restarting the Karaf container and then enabling the TSDR with HBase store as documented in tsdr-hbase-install.doc
-
-=== Uninstalling TSDR with default H2 datastore
-To uninstall the TSDR functionality with the default store, you need to do the following from karaf console
-* feature:uninstall odl-tsdr-all
-* feature:uninstall odl-tsdr-core
-* feature:uninstall odl-tsdr-H2-persistence
-
-Its recommended to restart the Karaf container after uninstallation of the TSDR functionality with the default store
-
+++ /dev/null
-== TSDR HBase Data Store Installation Guide
-This document is for the user to install the artifacts that are needed
-for using HBase Data Store in Time Series Data Repository, which is
-a new feature available in OpenDaylight Lithium release.
-
-=== Overview
-The Time Series Data Repository (TSDR) project in OpenDaylight (ODL) creates a framework for collecting, storing, querying, and maintaining time series data in the OpenDaylight SDN controller. It contains the following services and components:
-
-* Data Collection Service
-* Data Storage Service
-* TSDR Persistence Layer with data stores as plugins
-* TSDR Data Stores
-* Data Query Service
-* Data Aggregation Service
-* Data Purging Service
-
-Data Collection Service handles the collection of time series data into TSDR and hands it over to Data Storage Service. Data Storage Service stores the data into TSDR through TSDR Persistence Layer. TSDR Persistence Layer provides generic Service APIs allowing various data stores to be plugged in. Data Aggregation Service aggregates time series fine-grained raw data into course-grained roll-up data to control the size of the data. Data Purging Service periodically purges both fine-grained raw data and course-granined aggregated data according to user-defined schedules.
-
-
-In Lithium, we implemented Data Collection Service, Data Storage Service, TSDR Persistence Layer, TSDR HBase Data Store, and TSDR H2 Data Store. Among these services and components, time series data is communicated using a common TSDR data model, which is designed and implemented for the abstraction of the time series data commonalities. With these functions, TSDR will be able to collect the data from the data sources and store them into one of the TSDR data stores: either HBase Data Store or H2 Data Store. We also provided a simple query command from Karaf console for the user to retrieve TSDR data from the data stores.
-
-A future release will contain Data Aggregation service, Data Purging Service, and a full-fledged Data Query Service with Norghbound APIs.
-
-
-=== Prerequisites for Installing TSDR HBase Data Store
-The hardware requirements are the same as those for standard ODL controller installation.
-
-The software requirements for TSDR HBase Data Store are as follows:
-
-* The supported operating system for TSDR HBase Data Store is Linux. We do not support TSDR HBase Data Store on Windows.
-* Besides the software that ODL requires, we also require HBase database running on top of Hadoop single node.
-
-=== Preparing for Installation
-Download HBase (version number to be finalized) from the following website.
-
-http://archive.apache.org/dist/hbase/hbase-0.94.15/
-
-
-=== Installing TSDR HBase Data Store
-Installing TSDR HBase Data Store contains two steps:
-
- * Installing HBase server, and
- * Installing TSDR HBase Data Store features from ODL Karaf console.
-
-This installation guide will only cover the first step. For installing TSDR HBase Data Store features, please refer to TSDR HBase Data Store User Guide.
-
-In Lithium, we only support HBase single node running together on the same machine as ODL controller. Therefore, follow the steps to download and install HBase server onto the same box as where ODL controller is running:
-
-* Create a folder in Linux operating system for the HBase server.
-
-For example, create an hbase directory under /usr/lib:
-
- mkdir /usr/lib/hbase
-
-* Unzip the downloaded HBase server tar file.
-
-Run the following command to unzip the installation package:
-
- tar xvf <hbase-installer-name> /usr/lib/hbase
-
-* Make proper changes in hbase-site.xml
-
- .. Under <hbase-install-directory>/conf/, there is a hbase-site.xml. Although it is not recommended, an experience user with HBase canmodify the data directory for hbase server to store the data.
-
- .. Modify the value of the property with name "hbase.rootdir" in the file to reflect the desired file directory for storing hbase data.
-
-The following is an example of the file:
-
- <configuration>
- <property>
- <name>hbase.rootdir</name>
- <value>file:///usr/lib/hbase/data</value>
- </property>
- <property>
- <name>hbase.zookeeper.property.dataDir</name>
- <value>/usr/lib/hbase/zookeeper</value>
- </property>
- </configuration>
-
-
-=== Verifying your Installation
-After the HBase server is properly installed, start hbase server and hbase shell.
-
-.. start hbase server
-
- cd <hbase-installation-directory>
- ./start-hbase.sh
-
-.. start hbase shell
-
- cd <hbase-insatllation-directory>
- ./hbase shell
-
-=== Post Installation Configuration
-Please refer to HBase Data Store User Guide.
-
-=== Upgrading From a Previous Release
-Lithium is the first release of TSDR. Upgrading is not applicable for TSDR Lithium release.
-
-=== Uninstalling HBase Data Store
-To uninstall TSDR HBase Data Store,
-
-.. stop hbase server
-
- cd <hbase-installation-directory>
- ./stop-hbase.sh
-
-.. remove the file directory that contains the HBase server installation.
-
- rm -r <hbase-installation-directory>
--- /dev/null
+== TSDR Installation Guide
+This document is for the user to install the artifacts that are needed
+for using Time Series Data Repository (TSDR) functionality in the ODL
+Controller by enabling either an HSQLDB, HBase, or Cassandra Data Store.
+
+
+=== Overview
+The Time Series Data Repository (TSDR) project in OpenDaylight (ODL) creates a framework for collecting, storing, querying, and maintaining time series data in the OpenDaylight SDN controller. Please refer to the User Guide for the detailed description of the functionality of the project and how to use the corresponding features provided in TSDR.
+
+=== Pre Requisites for Installing TSDR
+The software requirements for TSDR HBase Data Store are as follows:
+
+* In the case when the user chooses HBase or Cassandra data store, besides the software that ODL requires, we also require HBase and Cassandra database running in single node deployment scenario.
+
+No additional software is required for the HSQLDB Data Stores.
+
+=== Preparing for Installation
+* When using HBase data store, download HBase from the following website:
+
+ http://archive.apache.org/dist/hbase/hbase-0.94.15/
+
+* When using Cassandra data store, download Cassandra from the following website:
+
+ http://www.eu.apache.org/dist/cassandra/2.1.10/
+
+* No additional steps are required to install the TSDR HSQL Data Store.
+
+=== Installing TSDR Data Stores
+==== Installing HSQLDB Data Store
+Once OpenDaylight distribution is up, from karaf console install the HSQLDB data store using the following command:
+
+ feature:install odl-tsdr-hsqldb-all
+
+This will install hsqldb related dependency features (and can take sometime) as well as openflow statistics collector before returning control to the console.
+e
+
+==== Installing HBase Data Store
+Installing TSDR HBase Data Store contains two steps:
+
+ * Installing HBase server, and
+ * Installing TSDR HBase Data Store features from ODL Karaf console.
+
+In Beryllium, we only support HBase single node running together on the same machine as OpenDaylight. Therefore, follow the steps to download and install HBase server onto the same machine as where OpenDaylight is running:
+
+* Create a folder in Linux operating system for the HBase server.
+
+For example, create an hbase directory under /usr/lib:
+
+ mkdir /usr/lib/hbase
+
+* Unzip the downloaded HBase server tar file.
+
+Run the following command to unzip the installation package:
+
+ tar xvf <hbase-installer-name> /usr/lib/hbase
+
+* Make proper changes in hbase-site.xml
+
+ .. Under <hbase-install-directory>/conf/, there is a hbase-site.xml. Although it is not recommended, an experienced user with HBase can modify the data directory for hbase server to store the data.
+
+ .. Modify the value of the property with name "hbase.rootdir" in the file to reflect the desired file directory for storing hbase data.
+
+The following is an example of the file:
+
+ <configuration>
+ <property>
+ <name>hbase.rootdir</name>
+ <value>file:///usr/lib/hbase/data</value>
+ </property>
+ <property>
+ <name>hbase.zookeeper.property.dataDir</name>
+ <value>/usr/lib/hbase/zookeeper</value>
+ </property>
+ </configuration>
+
+* start hbase server
+
+ cd <hbase-installation-directory>
+ ./start-hbase.sh
+
+* start hbase shell
+
+ cd <hbase-insatllation-directory>
+ ./hbase shell
+
+* start Karaf console
+
+* install hbase data store feature from Karaf console
+
+ feature:install odl-tsdr-hbase
+
+==== Installing Cassandra Data Store
+Installing TSDR Cassandra Data Store contains two steps:
+
+ * Installing Cassandra server, and
+ * Installing TSDR Cassandra Data Store features from ODL Karaf console.
+
+In Beryllium, we only support Cassadra single node running together on the same machine as OpenDaylight. Therefore, follow these steps to download and install Cassandra server onto the same machine as where OpenDaylight is running:
+
+Install Cassandra (latest stable version) by downloading the zip file and untar the tar ball to cassandra/ directory on the testing machine.
+
+ mkdir cassandra
+ wget http://www.eu.apache.org/dist/cassandra/2.1.10/apache-cassandra-2.1.10-bin.tar.gz[2.1.10 is current stable version, it can vary]
+ mv apache-cassandra-2.1.10-bin.tar.gz cassandra/
+ cd cassandra
+ tar -xvzf apache-cassandra-2.1.10-bin.tar.gz
+
+Start Cassandra from cassandra directory by running:
+
+ ./apache-cassandra-2.1.10/bin/cassandra
+
+Start cassandra shell by running:
+
+ ./apache-cassandra-2.1.10/bin/cqlsh
+
+Start Karaf according to the instructions above.
+
+Install Cassandra data store feature from Karaf console:
+
+ feature:install odl-tsdr-cassandra
+
+=== Verifying your Installation
+
+After the TSDR data store is installed, no matter whether it is HBase data store, Cassandra data store, or HSQLDB data store, the user can verify the installation with the following steps.
+
+* Verify if the following two tsdr commands are available from Karaf console:
+
+** tsdr:list
+** tsdr:purgeAll
+
+* Verify if openflow statisitcs data can be received successfully:
+
+** Run "feature:install odl-tsdr-openflow-statistics-collector" from Karaf.
+
+** Run mininet to connect to ODL controller. For example, use the following command to start a three node topology:
+
+ "mn --topo single,3 --controller 'remote,ip=172.17.252.210,port=6653' --switch ovsk,protocols=OpenFlow13"
+
+** From Karaf console, the user should be able to retrieve the statistics data of OpenFlow statistics data from the console:
+
+ tsdr:list FLOWSTATS
+
+==== Troubleshooting
+Check the ../data/log/karaf.log for any exception related to TSDR features.
+
+==== Post Installation Configuration
+===== Post Installation Configuration for HSQLDB Data Store
+
+The feature installation takes care of automated configuration of the datasource by installing a file in <install folder>/etc named org.ops4j.datasource-metric.cfg. This contains the default location of <install folder>/tsdr where the HSQLDB datastore files are stored. If you want to change the default location of the datastore files to some other location update the last portion of the url property in the org.ops4j.datasource-metric.cfg and then restart the Karaf container.
+
+===== Post Installation Configuration for HBase Data Store
+
+Please refer to HBase Data Store User Guide.
+
+===== Post Installation Configuration for Cassandra Data Store
+
+There is no post configuration for TSDR Cassandra data store.
+
+=== Upgrading From a Previous Release
+The HBase data store was supported in the previous release as well as in this release. However, we do not support data store upgrade for HBase data store.
+The user needs to reinstall TSDR and start to collect data in TSDR HBase datastore after the installation.
+
+HSQLDB and Cassandra are new data stores introduced in this release. Therefore, upgrading from previous release does not apply in these two data store scenarios.
+
+=== Uninstalling TSDR Data Stores
+==== To uninstall TSDR HSQLDB data store
+To uninstall the TSDR functionality with the default store, you need to do the following from karaf console
+
+ feature:uninstall odl-tsdr-hsqldb-all
+ feature:uninstall odl-tsdr-core
+ feature:uninstall odl-tsdr-hsqldb
+ feature:uninstall odl-tsdr-openflow-statistics-collector
+
+It is recommended to restart the Karaf container after the uninstallation of the TSDR functionality with the default store.
+
+==== To uninstall TSDR HBase Data Store
+To uninstall the TSDR functionality with the HBase data store,
+
+* Uninstall HBase data store related features from karaf console
+
+ feature:uninstall odl-tsdr-hbase
+ feature:uninstall odl-tsdr-core
+
+* stop hbase server
+
+ cd <hbase-installation-directory>
+ ./stop-hbase.sh
+
+* remove the file directory that contains the HBase server installation
+
+ rm -r <hbase-installation-directory>
+
+It is recommended to restart the Karaf container after the uninstallation of the TSDR data store.
+==== To uninstall TSDR Cassandra Data Store
+To uninstall the TSDR functionality with the Cassandra store,
+
+* uninstall cassandra data store related features following from karaf console
+
+ feature:uninstall odl-tsdr-cassandra
+ feature:uninstall odl-tsdr-core
+
+* stop cassandra database
+
+ ps auwx | grep cassandra
+ sudo kill pid
+
+* remove the cassandra installation files
+
+ rm <cassandra-installation-directory>
+
+It is recommended to restart the Karaf container after uninstallation of the TSDR data store.
<tag>HEAD</tag>
</scm>
<properties>
- <nexusproxy>http://nexus.opendaylight.org/content</nexusproxy>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<modules>
--- /dev/null
+== BGP Monitoring Protocol User Guide ==
+
+=== Overview ===
+
+The OpenDaylight Karaf distribution comes preconfigured with baseline BMP configuration.
+
+- *32-bmp.xml* (initial configuration for BMP messages handler service provider and BMP client/server dispatcher settings)
+- *42-bmp-example.xml* (sample initial configuration for the BMP Monitoring Station application)
+
+=== Configuring BMP ===
+
+==== Server Binding ====
+The default shipped configuration will start a BMP server on 0.0.0.0:12345.You can change this behavior in *42-bmp-example.xml*:
+
+[source,xml]
+----
+ <module>
+ <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">prefix:bmp-monitor-impl</type>
+ <name>example-bmp-monitor</name>
+ <!--<binding-address>0.0.0.0</binding-address>-->
+ <binding-port>12345</binding-port>
+ ...
+ </module>
+----
+
+- *binding-address* - adress on which BMP will be started and listen; to change value, uncomment then line first
+- *binding-port* - port on which the address will be started and listen
+
+Multiple instances of the BMP monitoring station (*bmp-monitor-impl* module) can be created. However, each instance must have a unique pair of *binding-address* and *binding-port*
+
+==== Active mode ====
+OpenDaylight's BMP might be configured to act as an active party of the connection (ODL BMP < = > Monitored router). To enable this functionality,
+configure monitored-router with mandatory parameters:
+
+* address (must be unique for each configured "monitored-router"),
+* port,
+* active.
+
+See following example from 42-bmp-example.xml:
+
+[source,xml]
+----
+ <monitored-router>
+ <address>192.0.2.2</address>
+ <port>1234</port>
+ <active>true</active>
+ </monitored-router>
+----
+
+=== Configuration through RESTCONF ===
+
+==== Server Binding ====
+
+*URL:*
+_http://<controllerIP>:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor_
+
+*Content-Type:*
+application/xml
+
+*Method:*
+PUT
+
+*Body:*
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <name>example-bmp-monitor</name>
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">x:bmp-monitor-impl</type>
+ <bmp-dispatcher xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type>bmp-dispatcher</type>
+ <name>global-bmp-dispatcher</name>
+ </bmp-dispatcher>
+ <codec-tree-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">x:binding-codec-tree-factory</type>
+ <name>runtime-mapping-singleton</name>
+ </codec-tree-factory>
+ <extensions xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:spi">x:extensions</type>
+ <name>global-rib-extensions</name>
+ </extensions>
+ <binding-address xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">0.0.0.0</binding-address>
+ <dom-data-provider xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">x:dom-async-data-broker</type>
+ <name>pingpong-broker</name>
+ </dom-data-provider>
+ <binding-port xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">12345</binding-port>
+</module>
+----
+
+* change values for *binding-address* and/or *binding-port*
+
+==== Active mode ====
+
+*URL:*
+_http://<controllerIP>:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/config:module/odl-bmp-impl-cfg:bmp-monitor-impl/example-bmp-monitor_
+
+*Content-Type:*
+application/xml
+
+*Method:*
+PUT
+
+*Body:*
+[source,xml]
+----
+<module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
+ <name>example-bmp-monitor</name>
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">x:bmp-monitor-impl</type>
+ <bmp-dispatcher xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type>bmp-dispatcher</type>
+ <name>global-bmp-dispatcher</name>
+ </bmp-dispatcher>
+ <codec-tree-factory xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">x:binding-codec-tree-factory</type>
+ <name>runtime-mapping-singleton</name>
+ </codec-tree-factory>
+ <extensions xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:bgp:rib:spi">x:extensions</type>
+ <name>global-rib-extensions</name>
+ </extensions>
+ <binding-address xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">0.0.0.0</binding-address>
+ <dom-data-provider xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <type xmlns:x="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">x:dom-async-data-broker</type>
+ <name>pingpong-broker</name>
+ </dom-data-provider>
+ <binding-port xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">12345</binding-port>
+ <monitored-router xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">
+ <address xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">127.0.0.1</address>
+ <port xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">1234</port>
+ <active xmlns="urn:opendaylight:params:xml:ns:yang:controller:bmp:impl">true</active>
+ </monitored-router>
+</module>
+----
+
+* change values for *address* and *port*
include::bgpcep/odl-bgpcep-bgp-all-user.adoc[BGP]
+include::bgpcep/odl-bgpcep-bmp-user.adoc[BMP]
+
include::capwap/capwap-user.adoc[CAPWAP]
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::netide/odl-netide-user-guide.adoc[NetIDE]
include::snmp/snmp-user-guide.adoc[SNMP]
+include::snmp4sdn/snmp4sdn-user-guide.adoc[SNMP4SDN]
+
include::sxp/odl-sxp-user.adoc[]
include::tcpmd5/odl-tcpmd5-all-user.adoc[TCP-MD5]
-include::tsdr/tsdr-h2-user.adoc[]
-
-include::tsdr/tsdr-hbase-user.adoc[]
+include::tsdr/tsdr-user-guide.adoc[]
include::ttp/ttp-cli-tools-user.adoc[TTP]
+include::unimgr/unimgr-user.adoc[]
+
include::usc/odl-usc-channel-user.adoc[USC]
include::vtn/vtn-user.adoc[]
--- /dev/null
+==== Overview
+
+The FaaS renderer feature enables leveraging the FaaS project as a GBP renderer.
+
+===== Installing and Pre-requisites
+
+From the Karaf console in OpenDaylight:
+
+ feature:install odl-groupbasedpolicy-faas
+
+More information about FaaS can be found here: https://wiki.opendaylight.org/view/FaaS:GBPIntegration
--- /dev/null
+==== Overview
+
+The IO Visor renderer feature enables container endpoints (e.g. Docker, LXC) to leverage GBP policies.
+
+The renderer interacts with a IO Visor module from the Linux Foundation IO Visor project.
+
+===== Installing and Pre-requisites
+
+From the Karaf console in OpenDaylight:
+
+ feature:install odl-groupbasedpolicy-iovisor odl-restconf
+
+Installation details, usage, and other information for the IO Visor GBP module can be found here: https://github.com/iovisor/iomodules[*IO Visor* github repo for IO Modules]
This section is for Application Developers and Network Administrators
who are looking to integrate Group Based Policy with OpenStack.
-To enable the *GBP* Neutron Mapper feature, at the karaf console:
+To enable the *GBP* Neutron Mapper feature, at the Karaf console:
feature:install odl-groupbasedpolicy-neutronmapper
odl-groupbasedpolicy-ofoverlay
-For Lithium, *GBP* has one renderer, hence this is loaded by default.
+// For Lithium, *GBP* has one renderer, hence this is loaded by default.
REST calls from OpenStack Neutron are by the Neutron NorthBound project.
*Troubleshooting within GBP*
-Logging level for the mapping functionality can be set for package org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling TRACE logging level on karaf console:
+Logging level for the mapping functionality can be set for package org.opendaylight.groupbasedpolicy.neutron.mapper. An example of enabling TRACE logging level on Karaf console:
log:set TRACE org.opendaylight.groupbasedpolicy.neutron.mapper
The OpenFlow Overlay (OfOverlay) feature enables the OpenFlow Overlay
renderer, which creates a network virtualization solution across nodes
-that host OpenvSwitch software switches.
+that host Open vSwitch software switches.
===== Installing and Pre-requisites
-From the karaf console in OpenDaylight:
+From the Karaf console in OpenDaylight:
feature:install odl-groupbasedpolicy-ofoverlay
When this feature is loaded "standalone", the user is required to configure infrastructure, such as
-* instantiating OVS bridges,
-* attaching hosts to the bridges,
-* and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
+* instantiating OVS bridges,
+* attaching hosts to the bridges,
+* and creating the VXLAN/VXLAN-GPE tunnel ports on the bridges.
[[offset]]
-In Lithium, the *GBP* OfOverlay renderer also supports a table offset option, to offset the pipeline post-table 0.
+The *GBP* OfOverlay renderer also supports a table offset option, to offset the pipeline post-table 0.
The value of table offset is stored in the config datastore and it may be rewritten at runtime.
----
*Endpoint Manager*
-The endpoint repository, in Lithium, operates in *orchestrated* mode. This means the user is responsible for the provisioning of endpoints via:
+The endpoint repository operates in *orchestrated* mode. This means the user is responsible for the provisioning of endpoints via:
* <<UX,UX/GUI>>
* REST API
*Switch Manager*
-The Switch Manager has been refactored in Lithium to be purely a state manager.
+The Switch Manager is purely a state manager.
Switches are in one of 3 states:
Ingress from outside, goto Table _Ingress NAT Mapper_:
cookie=0x0, <snip> , priority=200,in_port=1 actions=goto_table:1
-
+
ARP from Endpoint, go to Table _Source Mapper_:
cookie=0x0, <snip> , priority=121,arp,in_port=5,dl_src=fa:16:3e:d5:b9:8d,arp_spa=10.1.1.3 actions=goto_table:2
DHCP DORA from Endpoint, go to Table _Source Mapper_:
cookie=0x0, <snip> , priority=115,ip,in_port=5,dl_src=fa:16:3e:d5:b9:8d,nw_dst=255.255.255.255 actions=goto_table:2
-
+
Series of DROP tables with priority set to capture any non-specific traffic that should have matched above:
cookie=0x0, <snip> , priority=112,ipv6 actions=drop
cookie=0x0, <snip> , priority=111, ip actions=drop
- cookie=0x0, <snip> , priority=110,arp actions=drop
+ cookie=0x0, <snip> , priority=110,arp actions=drop
"L2" catch all traffic not identified above:
Broadcast traffic destined for GroupTable:
cookie=0x0, <snip> , priority=140,reg5=0x5,dl_dst=01:00:00:00:00:00/01:00:00:00:00:00 actions=load:0x5->NXM_NX_TUN_ID[0..31],group:5
-
+
Layer3 destination matching flows, where priority=100+masklength. Since *GBP* now support L3Prefix endpoint, we can set default routes etc:
cookie=0x0, <snip>, priority=132,ip,reg6=0x7,dl_dst=fa:16:3e:b4:b4:b1,nw_dst=10.1.1.3 actions=load:0xc->NXM_NX_REG2[],load:0x1->NXM_NX_REG3[],load:0x5->NXM_NX_REG7[],set_field:fa:16:3e:b4:b4:b1->eth_dst,dec_ttl,goto_table:4
"endpoint-group": "<epg0>",
"endpoint-groups" : ["<epg1>","<epg2>"],
"network-containment" : "<fowarding-model-context1>",
- "l2-context": "<bridge-domain1>",
- "mac-address": "<mac1>",
+ "l2-context": "<bridge-domain1>",
+ "mac-address": "<mac1>",
"l3-address": [
{
- "ip-address": "<ipaddress1>",
+ "ip-address": "<ipaddress1>",
"l3-context": "<l3_context1>"
}
- ],
- "*ofoverlay:port-name*": "<ovs port name>",
+ ],
+ "*ofoverlay:port-name*": "<ovs port name>",
"tenant": "<tenant1>"
}
}
"opendaylight-inventory:nodes": {
"node": [
{
- "id": "openflow:123456",
+ "id": "openflow:123456",
"ofoverlay:tunnel": [
{
"tunnel-type": "overlay:tunnel-type-vxlan",
"node-connector-id": "openflow:123456:1"
}
]
- },
+ },
{
- "id": "openflow:654321",
+ "id": "openflow:654321",
"ofoverlay:tunnel": [
{
"tunnel-type": "overlay:tunnel-type-vxlan",
==== Tutorials[[Demo]]
-Comprehensive tutorials, along with a demonstration environment leveraging Vagrant
+Comprehensive tutorials, along with a demonstration environment leveraging Vagrant
can be found on the https://wiki.opendaylight.org/view/Group_Based_Policy_(GBP)[*GBP* wiki]
image::groupbasedpolicy/sfc-3-asymmetric.png[align="center",width=500]
-All these scenarios are supported by the Lithium integration.
+All these scenarios are supported by the integration.
In the *Subject Feature Instance* section of the tenant config, we define the instances of the classifier definitions for ICMP and HTTP:
----
+
By focusing on *Model. Process. Automation*, a consistent policy resolution process enables for mapping between the *expressed intent* and renderers responsible for providing the capabilities of implementing that intent.
-* recursive/intent level-independent behaviour.
+* recursive/intent level-independent behaviour.
+
Where _one person's concrete is another's abstract_, intent can be fulfilled through a hierarchical implementation of non-domain specific policy resolution. Domain specifics are provided by the _renderers_, and exposed via the API, at each policy resolution instance.
For example:
It is important to show the overall philosophy of *GBP* as it sets the project's direction.
-In the Lithium release of OpenDaylight, *GBP* focused on *expressed intent* and *capabilities*.
+In the Beryllium release of OpenDaylight, *GBP* focused on *expressed intent*, *refactoring of how renderers consume and publish Subject Feature Definitions for multi-renderer support*.
=== GBP Base Architecture and Value Proposition
==== Terminology
.GBP Forwarding Model Terminology - L3 Context, L2 Bridge Context, L2 Flood Context/Domain, Subnet
image::groupbasedpolicy/GBPTerminology3.png[align="center",width=500]
-* Endpoints:
+* Endpoints:
+
-Define concrete uniquely identifiable entities. In Lithium, examples could be a Docker container, or a Neutron port
-* EndpointGroups:
+Define concrete uniquely identifiable entities. In Beryllium, examples could be a Docker container, or a Neutron port
+* EndpointGroups:
+
EndpointGroups are sets of endpoints that share a common set of policies. EndpointGroups can participate in contracts that determine the kinds of communication that are allowed. EndpointGroups _consume_ and _provide_ contracts.
They also expose both _requirements and capabilities_, which are labels that help to determine how contracts will be applied. An EndpointGroup can specify a parent EndpointGroup from which it inherits.
-* Contracts:
+* Contracts:
+
-Contracts determine which endpoints can communicate and in what way. Contracts between pairs of EndpointGroups are selected by the contract selectors defined by the EndpointGroup.
-Contracts expose qualities, which are labels that can help EndpointGroups to select contracts. Once the contract is selected,
-contracts have clauses that can match against requirements and capabilities exposed by EndpointGroups, as well as any conditions
+Contracts determine which endpoints can communicate and in what way. Contracts between pairs of EndpointGroups are selected by the contract selectors defined by the EndpointGroup.
+Contracts expose qualities, which are labels that can help EndpointGroups to select contracts. Once the contract is selected,
+contracts have clauses that can match against requirements and capabilities exposed by EndpointGroups, as well as any conditions
that may be set on endpoints, in order to activate subjects that can allow specific kinds of communication. A contract is allowed to specify a parent contract from which it inherits.
* Subject
+
-Subjects describe some aspect of how two endpoints are allowed to communicate. Subjects define an ordered list of rules that will match against the traffic and perform any necessary actions on that traffic.
+Subjects describe some aspect of how two endpoints are allowed to communicate. Subjects define an ordered list of rules that will match against the traffic and perform any necessary actions on that traffic.
No communication is allowed unless a subject allows that communication.
* Clause
+
-Clauses are defined as part of a contract. Clauses determine how a contract should be applied to particular endpoints and EndpointGroups. Clauses can match against requirements and capabilities exposed by EndpointGroups,
+Clauses are defined as part of a contract. Clauses determine how a contract should be applied to particular endpoints and EndpointGroups. Clauses can match against requirements and capabilities exposed by EndpointGroups,
as well as any conditions that may be set on endpoints. Matching clauses define some set of subjects which can be applied to the communication between the pairs of endpoints.
==== Architecture and Value Proposition
.GBP Access (or Core) Model
image::groupbasedpolicy/GBP_AccessModel_simple.png[align="center",width=500]
-The _classifier_ and _action_ portions of the model can be thought of as hooks, with their definition provided by each _renderer_ about its domain specific capabilities. In *GBP* Lithium, there is one renderer,
+The _classifier_ and _action_ portions of the model can be thought of as hooks, with their definition provided by each _renderer_ about its domain specific capabilities. In *GBP* Beryllium, there is one renderer,
the _<<OfOverlay,OpenFlow Overlay renderer (OfOverlay).>>_
These hooks are filled with _definitions_ of the types of _features_ the renderer can provide the _subject_, and are called *subject-feature-definitions*.
.GBP Endpoints and the Forwarding Model
image::groupbasedpolicy/GBP_Endpoint_EPG_Forwarding.png[align="center",width=300]
-When the forwarding model is considered in the figure above, it can be seen that even though all endpoints are communicating using a common set of contracts,
+When the forwarding model is considered in the figure above, it can be seen that even though all endpoints are communicating using a common set of contracts,
their forwarding is _contained_ by the forwarding model contexts or namespaces.
-In the example shown, the endpoints associated with a _network-containment_ that has an ultimate parent of _L3Context:Sales_ can only communicate with other endpoints within this L3Context.
+In the example shown, the endpoints associated with a _network-containment_ that has an ultimate parent of _L3Context:Sales_ can only communicate with other endpoints within this L3Context.
In this way L3VPN services can be implemented without any impact to the *Intent* of the contract.
===== High-level implementation Architecture
The overall architecture, including _<<Neutron,Neutron>>_ domain specific mapping, and the <<OfOverlay,OpenFlow Overlay renderer>> looks as so:
-.GBP High Level Lithium Architecture
-image::groupbasedpolicy/GBP_High-levelLithiumArchitecture.png[align="center",width=300]
+.GBP High Level Beryllium Architecture
+image::groupbasedpolicy/GBP_High-levelBerylliumArchitecture.png[align="center",width=300]
-The major benefit of this architecture is that the mapping of the domain-specific-language is completely separate and independent of the underlying renderer implementation.
+The major benefit of this architecture is that the mapping of the domain-specific-language is completely separate and independent of the underlying renderer implementation.
-For instance, using the <<Neutron,Neutron Mapper>>, which maps the Neutron API to the *GBP* core model, any contract automatically generated from this mapping can be augmented via the <<UX,UX>>
+For instance, using the <<Neutron,Neutron Mapper>>, which maps the Neutron API to the *GBP* core model, any contract automatically generated from this mapping can be augmented via the <<UX,UX>>
to use <<SFC,Service Function Chaining>>, a capability not currently available in OpenStack Neutron.
When another renderer is added, for instance, NetConf, the same policy can now be leveraged across NetConf devices simultaneously:
-.GBP High Level Lithium Architecture - adding a renderer
+.GBP High Level Beryllium Architecture - adding a renderer
image::groupbasedpolicy/GBP_High-levelExtraRenderer.png[align="center",width=300]
As other domain-specific mappings occur, they too can leverage the same renderers, as the renderers only need to implement the *GBP* access and forwarding models, and the domain-specific mapping need only manage mapping to the access and forwarding models. For instance:
-.GBP High Level Lithium Architecture - adding a renderer
-image::groupbasedpolicy/High-levelLithiumArchitectureEvolution2.png[align="center",width=300]
+.GBP High Level Beryllium Architecture - adding a renderer
+image::groupbasedpolicy/High-levelBerylliumArchitectureEvolution2.png[align="center",width=300]
In summary, the *GBP* architecture:
The first step in policy resolution is to select the contracts that are in scope.
-EndpointGroups participate in contracts either as a _provider_ or as a _consumer_ of a contract. Each EndpointGroup can participate in many contracts at the same time, but for each contract it can be in only one role at a time.
+EndpointGroups participate in contracts either as a _provider_ or as a _consumer_ of a contract. Each EndpointGroup can participate in many contracts at the same time, but for each contract it can be in only one role at a time.
In addition, there are two ways for an EndpointGroup to select a contract: either with either a:
-* _named selector_
+* _named selector_
+
Named selectors simply select a specific contract by its contract ID.
* target selector.
Thus, there are a total of 4 kinds of contract selector:
-* provider named selector
+* provider named selector
+
Select a contract by contract ID, and participate as a provider.
+
Match against a contract's target with a quality matcher, and participate as a consumer.
-To determine which contracts are in scope, contracts are found where either the source EndpointGroup selects a contract as either a provider or consumer,
+To determine which contracts are in scope, contracts are found where either the source EndpointGroup selects a contract as either a provider or consumer,
while the destination EndpointGroup matches against the same contract in the corresponding role. So if endpoint _x_ in EndpointGroup _X_ is communicating with endpoint _y_
in EndpointGroup _Y_, a contract _C_ is in scope if either _X_ selects _C_ as a provider and _Y_ selects _C_ as a consumer, or vice versa.
* The consumer EndpointGroup ID
* The name of the selector in the consumer EndpointGroup that was used to select the contract, called the _matching consumer selector._
+The result is then stored in the datastore under *Resolved Policy*.
+
===== Subject Selection
The second phase in policy resolution is to determine which subjects are in scope.
===== Requirements and Capabilities
-When acting as a _provider_, EndpointGroups expose _capabilities,_ which are labels representing specific pieces of functionality that can be exposed to other
+When acting as a _provider_, EndpointGroups expose _capabilities,_ which are labels representing specific pieces of functionality that can be exposed to other
EndpointGroups that may meet functional requirements of those EndpointGroups.
When acting as a _consumer_, EndpointGroups expose _requirements_, which are labels that represent that the EndpointGroup requires some specific piece of functionality.
As an example, we might create a capability called "user-database" which indicates that an EndpointGroup contains endpoints that implement a database of users.
-We might create a requirement also called "user-database" to indicate an EndpointGroup contains endpoints that will need to communicate with the endpoints that expose this service.
+We might create a requirement also called "user-database" to indicate an EndpointGroup contains endpoints that will need to communicate with the endpoints that expose this service.
Note that in this example the requirement and capability have the same name, but the user need not follow this convention.
An example of a condition might be "malware-detected," or "authentication-succeeded." Conditions are used to affect how that particular endpoint can communicate.
-To continue with our example, the "malware-detected" condition might cause an endpoint's connectivity to be cut off, while "authentication-succeeded" might open up communication with services
+To continue with our example, the "malware-detected" condition might cause an endpoint's connectivity to be cut off, while "authentication-succeeded" might open up communication with services
that require an endpoint to be first authenticated and then forward its authentication credentials.
===== Clauses
-Clauses perform the actual selection of subjects.
+Clauses perform the actual selection of subjects.
A clause has lists of matchers in two categories. In order for a clause to become active, all lists of matchers must match.
A matching clause will select all the subjects referenced by the clause.
Note that an empty list of matchers counts as a match.
* Consumer Endpoint Identification Constraint
+
-Label based criteria for matching against endpoints. In Lithium this can be used to label endpoints based on IpPrefix.
+Label based criteria for matching against endpoints. In Beryllium this can be used to label endpoints based on IpPrefix.
The second category is the provider matchers, which match against the provider EndpointGroup and endpoints. The provider matchers are:
* Consumer Endpoint Identification Constraint
+
-Label based criteria for matching against endpoints. In Lithium this can be used to label endpoints based on IpPrefix.
+Label based criteria for matching against endpoints. In Beryllium this can be used to label endpoints based on IpPrefix.
Clauses have a list of subjects that apply when all the matchers in the clause match. The output of the subject selection phase logically is a set of subjects that are in scope for any particular pair of endpoints.
===== Rule Application
-Now subjects have been selected that apply to the traffic between a particular set of endpoints, policy can be applied to allow endpoints to communicate.
-The applicable subjects from the previous step will each contain a set of rules.
+Now subjects have been selected that apply to the traffic between a particular set of endpoints, policy can be applied to allow endpoints to communicate.
+The applicable subjects from the previous step will each contain a set of rules.
-Rules consist of a set of _classifiers_ and a set of _actions_. Classifiers match against traffic between two endpoints.
+Rules consist of a set of _classifiers_ and a set of _actions_. Classifiers match against traffic between two endpoints.
An example of a classifier would be something that matches against all TCP traffic on port 80, or one that matches against HTTP traffic containing a particular cookie.
Actions are specific actions that need to be taken on the traffic before it reaches its destination.
Actions could include tagging or encapsulating the traffic in some way, redirecting the traffic, or applying a <<SFC,service function chain>>.
-Rules, subjects, and actions have an _order_ parameter, where a lower order value means that a particular item will be applied first.
-All rules from a particular subject will be applied before the rules of any other subject, and all actions from a particular rule will be applied before the actions from another rule.
+Rules, subjects, and actions have an _order_ parameter, where a lower order value means that a particular item will be applied first.
+All rules from a particular subject will be applied before the rules of any other subject, and all actions from a particular rule will be applied before the actions from another rule.
If more than item has the same order parameter, ties are broken with a lexicographic ordering of their names, with earlier names having logically lower order.
====== Matchers [[Matchers]]
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"
+* "all"
+
which means the matcher matches when all of its labels match
* "any"
+
which means the matcher matches when any of its labels match,
-* "none"
+* "none"
+
-which means the matcher matches when none of its labels match.
+which means the matcher matches when none of its labels match.
Note a _match all_ matcher can be made by matching against an empty set of labels with a match type of "all."
===== Inheritance [[Inheritance]]
-Some objects in the system include references to parents, from which they will inherit definitions.
-The graph of parent references must be loop free. When resolving names, the resolution system must detect loops and raise an exception.
+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,
+Generally, inheritance works by simply importing the objects in the parent into the child object. When there are objects with the same name in the child object,
then the child object will override the parent object according to rules which are specific to the type of object. We'll next explore the detailed rules for inheritance for each type of object
*EndpointGroups*
*Clauses*
Clauses cannot themselves have a parent clause, but it may inherit from a clause with the same name as the clause in a parent contract.
-The list of subject references in the parent clause will be added to the list of subject references in the child clause. This is just a union operation.
+The list of subject references in the parent clause will be added to the list of subject references in the child clause. This is just a union operation.
A subject reference that refers to a subject name in the parent contract might have that name overridden in the child contract.
-Each of the matchers in the clause are also inherited by the child clause.
+Each of the matchers in the clause are also inherited by the child clause.
Matchers in the child of the same name and type as a matcher from the parent will inherit from and override the parent matcher. See below under Matchers for more information.
*Matchers*
-Matchers include quality matchers, condition matchers, requirement matchers, and capability matchers.
-Matchers cannot themselves have parent matchers, but when there is a matcher of the same name and type in the parent object,
+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."
+Labels are also inherited from the parent object. If there is a label with the same name in the child object, this does not have any semantic effect except if the label has its inclusion-rule parameter set to "exclude."
In this case, then the label should be ignored for the purpose of matching. Otherwise, the label with the same name will completely override the label from the parent.
=== Using the GBP UX interface [[UX]]
If the REST API must be used, and the above resources are not sufficient:
-* feature:install odl-mdsal-apidocs or odl-dlux-yangui
-* browse to: http://<odl-controller>:8181/apidoc/explorer/index.html
+* feature:install odl-dlux-yangui
+* browse to: http://<odl-controller>:8181/index.html and select YangUI from the left menu.
-to explore the various *GBP* REST options
+to explore the various *GBP* REST options
-=== Using OpenStack with GBP [[Neutron]]
+=== Using OpenStack with GBP [[Neutron]]
include::odl-groupbasedpolicy-neutronmapper-user-guide.adoc[]
include::odl-groupbasedpolicy-ofoverlay-user-guide.adoc[]
-=== Using Service Function Chaining (SFC) with GBP [[SFC]]
+=== Using the GBP eBPF IO Visor Agent renderer [[IoVisor]]
+
+
+include::odl-groupbasedpolicy-iovisor-user-guide.adoc[]
+
+
+=== Using the GBP FaaS renderer [[FaaS]]
+
+
+include::odl-groupbasedpolicy-faas-user-guide.adoc[]
+
+
+=== Using Service Function Chaining (SFC) with GBP Neutron Mapper and OfOverlay [[SFC]]
include::odl-groupbasedpolicy-sfc-user-guide.adoc[]
=== Demo/Development environment[[demo]]
-The *GBP* project for Lithium has two demo/development environments.
+The *GBP* project for Beryllium has two demo/development environments.
* Docker based GBP and GBP+SFC integration Vagrant environment
* DevStack based GBP+Neutron integration Vagrant environment
--- /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
=== Overview
OpenDaylight's NetIDE project allows users to run SDN applications written for different
-SDN controllers eg, Floodlight, Ryu on top of OpenDaylight managed infrastructure.
+SDN controllers, e.g., Floodlight or Ryu, on top of OpenDaylight managed infrastructure. The NetIDE
+Network Engine integrates a client controller layer that executes the modules that
+compose a Network Application and interfaces with a server SDN controller layer that drives
+the underlying infrastructure. In addition, it provides a uniform interface to common tools
+that are intended to allow the inspection/debug of the control channel and the management of the
+network resources.
+
+The Network Engine provides a compatibility layer capable of translating calls of the network
+applications running on top of the client controllers, into calls for the server controller framework. The
+communication between the client and the server layers is achieved through the NetIDE
+intermediate protocol, which is an application-layer protocol on top of TCP that transmits the
+network control/management messages from the client to the server controller and vice-versa.
+Between client and server controller sits the Core Layer which also speaks the intermediate protocol.
=== NetIDE API
==== Architecture and Design
-The NetIDE engine follows the ONF's proposed Client/Server SDN Application architecture
+The NetIDE engine follows the ONF's proposed Client/Server SDN Application architecture.
+
+.NetIDE Network Engine Architecture
+image::netide/netidearch.jpg[width=500]
==== Core
-The NetIDE Core is a message based system that allows for the exchange of messages between
+The NetIDE Core is a message-based system that allows for the exchange of messages between
OpenDaylight and subscribed Client SDN Controllers
+==== Handling reply messages correctly
+
+When an application module sends a request to the network (e.g. flow statistics, features, etc.),
+the Network Engine must be able to correctly drive the corresponding reply to such a module. This is
+not a trivial task, as many modules may compose the network application running on top of the
+Network Engine, and there is no way for the Core to pair replies and requests. The transaction
+IDs (xid) in the OpenFlow header are unusable in this case, as it may happen that different modules
+use the same values.
+
+In the proposed approach, represented in the figure below, the task of pairing replies with requests is
+performed by the Shim Layer which replaces the original xid of the OpenFlow requests coming
+from the core with new unique xid values. The Shim also saves the original OpenFlow xid value
+and the module id it finds in the NetIDE header. As the network elements must use the same xid
+values in the replies, the Shim layer can easily pair a reply with the correct request as it is using
+unique xid values.
+
+The below figure shows how the Network Engine should handle the controller-to-switch OpenFlow messages.
+The diagram shows the case of a request message sent by an application module to a network
+element where the Backend inserts the module id of the module in the NetIDE header (X in the
+Figure). For other messages generated by the client controller platform (e.g. echo requests) or by
+the Backend, the module id of the Backend is used (Y in the Figure).
+
+.NetIDE Communication Flow
+image::netide/netide-flow.jpg[width=500]
+
+
==== Configuration
Below are the configuration items which can be edited, including their default values.
+* core-address: This is the ip address of the NetIDE Core, default is 127.0.0.1
+* core-port: The port of on which the NetIDE core is listening on
+* address: IP address where the controller listens for switch connections, default is 127.0.0.1
+* port: Port where controller listens for switch connections, default: 6644
+* transport-protocol: default is TCP
+* switch-idle-timeout: default is 15000ms
+
+
-== PCMM User Guide
+== PacketCable User Guide
=== Overview
=== PacketCable Components
-PacketCable is comprised of three OpenDaylight bundles:
+PacketCable is comprised of two OpenDaylight bundles:
[options="header"]
|======
|Bundle |Description
-|packetcable-policy-server | Plugin that provides PCMM model implementation based on CMTS structure and COPS protocol.
-|packetcable-policy-model | The Model provided provides a direct mapping to the underlying QoS Gates of CMTS.
-|packetcable-driver | The codec for transforming the model into the appropriate PCMM Gate message for flows and CMTS connections.
+|odl-packetcable-policy-server | Plugin that provides PCMM model implementation based on CMTS structure and COPS protocol.
+|odl-packetcable-policy-model | The Model provided provides a direct mapping to the underlying QoS Gates of CMTS.
|======
See the PacketCable
-https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-model/src/main/yang[YANG
+https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-policy-model/src/main/yang[YANG
Models].
=== Installing PacketCable
To install PacketCable, run the following `feature:install` command from the Karaf CLI
- feature:install odl-restconf odl-l2switch-switch odl-dlux-core odl-mdsal-apidocs odl-packetcable-policy-all
+ feature:install odl-packetcable-policy-server-all odl-restconf odl-mdsal-apidocs
=== Explore and exercise the PacketCable REST API
Replace localhost with the IP address or hostname where OpenDaylight is running if you are not running OpenDaylight locally on your machine.
-=== Adding a CMTS to OpenDaylight Inventory
-
-The RESTCONF URLs makes it possible to add a CMTS to OpenDaylight and have it connected.
-
-.Add a CMTS to OpenDaylight Inventory
-image::Screenshot1.png[width=500]
+NOTE: Prior to setting any PCMM gates, a CCAP must first be added.
=== Postman
-https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Configure
-the Chrome browser]
+https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Install
+the Chrome extension]
-https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-client[Download
+https://git.opendaylight.org/gerrit/gitweb?p=packetcable.git;a=tree;f=packetcable-policy-server/doc/restconf-samples[Download
and import sample packetcable collection]
.Postman Operations
-=== SFC OpenFlow Layer 2 Renderer User Guide
+=== SFC OpenFlow Renderer User Guide
==== Overview
-The Service Function Chaining (SFC) OpenFlow Layer 2 Renderer (SFCOFL2)
+The Service Function Chaining (SFC) OpenFlow Renderer (SFCOFL2)
implements Service Chaining on OpenFlow switches. It listens for the
creation of a Rendered Service Path (RSP), and once received it programs
Service Function Forwarders (SFF) that are hosted on OpenFlow capable
==== SFC OpenFlow Switch Flow pipeline
The SFC OpenFlow Renderer uses the following tables for its Flow pipeline:
-* Table 0, Transport Ingress
-* Table 1, Path Mapper
-* Table 2, Next Hop
+* Table 0, Classifier
+* Table 1, Transport Ingress
+* Table 2, Path Mapper
+* Table 3, Path Mapper ACL
+* Table 4, Next Hop
* Table 10, Transport Egress
The OpenFlow Table Pipeline is intended to be generic to work for
.SFC OpenFlow Renderer Typical Network Topology
image::sfc/sfcofl2_architecture_nwtopo.jpg["SFC OpenFlow Renderer Typical Network Topology",width=500]
+===== Classifier Table detailed
+
+It is possible for the SFF to also act as a classifier. This table maps subscriber
+traffic to RSPs, and is explained in detail in the classifier documentation.
+
+If the SFF is not a classifier, then this table will just have a simple Goto
+Table 1 flow.
===== Transport Ingress Table detailed
type to be received in a particular SFF, as established in the SFC
configuration.
-Here is an example on SFF1, assuming VLAN is used for the SFF-SF, and the RSP
-tunnel is MPLS:
+Here are two example on SFF1: one where the RSP ingress tunnel is MPLS assuming
+VLAN is used for the SFF-SF, and the other where the RSP ingress tunnel is NSH
+GRE (UDP port 4789):
.Table Transport Ingress
+[width=60%]
|===
|Priority |Match | Action
|256
|EtherType==0x8847 (MPLS unicast)
-|Goto Table 1
+|Goto Table 2
|256
|EtherType==0x8100 (VLAN)
-|Goto Table 1
+|Goto Table 2
+
+|256
+|EtherType==0x0800,udp,tp_dst==4789 (IP v4)
+|Goto Table 2
|5
|Match Any
The Path Mapper table has an entry per expected tunnel transport info
to be received in a particular SFF, as established in the SFC
configuration. The tunnel transport info is used to determine the
-RSP Path ID, and is stored in the OpenFlow Metadata.
+RSP Path ID, and is stored in the OpenFlow Metadata. This table is not
+used for NSH, since the RSP Path ID is stored in the NSH header.
-Since most SF nodes wont support tunneling, the IP header DSCP field is
+For SF nodes that do not support NSH tunneling, the IP header DSCP field is
used to store the RSP Path Id. The RSP Path Id is written to the DSCP
field in the Transport Egress table for those packets sent to an SF.
* The RSP Path 2 (symmetric downlink path) uses MPLS label 101 for ingress and 100 for egress
.Table Path Mapper
+[width=60%]
|===
|Priority |Match | Action
|256
|MPLS Label==100
-|RSP Path=1, Pop MPLS, Goto Table 2
+|RSP Path=1, Pop MPLS, Goto Table 4
|256
|MPLS Label==101
-|RSP Path=2, Pop MPLS, Goto Table 2
+|RSP Path=2, Pop MPLS, Goto Table 4
|256
|VLAN ID==1000, IP DSCP==1
-|RSP Path=1, Pop VLAN, Goto Table 2
+|RSP Path=1, Pop VLAN, Goto Table 4
|256
|VLAN ID==1000, IP DSCP==2
-|RSP Path=2, Pop VLAN, Goto Table 2
+|RSP Path=2, Pop VLAN, Goto Table 4
|5
|Match Any
-|Drop
+|Goto Table 3
|===
-===== Next Hop Table detailed
-The Next Hop table uses the RSP Path Id and source MAC address to
-determine the destination MAC address.
+===== Path Mapper ACL Table detailed
+This table is only populated when PacketIn packets are received from the switch
+for TcpProxy type SFs. These flows are created with an inactivity timer of 60
+seconds and will be automatically deleted upon expiration.
-Here is an example on SFF1, assuming SFF1 is connected to SFF2 and
-RSP Path 1 ingress packets come from external to SFC, for which
-we don’t have the source MAC address (MacSrc).
+===== Next Hop Table detailed
+The Next Hop table uses the RSP Path Id and appropriate packet fields to
+determine where to send the packet next. For NSH, only the NSP (Network
+Services Path, RSP ID) and NSI (Network Services Index, next hop) fields
+from the NSH header are needed to determine the VXLAN tunnel destination
+IP. For VLAN or MPLS, then the source MAC address is used to determine
+the destination MAC address.
+
+Here are two examples on SFF1, assuming SFF1 is connected to SFF2. RSP Paths 1
+and 2 are symmetric VLAN paths. RSP Paths 3 and 4 are symmetric NSH paths.
+RSP Path 1 ingress packets come from external to SFC, for which we don’t have
+the source MAC address (MacSrc).
.Table Next Hop
+[width=75%]
|===
|Priority |Match | Action
|RSP Path==1
|MacDst=SF1, Goto Table 10
+|256
+|nsp=3,nsi=255 (SFF Ingress RSP 3)
+|load:0xa000002->NXM_NX_TUN_IPV4_DST[], Goto Table 10
+
+|256
+|nsp=3,nsi=254 (SFF Ingress from SF, RSP 3)
+|load:0xa00000a->NXM_NX_TUN_IPV4_DST[], Goto Table 10
+
+|256
+|nsp=4,nsi=254 (SFF1 Ingress from SFF2)
+|load:0xa00000a->NXM_NX_TUN_IPV4_DST[], Goto Table 10
+
|5
|Match Any
|Drop
The Transport Egress table prepares egress tunnel information and
sends the packets out.
-Here is an example on SFF1, assuming VLAN is used for the SFF-SF, and the
-RSP tunnel is MPLS:
+Here are two examples on SFF1. RSP Paths 1 and 2 are symmetric MPLS paths that
+use VLAN for the SFF-SF. RSP Paths 3 and 4 are symmetric NSH paths. Since it is
+assumed that switches used for NSH will only have one VXLANport, the NSH
+packets are just sent back where they came from.
.Table Transport Egress
+[width=60%]
|===
|Priority |Match | Action
|RSP Path==2
|Push MPLS Label 100, Port=Ingress
+|256
+|nsp=3,nsi=255 (SFF Ingress RSP 3)
+|IN_PORT
+
+|256
+|nsp=3,nsi=254 (SFF Ingress from SF, RSP 3)
+|IN_PORT
+
+|256
+|nsp=4,nsi=254 (SFF1 Ingress from SFF2)
+|IN_PORT
+
|5
|Match Any
|Drop
To use the SFC OpenFlow Renderer Karaf, at least the following Karaf
features must be installed.
-* odl-openflowplugin-all
-* odl-sfc-core (includes odl-sfc-provider and odl-sfc-model)
+* odl-openflowplugin-nxm-extensions
+* odl-openflowplugin-flow-services
+* odl-sfc-provider
+* odl-sfc-model
* odl-sfcofl2
* odl-sfc-ui (optional)
==== SFCOFL2 Tutorial
===== Overview
-The following Network Topology diagram shows how to configure SFC to
-create a Service Chain.
+In this tutorial, 2 different encapsulations will be shown: MPLS and NSH. The
+following Network Topology diagram is a logical view of the SFFs and SFs involved
+in creating the Service Chains.
.SFC OpenFlow Renderer Typical Network Topology
image::sfc/sfcofl2_architecture_nwtopo.jpg["SFC OpenFlow Renderer Typical Network Topology",width=500]
===== Prerequisites
To use this example, SFF OpenFlow switches must be created and
-connected as illustrated above. Additionally, The SFs must be
-created and connected to the SFFs.
+connected as illustrated above. Additionally, the SFs must be
+created and connected.
===== Target Environment
The target environment is not important, but this use-case was created
-and only tested on Linux.
+and tested on Linux.
===== Instructions
The steps to use this tutorial are as follows. The referenced
configuration in the steps is listed in the following sections.
-There are numerous ways to send the configuration. The following
+There are numerous ways to send the configuration. In the following
configuration chapters, the appropriate `curl` command is shown for
each configuration to be sent, including the URL.
Once the configuration has been successfully created, query the
Rendered Service Paths with either the SFC UI or via RESTCONF.
-Notice that the RSP is symetrical, so the following 2 RSPs will
+Notice that the RSP is symmetrical, so the following 2 RSPs will
be created:
* sfc-path1
string with the appropriate JSON configuration. Also, change the
`localhost` desintation in the URL accordingly.
-====== Service Function configuration
+====== SFCOFL2 NSH Tutorial
+
+The following configuration sections show how to create the different elements
+using NSH encapsulation.
+
+*NSH Service Function configuration* +
+
The Service Function configuration can be sent with the following command:
curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
"service-function": [
{
"name": "sf1",
- "type": "service-function-type:http-header-enrichment",
+ "type": "http-header-enrichment",
+ "nsh-aware": true,
+ "ip-mgmt-address": "10.0.0.2",
+ "sf-data-plane-locator": [
+ {
+ "name": "sf1dpl",
+ "ip": "10.0.0.10",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe",
+ "service-function-forwarder": "sff1"
+ }
+ ]
+ },
+ {
+ "name": "sf2",
+ "type": "firewall",
+ "nsh-aware": true,
+ "ip-mgmt-address": "10.0.0.3",
+ "sf-data-plane-locator": [
+ {
+ "name": "sf2dpl",
+ "ip": "10.0.0.20",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe",
+ "service-function-forwarder": "sff2"
+ }
+ ]
+ }
+ ]
+ }
+}
+----
+
+*NSH Service Function Forwarder configuration* +
+
+The Service Function Forwarder configuration can be sent with the
+following command:
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-forwarder:service-function-forwarders/
+
+.SFF configuration JSON
+----
+{
+ "service-function-forwarders": {
+ "service-function-forwarder": [
+ {
+ "name": "sff1",
+ "service-node": "openflow:2",
+ "sff-data-plane-locator": [
+ {
+ "name": "sff1dpl",
+ "data-plane-locator":
+ {
+ "ip": "10.0.0.1",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "sf1",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name": "sf1dpl",
+ "sff-dpl-name": "sff1dpl"
+ }
+ }
+ ]
+ },
+ {
+ "name": "sff2",
+ "service-node": "openflow:3",
+ "sff-data-plane-locator": [
+ {
+ "name": "sff2dpl",
+ "data-plane-locator":
+ {
+ "ip": "10.0.0.2",
+ "port": 4789,
+ "transport": "service-locator:vxlan-gpe"
+ }
+ }
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "sf2",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name": "sf2dpl",
+ "sff-dpl-name": "sff2dpl"
+ }
+ }
+ ]
+ }
+ ]
+ }
+}
+----
+
+*NSH Service Function Chain configuration* +
+
+The Service Function Chain configuration can be sent with the following command:
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-chain:service-function-chains/
+
+.SFC configuration JSON
+----
+{
+ "service-function-chains": {
+ "service-function-chain": [
+ {
+ "name": "sfc-chain1",
+ "symmetric": true,
+ "sfc-service-function": [
+ {
+ "name": "hdr-enrich-abstract1",
+ "type": "http-header-enrichment"
+ },
+ {
+ "name": "firewall-abstract1",
+ "type": "firewall"
+ }
+ ]
+ }
+ ]
+ }
+}
+----
+
+*NSH Service Function Path configuration* +
+
+The Service Function Path configuration can be sent with the following command:
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function-path:service-function-paths/
+
+.SFP configuration JSON
+----
+{
+ "service-function-paths": {
+ "service-function-path": [
+ {
+ "name": "sfc-path1",
+ "service-chain-name": "sfc-chain1",
+ "transport-type": "service-locator:vxlan-gpe",
+ "symmetric": true
+ }
+ ]
+ }
+}
+----
+
+*NSH Rendered Service Path creation* +
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:create-rendered-path/
+
+.RSP creation JSON
+----
+{
+ "input": {
+ "name": "sfc-path1",
+ "parent-service-function-path": "sfc-path1",
+ "symmetric": true
+ }
+}
+----
+
+*NSH Rendered Service Path removal* +
+
+The following command can be used to remove a Rendered Service Path
+called `sfc-path1`:
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{"input": {"name": "sfc-path1" } }' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:delete-rendered-path/
+
+*NSH Rendered Service Path Query* +
+
+The following command can be used to query all of the created Rendered Service Paths:
+
+ curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
+
+
+====== SFCOFL2 MPLS Tutorial
+
+The following configuration sections show how to create the different elements
+using MPLS encapsulation.
+
+*MPLS Service Function configuration* +
+
+The Service Function configuration can be sent with the following command:
+
+ curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X PUT --user admin:admin http://localhost:8181/restconf/config/service-function:service-functions/
+
+.SF configuration JSON
+----
+{
+ "service-functions": {
+ "service-function": [
+ {
+ "name": "sf1",
+ "type": "http-header-enrichment",
"nsh-aware": false,
"ip-mgmt-address": "10.0.0.2",
"sf-data-plane-locator": [
},
{
"name": "sf2",
- "type": "service-function-type:firewall",
+ "type": "firewall",
"nsh-aware": false,
"ip-mgmt-address": "10.0.0.3",
"sf-data-plane-locator": [
}
----
-====== Service Function Forwarder configuration
+*MPLS Service Function Forwarder configuration* +
+
The Service Function Forwarder configuration can be sent with the
following command:
"mac": "33:33:33:33:33:33",
"port-id" : "2"
}
- }
- ],
- "service-function-dictionary": [
+ },
{
- "name": "sf1",
- "type": "service-function-type:http-header-enrichment",
- "sff-sf-data-plane-locator":
+ "name": "toSf1",
+ "data-plane-locator":
{
"mac": "22:22:22:22:22:22",
"vlan-id": 1000,
- "transport": "service-locator:mac"
+ "transport": "service-locator:mac",
},
"service-function-forwarder-ofs:ofs-port":
{
+ "mac": "33:33:33:33:33:33",
"port-id" : "3"
}
}
+ ],
+ "service-function-dictionary": [
+ {
+ "name": "sf1",
+ "sff-sf-data-plane-locator":
+ {
+ "sf-dpl-name": "sf1-sff1",
+ "sff-dpl-name": "toSf1"
+ }
+ }
]
},
{
"mac": "66:66:66:66:66:66",
"port-id" : "2"
}
+ },
+ {
+ "name": "toSf2",
+ "data-plane-locator":
+ {
+ "mac": "55:55:55:55:55:55",
+ "vlan-id": 2000,
+ "transport": "service-locator:mac"
+ },
+ "service-function-forwarder-ofs:ofs-port":
+ {
+ "port-id" : "3"
+ }
}
],
"service-function-dictionary": [
{
"name": "sf2",
- "type": "service-function-type:firewall",
"sff-sf-data-plane-locator":
{
- "mac": "55:55:55:55:55:55",
- "vlan-id": 2000,
- "transport": "service-locator:mac"
+ "sf-dpl-name": "sf2-sff2",
+ "sff-dpl-name": "toSf2"
+
},
"service-function-forwarder-ofs:ofs-port":
{
}
----
-====== Service Function Chain configuration
+*MPLS Service Function Chain configuration* +
+
The Service Function Chain configuration can be sent with the
following command:
"sfc-service-function": [
{
"name": "hdr-enrich-abstract1",
- "type": "service-function-type:http-header-enrichment"
+ "type": "http-header-enrichment"
},
{
"name": "firewall-abstract1",
- "type": "service-function-type:firewall"
+ "type": "firewall"
}
]
}
}
----
-====== Service Function Path configuration
+*MPLS Service Function Path configuration* +
+
The Service Function Path configuration can be sent with the following
command:
}
----
-====== Rendered Service Path creation
+*MPLS Rendered Service Path creation* +
curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '${JSON}' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:create-rendered-path/
}
----
-====== Rendered Service Path removal
+*MPLS Rendered Service Path removal* +
+
The following command can be used to remove a Rendered Service Path
called `sfc-path1`:
curl -i -H "Content-Type: application/json" -H "Cache-Control: no-cache" --data '{"input": {"name": "sfc-path1" } }' -X POST --user admin:admin http://localhost:8181/restconf/operations/rendered-service-path:delete-rendered-path/
-====== Rendered Service Path Query
+*MPLS Rendered Service Path Query* +
+
The following command can be used to query all of the created Rendered Service Paths:
curl -H "Content-Type: application/json" -H "Cache-Control: no-cache" -X GET --user admin:admin http://localhost:8181/restconf/operational/rendered-service-path:rendered-service-paths/
include::odl-sfc-classifier-user.adoc[SFC Classifier configuration User guide]
-include::odl-sfcofl2-user.adoc[SFC OpenFlow Layer2 Renderer user guide]
+include::odl-sfcofl2-user.adoc[SFC OpenFlow Renderer user guide]
include::odl-sfc-sf-scheduler-user.adoc[Service Function selection scheduler]
--- /dev/null
+== SNMP4SDN User Guide\r
+=== Overview\r
+We propose a southbound plugin that can control the off-the-shelf commodity Ethernet switches for the purpose of building SDN using Ethernet switches. For Ethernet switches, forwarding table, VLAN table, and ACL are where one can install flow configuration on, and this is done via SNMP and CLI in the proposed plugin. In addition, some settings required for Ethernet switches in SDN, e.g., disabling STP and flooding, are proposed.\r
+\r
+.SNMP4SDN as an OpenDaylight southbound plugin \r
+image::snmp4sdn_in_odl_architecture.jpg["SNMP4SDN as an OpenDaylight southbound plugin",width=400]\r
+\r
+=== Configuration\r
+Just follow the steps:\r
+\r
+==== Prepare the switch list database file\r
+A sample is https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[here], and we suggest to save it as '/etc/snmp4sdn_swdb.csv' so that SNMP4SDN Plugin can automatically load this file. Note that the first line is title and should not be removed.\r
+\r
+==== Prepare the vendor-specific configuration file\r
+A sample is https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file[here], and we suggest to save it as '/etc/snmp4sdn_VendorSpecificSwitchConfig.xml' so that SNMP4SDN Plugin can automatically load this file.\r
+\r
+=== Install SNMP4SDN Plugin\r
+If using SNMP4SDN Plugin provided in OpenDaylight release, just do the following from the Karaf CLI:\r
+\r
+----\r
+feature:install odl-snmp4sdn-all\r
+----\r
+\r
+=== Troubleshooting\r
+==== Installation Troubleshooting\r
+===== Feature installation failure\r
+When trying to install a feature, if the following failure occurs:\r
+----\r
+Error executing command: Could not start bundle ... \r
+Reason: Missing Constraint: Require-Capability: osgi.ee; filter="(&(osgi.ee=JavaSE)(version=1.7))"\r
+----\r
+A workaround: exit Karaf, and edit the file <karaf_directory>/etc/config.properties, remove the line '${services-${karaf.framework}}' and the ", \" in the line above.\r
+\r
+==== Runtime Troubleshooting\r
+===== Problem starting SNMP Trap Interface\r
+It is possible to get the following exception during controller startup. (The error would not be printed in Karaf console, one may see it in <karaf_directory>/data/log/karaf.log)\r
+----\r
+2014-01-31 15:00:44.688 CET [fileinstall-./plugins] WARN o.o.snmp4sdn.internal.SNMPListener - Problem starting SNMP Trap Interface: {}\r
+ java.net.BindException: Permission denied\r
+ at java.net.PlainDatagramSocketImpl.bind0(Native Method) ~[na:1.7.0_51]\r
+ at java.net.AbstractPlainDatagramSocketImpl.bind(AbstractPlainDatagramSocketImpl.java:95) ~[na:1.7.0_51]\r
+ at java.net.DatagramSocket.bind(DatagramSocket.java:376) ~[na:1.7.0_51]\r
+ at java.net.DatagramSocket.<init>(DatagramSocket.java:231) ~[na:1.7.0_51]\r
+ at java.net.DatagramSocket.<init>(DatagramSocket.java:284) ~[na:1.7.0_51]\r
+ at java.net.DatagramSocket.<init>(DatagramSocket.java:256) ~[na:1.7.0_51]\r
+ at org.snmpj.SNMPTrapReceiverInterface.<init>(SNMPTrapReceiverInterface.java:126) ~[org.snmpj-1.4.3.jar:na]\r
+ at org.snmpj.SNMPTrapReceiverInterface.<init>(SNMPTrapReceiverInterface.java:99) ~[org.snmpj-1.4.3.jar:na]\r
+ at org.opendaylight.snmp4sdn.internal.SNMPListener.<init>(SNMPListener.java:75) ~[bundlefile:na]\r
+ at org.opendaylight.snmp4sdn.core.internal.Controller.start(Controller.java:174) [bundlefile:na]\r
+...\r
+----\r
+This indicates that the controller is being run as a user which does not have sufficient OS privileges to bind the SNMPTRAP port (162/UDP)\r
+\r
+==== Switch list file missing\r
+The SNMP4SDN Plugin needs a switch list file, which is necessary for topology discovery and should be provided by the administrator (so please prepare one for the first time using SNMP4SDN Plugin, here is the https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[sample]). The default file path is /etc/snmp4sdn_swdb.csv. SNMP4SDN Plugin would automatically load this file and start topology discovery. If this file is not ready there, the following message like this will pop up:\r
+----\r
+2016-02-02 04:21:52,476 | INFO| Event Dispatcher | CmethUtil | 466 - org.opendaylight.snmp4sdn - 0.3.0.SNAPSHOT | CmethUtil.readDB() err: {}\r
+java.io.FileNotFoundException: /etc/snmp4sdn_swdb.csv (No such file or directory)\r
+ at java.io.FileInputStream.open0(Native Method)[:1.8.0_65]\r
+ at java.io.FileInputStream.open(FileInputStream.java:195)[:1.8.0_65]\r
+ at java.io.FileInputStream.<init>(FileInputStream.java:138)[:1.8.0_65]\r
+ at java.io.FileInputStream.<init>(FileInputStream.java:93)[:1.8.0_65]\r
+ at java.io.FileReader.<init>(FileReader.java:58)[:1.8.0_65]\r
+ at org.opendaylight.snmp4sdn.internal.util.CmethUtil.readDB(CmethUtil.java:66)\r
+ at org.opendaylight.snmp4sdn.internal.util.CmethUtil.<init>(CmethUtil.java:43)\r
+...\r
+----\r
+\r
+=== Configuration\r
+Just follow the steps:\r
+\r
+==== 1. Prepare the switch list database file\r
+A sample is https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[here], and we suggest to save it as '/etc/snmp4sdn_swdb.csv' so that SNMP4SDN Plugin can automatically load this file.\r
+\r
+NOTE:\r
+The first line is title and should not be removed.\r
+\r
+==== 2. Prepare the vendor-specific configuration file\r
+A sample is https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file[here], and we suggest to save it as '/etc/snmp4sdn_VendorSpecificSwitchConfig.xml' so that SNMP4SDN Plugin can automatically load this file.\r
+\r
+==== 3. Install SNMP4SDN Plugin\r
+If using SNMP4SDN Plugin provided in OpenDaylight release, just do the following:\r
+\r
+Launch Karaf in Linux console:\r
+----\r
+cd <Beryllium_controller_directory>/bin\r
+(for example, cd distribution-karaf-x.x.x-Beryllium/bin)\r
+----\r
+----\r
+./karaf\r
+----\r
+Then in Karaf console, execute:\r
+----\r
+feature:install odl-snmp4sdn-all\r
+----\r
+\r
+==== 4. Load switch list\r
+For initialization, we need to feed SNMP4SDN Plugin the switch list. Actually SNMP4SDN Plugin automatically try to load the switch list at /etc/snmp4sdn_swdb.csv if there is. If so, this step could be skipped.\r
+In Karaf console, execute:\r
+----\r
+snmp4sdn:ReadDB <switch_list_path>\r
+(For example, snmp4sdn:ReadDB /etc/snmp4sdn_swdb.csv)\r
+(in Windows OS, For example, snmp4sdn:ReadDB D://snmp4sdn_swdb.csv)\r
+----\r
+A sample is https://wiki.opendaylight.org/view/SNMP4SDN:switch_list_file[here], and we suggest to save it as '/etc/snmp4sdn_swdb.csv' so that SNMP4SDN Plugin can automatically load this file. \r
+\r
+NOTE:\r
+The first line is title and should not be removed.\r
+\r
+==== 5. Show switch list\r
+----\r
+snmp4sdn:PrintDB\r
+----\r
+\r
+=== Tutorial\r
+==== Topology Service\r
+===== Execute topology discovery\r
+\r
+The SNMP4SDN Plugin automatically executes topology discovery on startup. One may use the following commands to invoke topology discovery manually. Note that you may need to wait for seconds for itto complete. \r
+\r
+NOTE:\r
+Currently, one needs to manually execute 'snmp4sdn:TopoDiscover' first (just once), then later the automatic topology discovery can be successful. If switches change (switch added or removed), 'snmp4sdn:TopoDiscover' is also required. A future version will fix it to eliminate these requirements.\r
+----\r
+snmp4sdn:TopoDiscover\r
+----\r
+\r
+If one like to discover all inventory (i.e. switches and their ports) but not edges, just execute "TopoDiscoverSwitches":\r
+----\r
+snmp4sdn:TopoDiscoverSwitches\r
+----\r
+\r
+If one like to only discover all edges but not inventory, just execute "TopoDiscoverEdges":\r
+----\r
+snmp4sdn:TopoDiscoverEdges\r
+----\r
+\r
+You can also trigger topology discovery via the REST API by using +curl+ from the Linux console (or any other REST client):\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:rediscover\r
+----\r
+\r
+You can change the periodic topology discovery interval via a REST API:\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:set-discovery-interval -d "{"input":{"interval-second":'<interval_time>'}}" \r
+For example, set the interval as 15 seconds:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:set-discovery-interval -d "{"input":{"interval-second":'15'}}" \r
+----\r
+\r
+===== Show the topology\r
+\r
+SNMP4SDN Plugin supports to show topology via REST API:\r
+\r
+* Get topology\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-edge-list\r
+----\r
++\r
+* Get switch list\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-node-list\r
+----\r
++\r
+* Get switches' ports list\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/topology:get-node-connector-list\r
+----\r
++\r
+* The three commands above are just for user to get the latest topology discovery result, it does not trigger SNMP4SDN Plugin to do topology discovery.\r
+* To trigger SNMP4SDN Plugin to do topology discover, as described in aforementioned 'Execute topology discovery'.\r
+\r
+==== Flow configuration\r
+\r
+===== FDB configuration\r
+\r
+SNMP4SDN supports to add entry on FDB table via REST API:\r
+\r
+* Get FDB table\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:get-fdb-table -d "{input:{"node-id":<switch-mac-address-in-number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:get-fdb-table -d "{input:{"node-id":158969157063648}}" \r
+----\r
++\r
+* Get FDB table entry\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:get-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:get-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":158969157063648}}" \r
+----\r
++\r
+* Set FDB table entry\r
++\r
+(Notice invalid value: (1) non unicast mac (2) port not in the VLAN)\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:set-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>, "port":<port-in-number>, "type":'<type>'}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:set-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":187649984473770, "port":23, "type":'MGMT'}}" \r
+----\r
++\r
+* Delete FDB table entry\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/fdb:del-fdb-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "dest-mac-addr":<destination-mac-address-in-number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/fdb:del-fdb-entry -d "{input:{"node-id":158969157063648, "vlan-id":1, "dest-mac-addr":187649984473770}}" \r
+----\r
+\r
+===== VLAN configuration\r
+\r
+SNMP4SDN supports to add entry on VLAN table via REST API:\r
+\r
+* Get VLAN table\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:get-vlan-table -d "{input:{node-id:<switch-mac-address-in-number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:get-vlan-table -d "{input:{node-id:158969157063648}}" \r
+----\r
++\r
+* Add VLAN\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:add-vlan -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "vlan-name":'<vlan-name>'}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:add-vlan -d "{"input":{"node-id":158969157063648, "vlan-id":123, "vlan-name":'v123'}}" \r
+----\r
++\r
+* Delete VLAN\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:delete-vlan -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:delete-vlan -d "{"input":{"node-id":158969157063648, "vlan-id":123}}" \r
+----\r
++\r
+* Add VLAN and set ports\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:add-vlan-and-set-ports -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "vlan-name":'<vlan-name>', "tagged-port-list":'<tagged-ports-separated-by-comma>', "untagged-port-list":'<untagged-ports-separated-by-comma>'}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:add-vlan-and-set-ports -d "{"input":{"node-id":158969157063648, "vlan-id":123, "vlan-name":'v123', "tagged-port-list":'1,2,3', "untagged-port-list":'4,5,6'}}" \r
+----\r
++\r
+* Set VLAN ports\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/vlan:set-vlan-ports -d "{"input":{"node-id":<switch-mac-address-in-number>, "vlan-id":<vlan-id-in-number>, "tagged-port-list":'<tagged-ports-separated-by-comma>', "untagged-port-list":'<untagged-ports-separated-by-comma>'}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/vlan:set-vlan-ports -d "{"input":{"node-id":"158969157063648", "vlan-id":"123", "tagged-port-list":'4,5', "untagged-port-list":'2,3'}}"\r
+----\r
+\r
+===== ACL configuration\r
+\r
+SNMP4SDN supports to add flow on ACL table via REST API. However, it is so far only implemented for the D-Link DGS-3120 switch.\r
+\r
+ACL configuration via CLI is vendor-specific, and SNMP4SDN will support configuration with vendor-specific CLI in future release.\r
+\r
+To do ACL configuration using the REST APIs, use commands like the following:\r
+\r
+* Clear ACL table\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:clear-acl-table -d "{"input":{"nodeId":<switch-mac-address-in-number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:clear-acl-table -d "{"input":{"nodeId":158969157063648}}"\r
+----\r
++\r
+* Create ACL profile (IP layer)\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"acl-layer":'IP',"vlan-mask":<vlan_mask_in_number>,"src-ip-mask":'<src_ip_mask>',"dst-ip-mask":"<destination_ip_mask>"}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"acl-layer":'IP',"vlan-mask":1,"src-ip-mask":'255.255.0.0',"dst-ip-mask":'255.255.255.255'}}"\r
+----\r
++\r
+* Create ACL profile (MAC layer)\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"acl-layer":'ETHERNET',"vlan-mask":<vlan_mask_in_number>}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:create-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":2,"profile-name":'profile_2',"acl-layer":'ETHERNET',"vlan-mask":4095}}"\r
+----\r
++\r
+* Delete ACL profile\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":158969157063648,"profile-id":1}}"\r
+----\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-name":"<profile_name>"}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-profile -d "{input:{"nodeId":158969157063648,"profile-name":'profile_2'}}"\r
+----\r
++\r
+* Set ACL rule\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:set-acl-rule -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"rule-id":<rule_id_in_number>,"port-list":[<port_number>,<port_number>,...],"acl-layer":'<acl_layer>',"vlan-id":<vlan_id_in_number>,"src-ip":"<src_ip_address>","dst-ip":'<dst_ip_address>',"acl-action":'<acl_action>'}}" \r
+(<acl_layer>: IP or ETHERNET)\r
+(<acl_action>: PERMIT as permit, DENY as deny)\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:set-acl-rule -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"rule-id":1,"port-list":[1,2,3],"acl-layer":'IP',"vlan-id":2,"src-ip":'1.1.1.1',"dst-ip":'2.2.2.2',"acl-action":'PERMIT'}}" \r
+----\r
++\r
+* Delete ACL rule\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/acl:del-acl-rule -d "{input:{"nodeId":<switch-mac-address-in-number>,"profile-id":<profile_id_in_number>,"profile-name":'<profile_name>',"rule-id":<rule_id_in_number>}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/acl:del-acl-rule -d "{input:{"nodeId":158969157063648,"profile-id":1,"profile-name":'profile_1',"rule-id":1}}"\r
+----\r
+\r
+==== Special configuration\r
+\r
+SNMP4SDN supports setting the following special configurations via REST API:\r
+\r
+* Set STP port state\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:set-stp-port-state -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>, enable:<true_or_false>}}" \r
+(true: enable, false: disable)\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:set-stp-port-state -d "{input:{"node-id":158969157063648, "port":2, enable:false}}" \r
+----\r
++\r
+* Get STP port state\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-stp-port-state -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-stp-port-state -d "{input:{"node-id":158969157063648, "port":2}}" \r
+----\r
++\r
+* Get STP port root\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-stp-port-root -d "{input:{"node-id":<switch-mac-address-in-number>, "port":<port_number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-stp-port-root -d "{input:{"node-id":158969157063648, "port":2}}" \r
+----\r
++\r
+* Enable STP\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:enable-stp -d "{input:{"node-id":<switch-mac-address-in-number>}}" \r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:enable-stp -d "{input:{"node-id":158969157063648}}" \r
+----\r
++\r
+* Disable STP\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:disable-stp -d "{input:{"node-id":<switch-mac-address-in-number>}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:disable-stp -d "{input:{"node-id":158969157063648}}"\r
+----\r
++\r
+* Get ARP table\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-arp-table -d "{input:{"node-id":<switch-mac-address-in-number>}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-arp-table -d "{input:{"node-id":158969157063648}}"\r
+----\r
++\r
+* Set ARP entry\r
++\r
+(Notice to give IP address with subnet prefix)\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:set-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>', "mac-address":<mac_address_in_number>}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:set-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9', "mac-address":1}}"\r
+----\r
++\r
+* Get ARP entry\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:get-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>'}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:get-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9'}}"\r
+----\r
++\r
+* Delete ARP entry\r
++\r
+----\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://<controller_ip_address>:8181/restconf/operations/config:delete-arp-entry -d "{input:{"node-id":<switch-mac-address-in-number>, "ip-address":'<ip_address>'}}"\r
+\r
+For example:\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST http://localhost:8181/restconf/operations/config:delete-arp-entry -d "{input:{"node-id":158969157063648, "ip-address":'10.217.9.9'}}"\r
+----\r
+\r
+==== Using Postman to invoke REST API\r
+Besides using the curl tool to invoke REST API, like the examples aforementioned, one can also use GUI tool like Postman for better data display.\r
+\r
+* Install Postman: \r
+https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Install Postman in the Chrome browser]\r
++\r
+* In the chrome browser bar enter \r
++\r
+----\r
+chrome://apps/\r
+----\r
++\r
+* Click on Postman.\r
+\r
+===== Example: Get VLAN table using Postman\r
+\r
+As the screenshot shown below, one needs to fill in required fields.\r
+----\r
+URL:\r
+http://<controller_ip_address>:8181/restconf/operations/vlan:get-vlan-table\r
+\r
+Accept header:\r
+application/json\r
+\r
+Content-type:\r
+application/json\r
+\r
+Body:\r
+{input:{"node-id":<node_id>}}\r
+for example:\r
+{input:{"node-id":158969157063648}}\r
+----\r
+\r
+.Example: Get VLAN table using Postman\r
+image::snmp4sdn_getvlantable_postman.jpg["Example: Get VLAN table using Postman",width=500]\r
+\r
+=== Multi-vendor support\r
+\r
+So far the supported vendor-specific configurations:\r
+\r
+* Add VLAN and set ports\r
+* (More functions are TBD)\r
+\r
+The SNMP4SDN Plugin would examine whether the configuration is described in the vendor-specific configuration file. If yes, the configuration description would be adopted, otherwise just use the default configuration. For example, adding VLAN and setting the ports is supported via SNMP standard MIB. However we found some special cases, for example, certain Accton switch requires to add VLAN first and then allows to set the ports. So one may describe this in the vendor-specific configuration file.\r
+\r
+A vendor-specific configuration file sample is https://wiki.opendaylight.org/view/SNMP4SDN:snmp4sdn_VendorSpecificSwitchConfig_file[here], and we suggest to save it as '/etc/snmp4sdn_VendorSpecificSwitchConfig.xml' so that SNMP4SDN Plugin can automatically load it.\r
+\r
+=== Help\r
+* https://wiki.opendaylight.org/view/SNMP4SDN:Main[SNMP4SDN Wiki]\r
+* SNMP4SDN Mailing Lists: (https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-users[user], https://lists.opendaylight.org/mailman/listinfo/snmp4sdn-dev[developer])\r
+* Latest https://wiki.opendaylight.org/view/SNMP4SDN:User_Guide#Troubleshooting[troubleshooting] in Wiki\r
+\r
+++ /dev/null
-== TSDR H2 datastore User Guide
-This document describes how to use the embedded JPA datastore H2, which is the default datastore (recommended for non-production use case) introduced as part of OpenDaylight Time Series Data Respository(TSDR) project. This store captures the time series data. This document contains configuration, administration, management, using, and troubleshooting
-sections for the feature.
-
-=== Overview
-In the Lithium Release of Time Series Data Repository (TSDR), time series metrics corresponding to the OpenFlow statistics are captured. For users trying out things on their laptop or non-production environment, TSDR functionality can be enabled with default datastore H2 by installing the feature odl-tsdr-all.
-
-=== TSDR Architecture
-The following wiki pages capture the TSDR Model/Architecture
-
-a. https://wiki.opendaylight.org/view/TSDR_Data_Storage_Service_and_Persistence_with_HBase_Plugin
-b. https://wiki.opendaylight.org/view/TSDR_Data_Collection_Service
-
-Note in Lithium the DataCollection Service is implemented just for OpenFlow Statistics metrics.
-
-
-=== Configuring TSDR with default datastore H2
-The H2 based storage files get stored automatically in <karaf install folder>/tsdr/ directory. If you want to change the default storage location, the configuration file to change can be found in <karaf install folder>/etc directory. The filename is org.ops4j.datasource-metric.cfg. Change the last portion of the url=jdbc:h2:./tsdr/metric to point to different directory.
-
-=== Administering or Managing TSDR with default datastore H2
-Once the TSDR default datastore feature (odl-tsdr-all) is enabled, the TSDR captured OpenFlow statistics metrics can be accessed from Karaf Console by executing the command
-
- tsdr:list <metric-category> <starttimestamp> <endtimestamp>
-
-wherein
-
-* <metric-category> = any one of the following categories FlowGroupStats, FlowMeterStats, FlowStats, FlowTableStats, PortStats, QueueStats
-* <starttimestamp> = to filter the list of metrics starting this timestamp
-* <endtimestamp> = to filter the list of metrics ending this timestamp
-
-If either of <starttimestamp> or <endtimestamp> is not specified, this command displays the latest 1000 metrics captured.
-
-With TSDR functionality with default H2 datastore you get an additional command
-
- tsdr:purgeAll
-
-This will purge the entire collected tsdr metrics record.
+++ /dev/null
-== TSDR HBase Data Store User Guide
-This document describes how to use HBase to capture time series data
-using Time Series Data Repository (TSDR) feature in the OpenDaylight
-Lithium release. This document contains configuration, administration,
-management, usage, and troubleshooting sections for the feature.
-
-=== Overview
-The Time Series Data Repository (TSDR) project in OpenDaylight (ODL) creates a framework for collecting, storing, querying, and maintaining time series data in then OpenDaylight SDN controller. TSDR provides the framework for plugging in proper data collectors to collect various time series data and store into TSDR data stores. With a common data model and generic TSDR data persistence APIs, the user could choose various data stores to be plugged into TSDR Persistence framework. In Lithium, two types of data stores are supported: HBase NoSQL database and H2 relational database.
-
-With the capabilities of data collection, storage, query, aggregation, and purging provided by TSDR, network administrators could leverage various data driven appliations built on top of TSDR for security risk detection, performance analysis, operational configuration optimization, traffic engineering, and network analytics with automated intelligence.
-
-=== TSDR with HBase Data Store Architecture
-TSDR contains the following services and components:
-* Data Collection Service
-* Data Storage Service
-* TSDR Persistence Layer with data stores as plugins
-* TSDR Data Stores
-* Data Query Service
-* Data Aggregation Service
-* Data Purging Service
-
-Data Collection Service handles the collection of time series data into TSDR and hands it over to Data Storage Service. Data Storage Service stores the data into TSDR through TSDR Persistence Layer. TSDR Persistence Layer provides generic Service APIs allowing various data stores to be plugged in. Data Aggregation Service aggregates time series fine-grained raw data into course-grained roll-up data to control the size of the data. Data Purging Service periodically purges both fine-grained raw data and course-granined aggregated data according to user-defined schedules.
-
-
-In Lithium, we implemented Data Collection Service, Data Storage Service, TSDR Persistence Layer, TSDR HBase Data Store, and TSDR H2 Data Store. Among these services and components, time series data is communicated using a common TSDR data model, which is designed and implemented for the abstraction of time series data commonalities. With these functions, TSDR will be able to collect the data from the data sources and store them into one of the TSDR data stores: either HBase Data Store or H2 Data Store. We also provided a simple query command from Karaf console for the user to retrieve TSDR data from the data stores.
-
-
-A future release will contain Data Aggregation service, Data Purging Service, and a full-fledged Data Query Service with Norghbound APIs.
-
-=== Configuring TSDR with HBase Data Store
-After installing HBase Server on the same VM as the OpenDaylight Controller, if the user accepts the default configuration of the HBase Data Store, the user can directly proceed with the installation of HBase Data Store from Karaf console.
-
-Optionally, the user can configure TSDR HBase Data Store following HBase Data Store Configuration Procedure.
-
-* HBase Data Store Configuration Steps
-
-** Open the file etc/tsdr-persistence-hbase.peroperties under karaf distribution directory.
-** Edit the following parameters:
-*** HBase server name
-*** HBase server port
-*** HBase client connection pool size
-*** HBase client write buffer size
-
-After the configuration of HBase Data Store is complete, proceed with the installation of HBase Data Store from Karaf console.
-
-* HBase Data Store Installation Steps
-
-** Start Karaf Console
-** Run the following commands from Karaf Console:
-feature:install odl-tsdr-hbase
-
-
-=== Administering or Managing TSDR HBase Data Store
-
-* Using Karaf Command to retrieve data from HBase Data Store
-The user can retrieve the data from HBase data store using the following commands from Karaf console:
-
-tsdr:list
-
-tsdr:list <CategoryName> <StartTime> <EndTime>
-
-Typing tab will get the context prompt of the arguments when typeing the command in Karaf console.
-
-* Troubleshooting issues with log files
-** Karaf logs
-Similar to other OpenDaylight components and features, TSDR HBase Data Store writes logging information to Karaf logs. All the information messages, warnings, error messages, and debug messages are written to Karaf logs.
-
-** HBase logs
-For HBase system level logs, the user can check standard HBase server logs, which is under <HBase-installation-directory>/logs.
-
-=== Tutorials
-
-==== How to use TSDR to collect, store, and view OpenFlow Interface Statistics
-
-===== Overview
-This tutorial describes an example of using TSDR to collect, store, and view one type of time series data in OpenDaylight environment.
-
-
-===== Prerequisites
-You would need to have the following as prerequisits:
-* One or multiple OpenFlow enabled switches. Alternatively, you can use mininet to simulate such a switch.
-* Successfully installed OpenDaylight Controller.
-* Successfully installed HBase Data Store following TSDR HBase Data Store Installation Guide.
-* Connect the OpenFlow enabled switch(es) to OpenDaylight Controller.
-===== Target Environment
-HBase data store is only supported in Linux operation system.
-
-===== Instructions
-
-* Start OpenDaylight controller.
-
-* Connect OpenFlow enabled switch(es) to the controller.
-
-**If using mininet, run the following commands from mininet command line:
-
-*** mn --topo single,3 --controller 'remote,ip=172.17.252.210,port=6653' --switch ovsk,protocols=OpenFlow13
-
-**If using real switch(es), the OpenDaylight controller should be able to discover the network toplogy containing the switches.
-
-
-* Install tsdr hbase feature from Karaf:
-
-** feature:install odl-tsdr-hbase
-
-* run the following command from Karaf console:
-
-** tsdr:list InterfaceStats
-
-You should be able to see the interface statistics of the switch(es) from the HBase Data Store. If there are too many rows, you can use "tsdr:list InterfaceStats|more" to view it page by page.
-
-By tabbing after "tsdr:list", you will see all the supported data categories. For example, "tsdr:list FlowStats" will output the Flow statistics data collected from the switch(es).
-
-
--- /dev/null
+== TSDR User Guide
+This document describes how to use HSQLDB, HBase, and Cassandra data stores to
+capture time series data using Time Series Data Repository (TSDR) features
+in OpenDaylight. This document contains configuration, administration, management,
+usage, and troubleshooting sections for the features.
+
+=== Overview
+The Time Series Data Repository (TSDR) project in OpenDaylight (ODL) creates a
+framework for collecting, storing, querying, and maintaining time series data.
+TSDR provides the framework for plugging in proper data collectors to collect
+various time series data and store the data into
+TSDR Data Stores. With a common data model and generic TSDR data persistence
+APIs, the user can choose various data stores to be plugged into the TSDR
+persistence framework. Currently, three types of data stores are supported:
+HSQLDB relational database, HBase NoSQL database, and Cassandra NoSQL database.
+
+With the capabilities of data collection, storage, query, aggregation, and
+purging provided by TSDR, network administrators can leverage various data
+driven appliations built on top of TSDR for security risk detection,
+performance analysis, operational configuration optimization, traffic
+engineering, and network analytics with automated intelligence.
+
+
+=== TSDR Architecture
+TSDR has the following major components:
+
+* Data Collection Service
+* Data Storage Service
+* TSDR Persistence Layer with data stores as plugins
+* TSDR Data Stores
+* Data Query Service
+* Grafana integration for time series data visualization
+* Data Aggregation Service
+* Data Purging Service
+
+The Data Collection Service handles the collection of time series data into TSDR and
+hands it over to the Data Storage Service. The Data Storage Service stores the data
+into TSDR through the TSDR Persistence Layer. The TSDR Persistence Layer provides generic
+Service APIs allowing various data stores to be plugged in. The Data Aggregation
+Service aggregates time series fine-grained raw data into course-grained roll-up
+data to control the size of the data. The Data Purging Service periodically purges
+both fine-grained raw data and course-granined aggregated data according to
+user-defined schedules.
+
+We have implemented The Data Collection Service, Data Storage Service, TSDR
+Persistence Layer, TSDR HSQLDB Data Store, TSDR HBase Data Store, and TSDR Cassandra
+Datastore. Among these services and components, time series data is communicated
+using a common TSDR data model, which is designed and implemented for the
+abstraction of time series data commonalities. With these functions, TSDR is
+able to collect the data from the data sources and store them into one of
+the TSDR data stores: HSQLDB Data Store, HBase Data Store or Cassandra Data
+Store. Besides a simple query command from Karaf console to retrieve data from the
+TSDR data stores, we also provided a Data Query Service for the user to use REST API
+to query the data from the data stores. Moreover, the user can use Grafana, which is
+a time series visualization tool to view the data stored in TSDR in various charting
+formats.
+
+=== Configuring TSDR Data Stores
+==== To Configure HSQLDB Data Store
+
+The HSQLDB based storage files get stored automatically in <karaf install folder>/tsdr/
+directory. If you want to change the default storage location, the configuration
+file to change can be found in <karaf install folder>/etc directory. The filename
+is org.ops4j.datasource-metric.cfg. Change the last portion of the url=jdbc:hsqldb:./tsdr/metric
+to point to different directory.
+
+==== To Configure HBase Data Store
+
+After installing HBase Server on the same machine as OpenDaylight, if the user accepts the default configuration of the HBase Data Store, the user can directly proceed with the installation of HBase Data Store from Karaf console.
+
+Optionally, the user can configure TSDR HBase Data Store following HBase Data Store Configuration Procedure.
+
+* HBase Data Store Configuration Steps
+
+** Open the file etc/tsdr-persistence-hbase.peroperties under karaf distribution directory.
+** Edit the following parameters:
+*** HBase server name
+*** HBase server port
+*** HBase client connection pool size
+*** HBase client write buffer size
+
+After the configuration of HBase Data Store is complete, proceed with the installation of HBase Data Store from Karaf console.
+
+* HBase Data Store Installation Steps
+
+** Start Karaf Console
+** Run the following commands from Karaf Console:
+feature:install odl-tsdr-hbase
+
+==== To Configure Cassandra Data Store
+
+Currently, there's no configuration needed for Cassandra Data Store. The user can use Cassandra data store directly after installing the feature from Karaf console.
+
+Additionally separate commands have been implemented to install various data collectors.
+
+=== Administering or Managing TSDR Data Stores
+==== To Administer HSQLDB Data Store
+
+Once the TSDR default datastore feature (odl-tsdr-hsqldb-all) is enabled, the TSDR captured OpenFlow statistics metrics can be accessed from Karaf Console by executing the command
+
+ tsdr:list <metric-category> <starttimestamp> <endtimestamp>
+
+wherein
+
+* <metric-category> = any one of the following categories FlowGroupStats, FlowMeterStats, FlowStats, FlowTableStats, PortStats, QueueStats
+* <starttimestamp> = to filter the list of metrics starting this timestamp
+* <endtimestamp> = to filter the list of metrics ending this timestamp
+* <starttimestamp> and <endtimestamp> are optional.
+* Maximum 1000 records will be displayed.
+
+==== To Administer HBase Data Store
+
+* Using Karaf Command to retrieve data from HBase Data Store
+
+The user first need to install hbase data store from karaf console:
+
+feature:install odl-tsdr-hbase
+
+The user can retrieve the data from HBase data store using the following commands from Karaf console:
+
+ tsdr:list
+ tsdr:list <CategoryName> <StartTime> <EndTime>
+
+Typing tab will get the context prompt of the arguments when typeing the command in Karaf console.
+
+==== To Administer Cassandra Data Store
+
+The user first needs to install Cassandra data store from Karaf console:
+
+ feature:install odl-tsdr-cassandra
+
+Then the user can retrieve the data from Cassandra data store using the following commands from Karaf console:
+
+ tsdr:list
+ tsdr:list <CategoryName> <StartTime> <EndTime>
+
+Typing tab will get the context prompt of the arguments when typeing the command in Karaf console.
+
+=== Installing TSDR Data Collectors
+
+When the user uses HSQLDB data store and installed "odl-tsdr-hsqldb-all" feature from Karaf console, besides the HSQLDB data store, OpenFlow data collector is also installed with this command. However, if the user needs to use other collectors, such as NetFlow Collector, Syslog Collector, SNMP Collector, and Controller Metrics Collector, the user needs to install them with separate commands. If the user uses HBase or Cassandra data store, no collectors will be installed when the data store is installed. Instead, the user needs to install each collector separately using feature install command from Karaf console.
+
+The following is the list of supported TSDR data collectors with the associated feature install commands:
+
+* OpenFlow Data Collector
+
+ feature:install odl-tsdr-openflow-statistics-collector
+
+* SNMP Data Collector
+
+ feature:install odl-tsdr-snmp-data-collector
+
+* NetFlow Data Collector
+
+ feature:install odl-tsdr-netflow-statistics-collector
+
+* Syslog Data Collector
+
+ feature:install odl-tsdr-syslog-collector
+
+* Controller Metrics Collector
+
+ feature:install odl-tsdr-controller-metrics-collector
+
+In order to use controller metrics collector, the user needs to install Sigar library.
+
+The following is the instructions for installing Sigar library on Ubuntu:
+
+*** Install back end library by "sudo apt-get install libhyperic-sigar-java"
+*** Execute "export LD_LIBRARY_PATH=/usr/lib/jni/:/usr/lib:/usr/local/lib" to set the path of the JNI (you can add this to the ".bashrc" in your home directory)
+*** Download the file "sigar-1.6.4.jar". It might be also in your ".m2" directory under "~/.m2/resources/org/fusesource/sigar/1.6.4"
+*** Create the directory "org/fusesource/sigar/1.6.4" under the "system" directory in your controller home directory and place the "sigar-1.6.4.jar" there
+
+=== Configuring TSDR Data Collectors
+
+* SNMP Data Collector Device Credential Configuration
+
+After installing SNMP Data Collector, a configuration file under etc/ directory of ODL distribution is generated: etc/tsdr.snmp.cfg is created.
+
+The following is a sample tsdr.snmp.cfg file:
+
+credentials=[192.168.0.2,public],[192.168.0.3,public]
+
+The above credentials indicate that TSDR SNMP Collector is going to connect to two devices. The IPAddress and Read community string of these two devices are (192.168.0.2, public), and (192.168.0.3) respectively.
+
+The user can make changes to this configuration file any time during runtime. The configuration will be picked up by TSDR in the next cycle of data collection.
+
+==== Polling interval configuration for SNMP Collector and OpenFlow Stats Collector
+
+The default polling interval of SNMP Collector and OpenFlow Stats Collector is 30 seconds and 15 seconds respectively. The user can change the polling interval through restconf APIs at any time. The new polling interval will be picked up by TSDR in the next collection cycle.
+
+* Retrieve Polling Interval API for SNMP Collector
+** URL: http://localhost:8181/restconf/config/tsdr-snmp-data-collector:TSDRSnmpDataCollectorConfig
+** Verb: GET
+
+* Update Polling Interval API for SNMP Collector
+** URL: http://localhost:8181/restconf/operations/tsdr-snmp-data-collector:setPollingInterval
+** Verb: POST
+** Content Type: application/json
+** Input Payload:
+
+ {
+ "input": {
+ "interval": "15000"
+ }
+ }
+
+* Retrieve Polling Interval API for OpenFlowStats Collector
+** URL: http://localhost:8181/restconf/config/tsdr-openflow-statistics-collector:TSDROSCConfig
+** Verb: GET
+
+* Update Polling Interval API for OpenFlowStats Collector
+** URL: http://localhost:8181/restconf/operations/tsdr-openflow-statistics-collector:setPollingInterval
+** Verb: POST
+** Content Type: application/json
+** Input Payload:
+
+ {
+ "input": {
+ "interval": "15000"
+ }
+ }
+
+=== Querying TSDR from REST APIs
+
+TSDR provides two REST APIs for querying data stored in TSDR data stores.
+
+* Query of TSDR Metrics
+** URL: http://localhost:8181/tsdr/metrics/query
+** Verb: GET
+** Parameters:
+*** tsdrkey=[NID=][DC=][MN=][RK=]
+
+ The TSDRKey format indicates the NodeID(NID), DataCategory(DC), MetricName(MN), and RecordKey(RK) of the monitored objects.
+ For example, the following is a valid tsdrkey:
+ [NID=openflow:1][DC=FLOWSTATS][MN=PacketCount][RK=Node:openflow:1,Table:0,Flow:3]
+ The following is also a valid tsdrkey:
+ tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]
+ In the case when the sections in the tsdrkey is empty, the query will return all the records in the TSDR data store that matches the filled tsdrkey. In the above example, the query will return all the data in FLOWSTATS data category.
+ The query will return only the first 1000 records that match the query criteria.
+
+*** from=<time_in_seconds>
+*** until=<time_in_seconds>
+
+The following is an example curl command for querying metric data from TSDR data store:
+
+curl -G -v -H "Accept: application/json" -H "Content-Type: application/json" "http://localhost:8181/tsdr/metrics/query" --data-urlencode "tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]" --data-urlencode "from=0" --data-urlencode "until=240000000"|more
+
+* Query of TSDR Log type of data
+** URL:http://localhost:8181/tsdr/logs/query
+** Verb: GET
+** Parameters:
+*** tsdrkey=tsdrkey=[NID=][DC=][RK=]
+
+ The TSDRKey format indicates the NodeID(NID), DataCategory(DC), and RecordKey(RK) of the monitored objects.
+ For example, the following is a valid tsdrkey:
+ [NID=openflow:1][DC=NETFLOW][RK]
+ The query will return only the first 1000 records that match the query criteria.
+
+*** from=<time_in_seconds>
+*** until=<time_in_seconds>
+
+The following is an example curl command for querying log type of data from TSDR data store:
+
+curl -G -v -H "Accept: application/json" -H "Content-Type: application/json" "http://localhost:8181/tsdr/logs/query" --data-urlencode "tsdrkey=[NID=][DC=NETFLOW][RK=]" --data-urlencode "from=0" --data-urlencode "until=240000000"|more
+
+=== Grafana integration with TSDR
+
+TSDR provides northbound integration with Grafana time series data visualization tool. All the metric type of data stored in TSDR data store can be visualized using Grafana.
+
+For the detailed instruction about how to install and configure Grafana to work with TSDR, please refer to the following link:
+
+https://wiki.opendaylight.org/view/Grafana_Integration_with_TSDR_Step-by-Step
+
+=== Purging Service configuration
+
+After the data stores are installed from Karaf console, the purging service will be installed as well. A configuration file called tsdr.data.purge.cfg will be generated under etc/ directory of ODL distribution.
+
+The following is the sample default content of the tsdr.data.purge.cfg file:
+
+host=127.0.0.1
+data_purge_enabled=true
+data_purge_time=23:59:59
+data_purge_interval_in_minutes=1440
+retention_time_in_hours=168
+
+The host indicates the IPAddress of the data store. In the case when the data store is together with ODL controller, 127.0.0.1 should be the right value for the host IP. The other attributes are self-explained. The user can change those attributes at any time. The configuration change will be picked up right away by TSDR Purging service at runtime.
+
+=== How to use TSDR to collect, store, and view OpenFlow Interface Statistics
+
+==== Overview
+This tutorial describes an example of using TSDR to collect, store, and view one type of time series data in OpenDaylight environment.
+
+
+==== Prerequisites
+You would need to have the following as prerequisits:
+
+* One or multiple OpenFlow enabled switches. Alternatively, you can use mininet to simulate such a switch.
+* Successfully installed OpenDaylight Controller.
+* Successfully installed HBase Data Store following TSDR HBase Data Store Installation Guide.
+* Connect the OpenFlow enabled switch(es) to OpenDaylight Controller.
+
+==== Target Environment
+HBase data store is only supported in Linux operation system.
+
+==== Instructions
+
+* Start OpenDaylight.
+
+* Connect OpenFlow enabled switch(es) to the controller.
+
+** If using mininet, run the following commands from mininet command line:
+
+*** mn --topo single,3 --controller 'remote,ip=172.17.252.210,port=6653' --switch ovsk,protocols=OpenFlow13
+
+
+* Install tsdr hbase feature from Karaf:
+
+** feature:install odl-tsdr-hbase
+
+* Install OpenFlow Statistics Collector from Karaf:
+
+** feature:install odl-tsdr-openflow-statistics-collector
+
+* run the following command from Karaf console:
+
+** tsdr:list PORTSTATS
+
+You should be able to see the interface statistics of the switch(es) from the HBase Data Store. If there are too many rows, you can use "tsdr:list InterfaceStats|more" to view it page by page.
+
+By tabbing after "tsdr:list", you will see all the supported data categories. For example, "tsdr:list FlowStats" will output the Flow statistics data collected from the switch(es).
+
+=== Troubleshooting
+==== Karaf logs
+
+All TSDR features and components write logging information including information messages, warnings, errors and debug messages into karaf.log.
+
+==== HBase and Cassandra logs
+
+For HBase and Cassandra data stores, the database level logs are written into HBase log and Cassandra logs.
+
+** HBase log
+*** HBase log is under <HBase-installation-directory>/logs/.
+
+** Cassandra log
+*** Cassandra log is under {cassandra.logdir}/system.log. The default {cassandra.logdir} is /var/log/cassandra/.
+
+
--- /dev/null
+== UNI Manager Plug In Project
+
+=== Overview
+The version of the UNI Manager (UNIMgr) plug-in included in OpenDaylight
+Beryllium release is experimental, serving as a proof-of-concept (PoC) for using
+features of OpenDaylight to provision networked elements with attributes
+satisfying Metro Ethernet Forum (MEF) requirements for delivery of Carrier
+Ethernet service. This initial version of UNIMgr does not enable the full set
+of MEF-defined functionality for Carrier Ethernet service. UNI Manager adheres
+to a minimum set of functionality defined by MEF 7.2 and 10.2 specifications.
+
+UNIMgr receives a request from applications to create an Ethernet Private Line
+(EPL) private Ethernet connection between two endpoints on the network. The
+request must include the IP addresses of the endpoints and a class of service
+identifier.
+
+UNI Manager plug-in translates the request for EPL service into (a) configuring
+two instances of Open vSwitch (OVS), each instance running in one of the
+UNI endpoints, with two ports and a bridge between the ports, and (b) creating a
+GRE tunnel to provide a private connection between the endpoints. This initial
+version of UNIMgr uses only OVSDB on its southbound interface to send
+configuration commands.
+
+UNIMgr also accepts a bits per second datarate parameter, which is translated
+to an OVSDB command to limit the rate at which the OVS instances will forward
+data traffic.
+
+The YANG module used to create the UNIMgr plug-in models MEF-defined UNI and
+Ethernet Virtual Connection (EVC) attributes but does not include the full set
+of UNI and EVC attributes. And of the attributes modeled in the YANG module
+only a subset of them are implemented in the UNIMgr listener code translating
+the Operational data tree to OVSDB commands. The YANG module used to develop
+the PoC UNIMgr plug-in is cl-unimgr-mef.yang. A copy of this module is
+available in the odl-unimgr-api bundle of the UNIMgr project.
+
+Limitations of the PoC version of UNI Manager in OpenDaylight Beryllium include
+those listed below:
+* Uses only OVSDB southbound interface of OpenDaylight
+* Only uses UNI ID, IP Address, and speed UNI attributes
+* Only uses a subset of EVC per UNI attributes
+* Does not use MEF Class of Service or Bandwidth Profile attributes
+* Configures only Open vSwitch network elements
+
+Opportunities for evolution of the UNI Manager plug in include using complete
+MEF Service Layer and MEF Resource Layer YANG models and supporting other
+OpenDaylight southbound protocols like NetConf and OpenFlow.
+
+=== UNI Manager Components
+
+UNI Manager is comprised of the following OpenDaylight Karaf features:
+
+[width="60%",frame="topbot"]
+|======================
+|odl-unimgr-api | OpenDaylight :: UniMgr :: api
+|odl-unimgr | OpenDaylight :: UniMgr
+|odl-unimgr-console | OpenDaylight :: UniMgr :: CLI
+|odl-unimgr-rest | OpenDaylight :: UniMgr :: REST
+|odl-unimgr-ui | OpenDaylight :: UniMgr :: UI
+|======================
+
+=== Installing UNI Manager Plug-in
+
+After launching OpenDaylight install the feature for the UNI Manager plug-in.
+From the karaf command prompt execute the following command to install
+the UNI Manager plug-in:
+
+ $ feature:install odl-manager-ui
+
+=== Explore and exercise the UNI Manager REST API
+
+To see the UNI Manager APIs, browse to this URL:
+http://localhost:8181/apidoc/explorer/index.html
+
+Replace localhost with the IP address or hostname where OpenDaylight is
+running if you are not running OpenDaylight locally on your machine.
+
+See also the UNI Manager Developer's Guide for a full list and description of
+UNI Manager POSTMAN calls.
<properties>
<asciidoctor.version>0.1.4</asciidoctor.version>
<current.branch>master</current.branch>
- <nexusproxy>http://nexus.opendaylight.org/content</nexusproxy>
+ <nexusproxy>https://nexus.opendaylight.org/content</nexusproxy>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<sitedeploy>${nexusproxy}/sites/site/${project.groupId}/${current.branch}/${project.artifactId}</sitedeploy>
</properties>
--- /dev/null
+[tox]
+minversion = 1.6
+envlist = docs
+skipsdist = true
+
+[testenv:docs]
+deps = sphinx
+commands = sphinx-build -b html -d {envtmpdir}/doctrees ./docs/ {envtmpdir}/html
Code Review / docs.git / commitdiff
