.. _documentation-guide:
+###################
Documentation Guide
-===================
+###################
This guide provides details on how to contribute to the OpenDaylight
documentation. OpenDaylight currently uses a mix of AsciiDoc_ and
people.
reStructuredText-based Documentation
-------------------------------------
+====================================
When using reStructuredText, we try to follow the python documentation
style guide. See:
firefox docs/_build/html/index.html
Directory Structure
-^^^^^^^^^^^^^^^^^^^
+-------------------
The directory structure for the reStructuredText documentation is
rooted in the ``docs`` directory inside the ``docs`` ``git``
.. note:: When including rst files using ``toctree`` omit the .rst at
the end of the file name.
+Documentation Layout and Style
+------------------------------
+
+As mentioned previously we try to follow the python documentation style guide
+which defines a few types of sections::
+
+ # with overline, for parts
+ * with overline, for chapters
+ =, for sections
+ -, for subsections
+ ^, for subsubsections
+ ", for paragraphs
+
+We try to follow the following structure based on that recommendation::
+
+ docs/index.rst -> entry point
+ docs/____-guide/index.rst -> part
+ docs/____-guide/<chapter>.rst -> chapter
+
+In the ____-guide/index.rst we use the # with overline at the very top
+of the file to determine that it is a part and then within each chapter
+file we start the document with a section using * with overline to
+denote that it's the chapter heading and then everything in the rest of
+the chapter should use::
+
+ =, for sections
+ -, for subsections
+ ^, for subsubsections
+ ", for paragraphs
+
+
Troubleshooting
-^^^^^^^^^^^^^^^
+---------------
If you see an error like this::
They can be ignored. This is an artifact of our building documentation for the robot test framework customizations OpenDaylight has and is being tracked as `BUG-6159 <https://bugs.opendaylight.org/show_bug.cgi?id=6159>`_. More information can be found there.
AsciiDoc-based Documentation
-----------------------------
+============================
Information on the AsciiDoc tools and build system can be found here:
https://wiki.opendaylight.org/view/Documentation/Tools
Directory Structure
-^^^^^^^^^^^^^^^^^^^
+-------------------
The AsciiDoc documentation is all located in the ``manuals`` directory
of the ``docs`` ``git`` repository. An example of the directory
``src/main/resources`` directory containing images.
Migration from AsciiDoc to ReStructuredText
--------------------------------------------
+===========================================
Automatically
-^^^^^^^^^^^^^
+-------------
In theory, Pandoc_ can convert from DocBook to reStructuredText and we
produce DocBook as part of our build chain from AsciiDoctor. In
well.
By Hand
-^^^^^^^
+-------
Converting from AsciiDoc to reStructuredText is usually pretty
straightforward and involves looking up the basic syntax for what you
the HTML documentation rapid iteration is very easy.
Bold/Italics/Verbatim Formatting
-""""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is mostly minor syntax issues. In AsciiDoc you do inline
formatting something like this::
**bold** *italic* ``verbatim``
Images
-""""""
+^^^^^^
Image formats change from something like::
+***
API
-===
+***
We are in the process of creating automatically generated API documentation for
all of OpenDaylight. The following are links to the preliminary documentation
+****************************
Common OpenDaylight Features
-============================
+****************************
.. toctree::
:maxdepth: 1
+*******************************
OpenDaylight concepts and tools
-===============================
+*******************************
In this section we discuss some of the concepts and tools you encounter with
basic use of OpenDaylight. The guide walks you through the installation process
+**********************************
OpenDaylight Experimental Features
-==================================
+**********************************
.. contents::
:depth: 1
:local:
Messaging4Transport
--------------------
+===================
Adds AMQP bindings to the MD-SAL, which makes all MD-SAL APIs available via
that mechanism. AMQP bindings integration exposes the MD-SAL datatree, rpcs,
and notifications via AMQP, when installed.
Network Intent Composition (NIC)
---------------------------------
+================================
Offers an interface with an abstraction layer for you to communicate
“intentions,” i.e., what you expect from the network. The Intent model, which
is part of NIC's core architecture, describes your networking services
* Network MOdeling Renderer
UNI Manager Plug-in (Unimgr)
-----------------------------
+============================
Formed to initiate the development of data models and APIs that facilitate
OpenDaylight software applications’ and/or service orchestrators’ ability to
configure and provision connectivity services.
YANG-PUBSUB
------------
+===========
An experimental feature Plugin that allows subscriptions to be placed on
targeted subtrees of YANG datastores residing on remote devices. Changes in
YANG objects within the remote subtree can be pushed to OpenDaylight as
+#####################
Getting Started Guide
-=====================
+#####################
.. toctree::
:maxdepth: 1
project-specific-guides/index
common-features/index
security_considerations
-
.. _install_odl:
+***********************
Installing OpenDaylight
-=======================
+***********************
You complete the following steps to install your networking environment, with
specific instructions provided in the subsections below.
Install OpenDaylight
---------------------
+====================
Downloading and installing OpenDaylight
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------------
The default distribution can be found on the OpenDaylight software
download page: http://www.opendaylight.org/software/downloads
the `Install the Karaf features`_ section below.
Running the karaf distribution
-""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To run the Karaf distribution:
inflating: distribution-karaf-0.4.0-Beryllium/bin/stop.bat
$ cd distribution-karaf-0.4.0-Beryllium
$ ./bin/karaf
-
+
________ ________ .__ .__ .__ __
\_____ \ ______ ____ ____ \______ \ _____ ___.__.\| \| \|__\| ____ \| \|___/ \|_
/ \| \\____ \_/ __ \ / \ \| \| \\__ \< \| \|\| \| \| \|/ ___\\| \| \ __\
* Press ``ctrl-d`` or type ``system:shutdown`` or ``logout`` to shutdown OpenDaylight.
Install the Karaf features
---------------------------
+==========================
To install a feature, use the following command, where feature1 is the feature
name listed in the table below::
**self+all**. Not every combination has been tested.
Uninstalling features
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
To uninstall a feature, you must shut down OpenDaylight, delete the data
directory, and start OpenDaylight up again.
is not supported and can cause unexpected and undesirable behavior.
Listing available features
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
To find the complete list of Karaf features, run the following command::
feature:list
you can find in the :ref:`proj_rel_notes` section.
Karaf running on Windows 10
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
Windows 10 cannot be identify by Karaf (equinox).
Issue occurs during installation of karaf features e.g.::
Error executing command: Can't install feature odl-restconf/0.0.0:
Could not start bundle mvn:org.fusesource.leveldbjni/leveldbjni-all/1.8-odl in feature(s) odl-akka-leveldb-0.7: The bundle "org.fusesource.leveldbjni.leveldbjni-all_1.8.0 [300]" could not be resolved. Reason: No match found for native code: META-INF/native/windows32/leveldbjni.dll; processor=x86; osname=Win32, META-INF/native/windows64/leveldbjni.dll; processor=x86-64; osname=Win32, META-INF/native/osx/libleveldbjni.jnilib; processor=x86; osname=macosx, META-INF/native/osx/libleveldbjni.jnilib; processor=x86-64; osname=macosx, META-INF/native/linux32/libleveldbjni.so; processor=x86; osname=Linux, META-INF/native/linux64/libleveldbjni.so; processor=x86-64; osname=Linux, META-INF/native/sunos64/amd64/libleveldbjni.so; processor=x86-64; osname=SunOS, META-INF/native/sunos64/sparcv9/libleveldbjni.so; processor=sparcv9; osname=SunOS
-Workaround is to add
+Workaround is to add
org.osgi.framework.os.name = Win32
Beryllium features
-------------------
+==================
.. list-table:: Beryllium features
:widths: 10 25 10 5
Other Beryllium features
-------------------------
+========================
.. list-table:: Other Beryllium features
:widths: 10 25 10 5
Experimental Beryllium Features
--------------------------------
+===============================
The following functionality is labeled as experimental in OpenDaylight
Beryllium and should be used accordingly. In general, it is not supposed to be
used in production unless its limitations are well understood by those
- all
Install support for REST APIs
------------------------------
+=============================
Most components that offer REST APIs will automatically load the RESTCONF API
Support component, but if for whatever reason they seem to be missing, install
the “odl-restconf” feature to activate this support.
+************
Introduction
-============
+************
The OpenDaylight project is an open source platform for Software Defined
Networking (SDN) that uses open protocols to provide centralized, programmatic
through the installation process.
What’s different about OpenDaylight
------------------------------------
+===================================
Major distinctions of OpenDaylight’s SDN compared to traditional SDN options are
the following:
SDN programs.
What you’ll find in this guide
-------------------------------
+==============================
To set up your environment, you first install OpenDaylight followed by the
Apache Karaf features that offer the functionality you require. The OpenDaylight
+***************************
OpenDaylight Karaf Features
-===========================
+***************************
This section provides brief descriptions of the most commonly used Karaf
features developed by OpenDaylight project teams. They are presented in
:local:
AAA
----
+===
Standards-compliant Authentication, Authorization and Accounting Services.
RESTCONF is the most common consumer of AAA, which installs the AAA features
automatically. AAA provides:
The Beryllium release of AAA includes experimental support for having the database of users and credentials stored in the cluster-aware MD-SAL datastore.
ALTO
-----
+====
Implements the Application-Layer Traffic Optimization (ALTO) base IETF protocol
to provide network information to applications. It defines abstractions and
services to enable simplified network views and network services to guide
amongst endpoints.
Border Gateway Protocol (including Link-state Distribution (BGP)
-----------------------------------------------------------------
+================================================================
Is a southbound plugin that provides support for Border Gateway Protocol
(including Link-state Distribution) as a source of L3 topology information.
Border Gateway Monitoring Protocol (BMP)
-----------------------------------------
+========================================
Is a southbound plugin that provides support for BGP Monitoring Protocol as a
monitoring station.
Control and Provisioning of Wireless Access Points (CAPWAP)
------------------------------------------------------------
+===========================================================
Enables OpenDaylight to manage CAPWAP-compliant wireless termination point (WTP)
network devices. Intelligent applications, e.g., radio planning, can be
developed by tapping into the operational states made available via REST APIs of
WTP network devices.
Controller Shield
------------------
+=================
Creates a repository called the Unified-Security Plugin (USecPlugin) to provide
controller security information to northbound applications, such as the
following:
Information collected at the plugin may also be used to configure firewalls and create IP blacklists for the network.
Device Identification and Driver Management (DIDM)
---------------------------------------------------
+==================================================
Provides device-specific functionality, which means that code enabling a feature
understands the capability and limitations of the device it runs on. For
example, configuring VLANs and adjusting FlowMods are features, and there may be
functionality is implemented as Device Drivers.
DLUX
-----
+====
Web based OpenDaylight user interface that includes:
* An MD-SAL flow viewer
* A tool box and YANG model that execute queries and visualize the YANG tree
Fabric as a Service (FaaS)
---------------------------
+==========================
Creates a common abstraction layer on top of a physical network so northbound
APIs or services can be more easily mapped onto the physical network as a
concrete device configuration.
Group Based Policy (GBP)
-------------------------
+========================
Defines an application-centric policy model for OpenDaylight that separates
information about application connectivity requirements from information about
the underlying details of the network infrastructure. Provides support for:
* OFOverlay support for NAT, table offsets
Internet of Things Data Management (IoTDM)
-------------------------------------------
+==========================================
Developing a data-centric middleware to act as a oneM2M_-compliant IoT Data
Broker (IoTDB) and enable authorized applications to retrieve IoT data uploaded
by any device.
Link Aggregation Control Protocol (LACP)
-----------------------------------------
+========================================
LACP can auto-discover and aggregate multiple links between an
OpenDaylight-controlled network and LACP-enabled endpoints or switches.
Location Identifier Separation Protocol (LISP) Flow Mapping Service (LISP)
---------------------------------------------------------------------------
+==========================================================================
LISP (RFC6830) enables separation of Endpoint Identity (EID) from Routing
Location (RLOC) by defining an overlay in the EID space, which is mapped to the
underlying network in the RLOC space.
OpenDaylight via the LISP protocol.
NEMO
-----
+====
Is a Domain Specific Language (DSL) for the abstraction of network models and
identification of operation patterns. NEMO enables network users/applications to
describe their demands for network resources, services, and logical operations
in an intuitive way that can be explained and executed by a language engine.
NETCONF
--------
+=======
Offers four features:
* odl-netconf-mdsal: NETCONF Northbound for MD-SAL and applications
* odl-restconf: RESTCONF Northbound for MD-SAL and applications
NetIDE
-------
+======
Enables portability and cooperation inside a single network by using a
client/server multi-controller architecture. It provides an interoperability
layer allowing SDN Applications written for other SDN Controllers to run on
engine.
OVSDB-based Network Virtualization Services
--------------------------------------------
+===========================================
Several services and plugins in OpenDaylight work together to provide simplified
integration with the OpenStack Neutron framework. These services enable
OpenStack to offload network processing to OpenDaylight while enabling
* Network Virtualization User interface for DLUX
OpenFlow Configuration Protocol (OF-CONFIG)
--------------------------------------------
+===========================================
Provides a process for an Operation Context containing an OpenFlow Switch that uses OF-CONFIG to communicate with an OpenFlow Configuration Point, enabling remote configuration of OpenFlow datapaths.
OpenFlow plugin
----------------
+===============
Supports connecting to OpenFlow-enabled network devices via the OpenFlow
specification. It currently supports OpenFlow versions 1.0 and 1.3.2.
OF-CONFIG specifications.
Path Computation Element Protocol (PCEP)
-----------------------------------------
+========================================
Is a southbound plugin that provides support for performing Create, Read,
Update, and Delete (CRUD) operations on Multiprotocol Label Switching (MPLS)
tunnels in the underlying network.
Secure Network Bootstrapping Interface (SNBi)
----------------------------------------------
+=============================================
Leverages manufacturer-installed IEEE 802.1AR certificates to secure initial
communications for a zero-touch approach to bootstrapping using Docker. SNBi
devices and controllers automatically do the following:
federation processes.
Service Function Chaining (SFC)
--------------------------------
+===============================
Provides the ability to define an ordered list of network services (e.g.
firewalls, load balancers) that are then "stitched" together in the network to
create a service chain. SFC provides the chaining logic and APIs necessary for
* Integration with OpenDaylight OVSDB NetVirt project
SNMP Plugin
------------
+===========
The SNMP southbound plugin allows applications acting as an SNMP Manager to
interact with devices that support an SNMP agent. The SNMP plugin implements a
general SNMP implementation, which differs from the SNMP4SDN as that project
device.
SNMP4SDN
---------
+========
Provides a southbound SNMP plugin to optimize delivery of SDN controller
benefits to traditional/legacy ethernet switches through the SNMP interface. It
offers support for flow configuration on ACLs and enables flow configuration
via REST API and multi-vendor support.
Source-Group Tag Exchange Protocol (SXP)
-----------------------------------------
+========================================
Enables creation of a tag that allows you to filter traffic instead of using
protocol-specific information like addresses and ports. Via SXP an external
entity creates the tags, assigns them to traffic appropriately, and publishes
services and networking devices.
Topology Processing Framework
------------------------------
+=============================
Provides a framework for simplified aggregation and topology data query to
enable a unified topology view, including multi-protocol, Underlay, and
Overlay resources.
Time Series Data Repository (TSDR)
-----------------------------------
+==================================
Creates a framework for collecting, storing, querying, and maintaining time
series data in OpenDaylight. You can leverage various data-driven applications
built on top of TSDR when you install a datastore and at least one collector.
See these TSDR_Directions_ for more information.
Unified Secure Channel (USC)
-----------------------------
+============================
Provides a central server to coordinate encrypted communications between
endpoints. Its client-side agent informs the controller about its encryption
capabilities and can be instructed to encrypt select flows based on business
device types.
VPN Service
------------
+===========
Implements the infrastructure services required to support L3 VPN service. It
initially leverages open source routing applications as pluggable components.
L3 services include:
* Network Overlay solution necessary for a Datacenter/Cloud environment
Virtual Tenant Network (VTN)
-----------------------------
+============================
Provides multi-tenant virtual network on an SDN controller, allowing you to
define the network with a look and feel of a conventional L2/L3 network. Once
the network is designed on VTN, it automatically maps into the underlying
+**************
Other features
-==============
+**************
OpFlex
-------
+======
Provides the OpenDaylight OpFlex Agent , which is a policy agent that works
with Open vSwitch (OVS), to enforce network policy, e.g., from Group-Based
Policy, for locally-attached virtual machines or containers.
Network embedded Experience (NeXt)
-----------------------------------
+==================================
Provides a network-centric topology UI that offers visualizations of the
following:
+********
Overview
-========
+********
OpenDaylight performs the following functions:
+************************************
Project-Specific Installation Guides
-====================================
+************************************
.. toctree::
:maxdepth: 1
tsdr
vtn
yangide
-
+*************
Release Notes
-=============
+*************
Target Environment
-------------------
+==================
For Execution
-^^^^^^^^^^^^^
+-------------
The OpenDaylight Karaf container, OSGi bundles, and Java class files
are portable and should run on any Java 7- or Java 8-compliant JVM to
* VTN has components which require Linux
For Development
-^^^^^^^^^^^^^^^
+---------------
OpenDaylight is written primarily in Java project and primarily uses
Maven as a build tool Consequently the two main requirements to develop
the project-specific release notes for details.
Known Issues and Limitations
-----------------------------
+============================
Other than as noted in project-specific release notes, we know of the
following limitations:
.. _proj_rel_notes:
Project-specific Release Notes
-------------------------------
+==============================
For the release notes of individual projects, please see the following pages on the OpenDaylight Wiki.
* YANG_Tools_
Projects without Release Notes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
The following projects participated in Boron, but intentionally do not have release notes.
+***********************
Security Considerations
-=======================
+***********************
This document discusses the various security issues that might affect
OpenDaylight. The document also lists specific recommendations to
which is tasked with identifying and resolving security threats.
Overview of OpenDaylight Security
----------------------------------
+=================================
There are many different kinds of security vulnerabilities that could affect
an OpenDaylight deployment, but this guide focuses on those where (a) the
a well-defined process for reporting and dealing with them.
OpenDaylight Security Resources
--------------------------------
+===============================
* If you have any security issues, you can send a mail to
*security@lists.opendaylight.org*.
refer to https://wiki.opendaylight.org/view/Security:Main
Deployment Recommendations
---------------------------
+==========================
We recommend that you follow the deployment guidelines in setting up
OpenDaylight to minimize security threats.
traffic from the data network to the management network.
Securing OSGi bundles
----------------------
+=====================
OSGi is a Java-specific framework that improves the way that Java classes
interact within a single JVM. It provides an enhanced version of the
For more information, refer to http://www.osgi.org/Main/HomePage.
Securing the Karaf container
-----------------------------
+============================
Apache Karaf is a OSGi-based runtime platform which provides a lightweight
container for OpenDaylight and applications. Apache Karaf uses
http://karaf.apache.org/manual/latest/developers-guide/security-framework.html.
Disabling the remote shutdown port
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------
You can lock down your deployment post installation. Set
``karaf.shutdown.port=-1`` in ``etc/custom.properties`` or ``etc/config.properties`` to
disable the remote shutdown port.
Securing Southbound Plugins
----------------------------
+===========================
Many individual southbound plugins provide mechanisms to secure their
communication with network devices. For example, the OpenFlow plugin supports
mechanisms to connect to devices using the relevant plugins.
Securing OpenDaylight using AAA
--------------------------------
+===============================
AAA stands for Authentication, Authorization, and Accounting. All three of
can help improve the security posture of and OpenDaylight deployment. In this
password *admin*. This should be changed before deploying OpenDaylight.
Security Considerations for Clustering
---------------------------------------
+======================================
While OpenDaylight clustering provides many benefits including high
availability, scale-out performance, and data durability, it also opens a new
+**************************
Who should use this guide?
-==========================
+**************************
OpenDaylight is for users considering open options in network programming. This
guide provides information for the following types of users:
+#################################
OpenDaylight with Openstack Guide
-=================================
+#################################
+********
Overview
---------
+********
OpenStack_ is a popular open source Infrastructure
as a service project, covering compute, storage and network management.
flows for the OpenStack compute nodes via the OVSDB south-bound plug-in. This
page describes how to set that up, and how to tell when everything is working.
+********************
Installing OpenStack
---------------------
+********************
Installing OpenStack is out of scope for this document, but to get started, it
is useful to have a minimal multi-node OpenStack deployment.
public network, and verify that you can connect to them, and that they can
see each other.
-
+***********************
Installing OpenDaylight
------------------------
+***********************
.. toctree::
:maxdepth: 1
Code Review / docs.git / commitdiff