--- /dev/null
+== API design principles and patterns contributed by southbound plugins\r
+\r
+This section is intended to define common design patterns supporting extensions contributed by southbound plugins, which could be used in the SAL or or used in modelling any abstract extensible APIs.\r
+\r
+NOTE: Wire protocol specific information (serialization, serialization constants , TLV identifiers, bit masks, field ordering) should not be part of the SAL. Also, APIs (interfaces, classes) should support extensibility using subclassing or other extension patterns. This allows for abstract APIs and also for concrete APIs to coexist in the SAL and to use common infrastructure.\r
+\r
+=== Extensible enumeration pattern\r
+\r
+This pattern is suitable for modelling or defining APIs for the enumeration of immutable data or types, which for example could represent ether type, protocol type, and others. The workflow for API definition is simple:\r
+\r
+. Define a simple interface with the needed functionality.\r
+\r
+. Declare an enum implementing the interface where the enum constants represent the known values.\r
+\r
+. (optional) Include a factory method mapping from names to objects implementing the interface.\r
+\r
+For more information, see the following links:\r
+\r
+** http://jtechies.blogspot.com/2012/07/item-34-emulate-extensible-enums-with.html\r
+\r
+** http://blogs.oracle.com/darcy/entry/enums_and_mixins\r
+\r
+=== Type-value pairs pattern\r
+\r
+This pattern is suitable for modelling or defining APIs for extensible set of fields, where the values could be of different types. The requirements for type-value pairs are: Extensible and Type safety.\r
+\r
+==== Common antipatterns\r
+\r
+This pattern is to replace the following constructs:\r
+\r
+\r
+* Simple untyped approach to properties (pros: extensible, cons: does not provide semantics and type safety):\r
+\r
+[literal]\r
+// Ommited for clarity...\r
+HashMap<String,Object> properties;\r
+\r
+\r
+* More refined approach using the enumeration to define a set of supported field types (pros: provides semantics, cons: not extensible).\r
+\r
+[literal]\r
+enum Type {\r
+ TYPE1(String.class),\r
+ TYPE2(Boolean.class),\r
+ private Class<?> valueType; // This line is optional.\r
+ // ommited for clarity... \r
+}\r
+class Field {\r
+ Type type;\r
+ Object value;\r
+ // ommited for clarity...\r
+}\r
+\r
+\r
+=== Actual pattern\r
+\r
+We can model this by using the abstract class and the generics to define value type and set of subclasses representing various types of fields. The instances of this class represents actual type-value pair, where class represents type and value is represented by object in the instance.\r
+\r
+[literal]\r
+abstract class Field<V> {\r
+ private V value;\r
+ public Field(V value) {\r
+ this.value = value;\r
+ }\r
+ ...\r
+}\r
+ class Type1Field extends Field<String> {\r
+ public Type1Field(String value){super(value);}\r
+}\r
+ class Type2Field extends Field<Boolean> {\r
+ public Type2Field(Boolean value){super(value);}\r
+}\r
+\r
+The abstract class does not have to only define fields or values, but could also define additional methods (concrete or abstract) which could provide additional semantic about the field type. This example shows only one value field, but it is possible to have multiple fields. It is possible to model common part of API also as an interface and leave all the implementation to the super types. Map, which should store one instance of the field is: Map<Class<? extends Field<?>>,Field<?>>. It is possible to provide simpler facade on top of this map.\r
+\r
+=== Extension interface pattern\r
+\r
+The following Java design allows an object to be extended without changing its interface to clients. The object can implement additional extension interfaces. Clients can ask the object for extension interfaces that it implements.\r
+\r
+\r
+In the interface present in the SAL models general approach or abstraction, the client code (applications) could ask for extension interface (which could be used to model protocol specific functionality, interfaces, data) by querying for the extension. Extension is identified by Java interface (the client code using extension must be compiled against this interface).\r
+\r
+\r
+This pattern could be also used as an replacement for the field pattern. We have defined a set of fields provided by extension as separate class or interface, the values could be queried by using the extension class.\r
+The strong point of this pattern is that the client code needs to be aware of the extension and its contract (be compiled against the base interface and also extension) in order to use the extension. The code which was not compiled against extension is not affected by introducing new extensions.\r
+\r
+*Synopsis: Original pattern*\r
+\r
+[literal]\r
+public interface A {\r
+ // Ommited for clarity...\r
+ <T> T getExtension(Class<T> extensionType)\r
+}\r
+\r
+*Synopsis: Updated pattern*\r
+[literal]\r
+public interface Extensible<P> {\r
+ // Ommited for clarity...\r
+ <T extends Extension<P>> T getExtension(Class<T> extensionType)\r
+}\r
+public interface Extension<T> {\r
+}\r
+\r
+Where:\r
+\r
+* Extensible is interface which is to be implemented by classes which provides extension support\r
+\r
+* P - generic argument, usually interface / class which implements\r
+\r
+* Extension is marker interface (for type-safety reasons) which marks interfaces / classes which are extensions\r
+\r
+* T - generic argument, pointing to the class / interface to which this extension is associated.\r
+\r
+=== Usage example\r
+\r
+[literal]\r
+ublic class Node extends Extensible<Node> {\r
+ // contents ommited\r
+ // the instatiated version of extension interface isExtension method is\r
+ @Override\r
+ <T extends Extension<Node> T getExtension(Class<T> extensionType) {\r
+ // contents ommited\r
+ }\r
+}\r
+public class OpenflowNode extends Extension<Node> {\r
+ // contents ommited\r
+}\r
+Node node = provider.getNode(); // sample call returning node\r
+OpenflowNode ofNode = node.getExtension(OpenflowNode.class);\r
+if(ofNode != null) {\r
+ // do openflow specific stuff\r
+}\r
--- /dev/null
+== OpenDaylight controller library descriptions\r
+\r
+Shared functions and methods are compiled and bundled into libraries. This page describes client libraries.\r
+\r
+=== C client library\r
+\r
+The C module generates the source code for the ANSI-C-compatible data structures and (de)serialization functions that can be used in conjunction with http://xmlsoft.org/[libxml2] to (de)serialize the REST resources as they are represented as XML data.\r
+\r
+\r
+The generated C source code depends on the http://xmlsoft.org/html/libxml-xmlreader.html[XML Reader API] and the http://xmlsoft.org/html/libxml-xmlwriter.html[XML Writer API] as well as the <time.h>, <string.h>, and <stdlib.h> C standard libraries.\r
+\r
+\r
+=== REST XML example\r
+\r
+[literal]\r
+ #include <full.c>\r
+ //...\r
+ xmlTextReaderPtr reader = ...; //set up the reader to the url.\r
+ full_ns0_edgeProps *response_element = ...;\r
+ response_element = xml_read_full_ns0_edgeProps(reader);\r
+ //handle the response as needed...\r
+ //free the full_ns0_edgeProps\r
+ free_full_ns0_edgeProps(response_element);\r
+ \r
+ \r
+=== .NET client library\r
+\r
+The .NET client-side library defines the classes that can be (de)serialized to/from XML. This is useful for accessing the REST endpoints that are published by this application.\r
+\r
+==== REST example\r
+\r
+[literal]\r
+ //read a resource from a REST url\r
+ Uri uri = new Uri(...);\r
+ XmlSerializer s = new XmlSerializer(\r
+ typeof( EdgeProps )\r
+ );\r
+ //Create the request object\r
+ WebRequest req = WebRequest.Create(uri);\r
+ WebResponse resp = req.GetResponse();\r
+ Stream stream = resp.GetResponseStream();\r
+ TextReader r = new StreamReader( stream );\r
+ EdgeProps order = (EdgeProps) s.Deserialize( r );\r
+ //handle the result as needed...\r
+ \r
+This bundle contains C# source code.\r
+\r
+=== Java client library\r
+\r
+The Java client-side library is used to access the Web service API for this application.\r
+The JAX-WS client-side library is used to provide the set of Java objects that can be serialized to/from XML using https://jaxb.dev.java.net/[JAXB]. This is useful for accessing the REST endpoints that are published by this application.\r
+\r
+\r
+==== REST example (Raw JAXB)\r
+\r
+[literal]\r
+ java.net.URL url = new java.net.URL(baseURL + "/{containerName}");\r
+ JAXBContext context = JAXBContext.newInstance( EdgeProps.class );\r
+ java.net.URLConnection connection = url.openConnection();\r
+ connection.connect();\r
+ Unmarshaller unmarshaller = context.createUnmarshaller();\r
+ EdgeProps result = (EdgeProps) unmarshaller.unmarshal( connection.getInputStream() );\r
+ //handle the result as needed...\r
+ \r
+ \r
+==== REST example (Jersey client)\r
+\r
+[literal]\r
+</nowiki>\r
+com.sun.jersey.api.client.Client client = com.sun.jersey.api.client.Client.create();\r
+EdgeProps result = client.resource(baseUrl + "/{containerName}")\r
+ .get(EdgeProps.class);\r
+//handle the result as needed... \r
+</nowiki>\r
+\r
+=== Java JSON client library\r
+\r
+The Java client-side library is used to provide the set of Java objects that can be serialized to/from JSON using Jackson. This is useful for accessing the JSON REST endpoints that are published by this application.\r
+\r
+==== REST example (Raw Jackson)\r
+\r
+\r
+[literal]\r
+ java.net.URL url = new java.net.URL(baseURL + "/{containerName}");\r
+ ObjectMapper mapper = new ObjectMapper();\r
+ java.net.URLConnection connection = url.openConnection();\r
+ connection.connect();\r
+ EdgeProps result = (EdgeProps) mapper.readValue( connection.getInputStream(), EdgeProps.class );\r
+ //handle the result as needed...\r
+ \r
+ \r
+=== Objective C Client library\r
+\r
+The Objective C module generates the source code for the Objective C classes and (de)serialization functions that can be used in conjunction with http://xmlsoft.org/[libxml2] to (de)serialize the REST resources as they are represented as XML data.\r
+\r
+\r
+The generated Objective C source code depends on the http://xmlsoft.org/html/libxml-xmlreader.html[XML Reader API] and the http://xmlsoft.org/html/libxml-xmlwriter.html[XML Writer API] as well as the base OpenStep foundation classes.\r
+\r
+==== REST XML example\r
+\r
+[literal]\r
+ #import <full.h>\r
+ //...\r
+ FULLNS0EdgeProps *responseElement;\r
+ NSData *responseData; //data holding the XML from the response.\r
+ NSURL *baseURL = ...; //the base url including the host and subpath.\r
+ NSURL *url = [NSURL URLWithString: @"/{containerName}" relativeToURL: baseURL];\r
+ NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:url];\r
+ NSURLResponse *response = nil;\r
+ NSError *error = NULL;\r
+ [request setHTTPMethod: @"GET"];\r
+ //this example uses a synchronous request,\r
+ //but you'll probably want to use an asynchronous call\r
+ responseData = [NSURLConnection sendSynchronousRequest:request returningResponse:&response error:&error];\r
+ FULLNS0EdgeProps *responseElement = [FULLNS0EdgeProps readFromXML: responseData];\r
+ [responseElement retain];\r
+ //handle the response as needed...\r
+ \r
+\r
+ \r
+ \r
+ \r
+
\ No newline at end of file
--- /dev/null
+== Configuring the OpenDaylight controller\r
+\r
+The common way to configure applications is to use configuration files such as xml or properties files. Although such files are easy for use in small scale applications, they offer limiterd capabilities in the case of fast growing and multi-module applications. Static config files become vast, non-transparent, and inconsistent. For highly dynamic and long living environments, proper configuration is an essential requirement. The OSGi framework provides configuration service (Config Admin), and allows runtime module configuration. However, it still lacks a validation process. A new module configuration can negatively affect other modules. It also does not solve problems relating to the atomicity of the change.\r
+\r
+=== Terms used in this section\r
+\r
+* *Module*: A compact part of a system, whose configuration is managed by the configuration subsystem.\r
+\r
+* *Module factory*: Important for creating module instances. Module factories are uniquely identified by name.\r
+\r
+\r
+* *Service*: Public API, which is used to access module instances, similar to interface in Java. Any module can implement or provide multiple services.\r
+\r
+\r
+* *Configuration*: Application state represented by modules definition, properties, and relations amongst them.\r
+\r
+=== Config component maps\r
+\r
+.Load balancer REST APIs summary\r
+\r
+[cols="3*", options="header"]\r
+\r
+|===\r
+\r
+|Artefact ID |Component |Description\r
+\r
+|config-api +\r
+\r
+config-manager +\r
+\r
+config-util\r
+\r
+|config-subsystem-core\r
+\r
+|Config subsystem core. Manages the configuration of the controller.\r
+Responsibilities include scanning of bundles for ModuleFactories, transactional management of lifecycle and dependency injection for config modules, and exposure of modules and their configuration into JMX.\r
+\r
+\r
+|netty-config-api +\r
+\r
+netty-timer-config +\r
+\r
+netty-threadgroup-config +\r
+\r
+netty-event-executor-config\r
+\r
+|netty-config\r
+\r
+|Config modules for netty related resources e.g. netty-threadgroup, netty-timer etc. \r
+Contains config module definition in form of yang schemas and generated code binding for config subsystem.\r
+\r
+\r
+|shutdown-api +\r
+\r
+shutdown-impl\r
+\r
+|controller-shutdown\r
+\r
+|Controller shutdown mechanism. Brings down the whole OSGi container of the controller. Authorization required in form of a *secret string*. Also contains config module definition in form of yang schemas and generated code binding for config subsystem. This makes it possible to invoke shutdown using config-sbusystem\r
+\r
+\r
+\r
+\r
+|threadpool-config-api +\r
+\r
+threadpool-config-impl\r
+\r
+|threadpool-config\r
+\r
+|Config modules for threading related resources such as threadfactories and fixed-threadpool. \r
+Contains config module definition in the form of yang schemas and generated code binding for config subsystem.\r
+\r
+\r
+\r
+|logback-config\r
+\r
+|logback-config\r
+\r
+|Config modules for logging(logback) related resources such as loggers and appenders. \r
+Contains config module definition in the form of yang schemas and generated code binding for config subsystem.\r
+\r
+\r
+\r
+|netconf-config-dispatcher\r
+\r
+|netconf-config-dispatcher-config\r
+\r
+|Config modules for netconf-dispatcher(from netconf subsystem). \r
+Contains config module definition in form of yang schemas and generated code binding for config subsystem.\r
+\r
+\r
+|yang-jmx-generator +\r
+\r
+yang-jmx-generator-plugin\r
+\r
+|yang-jmx-config-generator\r
+\r
+|Maven plugin that generates the config subsystem code binding from provided yang schemas. This binding is required when bundles want to participate in the config subsystem.\r
+\r
+\r
+\r
+\r
+|yang-test +\r
+\r
+yang-test-plugin\r
+\r
+|yang-jmx-config-generator-testing-modules\r
+\r
+|Testing resources for the maven plugin.\r
+\r
+\r
+|config-persister-api +\r
+\r
+config-persister-file-xml-adapter +\r
+\r
+config-persister-directory-xml-adapter\r
+\r
+\r
+|config-persister\r
+\r
+|Contains api definition for an extensible configuration persister(database for controller configuration). The persister (re)stores the configuration for the controller. Persister implementation can be found in the netconf subsystem. The adapter bundles contain concrete implementations of storage extension. They store the config as xml files on filesystem.\r
+\r
+|config-module-archetype\r
+\r
+|config-module-archetype\r
+\r
+|Maven archetype for *config subsystem aware* bundles. This archetype contains blueprints for yang-schemas, java classes and other files(e.g. pom.xml) required for a bundle to participate in the config subsystem. This archetype generates a bundle skeleton that can be developed into a full blown *config subsystem aware* bundle.\r
+\r
+\r
+|===\r
+\r
+=== Configuration and transactional processes for the OpenDaylight controller\r
+\r
+The Configuration operation has three stages:\r
+\r
+. A proposed configuration is created. Its target is to replace the old configuration.\r
+\r
+. The proposed configuration must be validated before it can be committed. If it passes validation successfully, the proposed state of the configuration is changed to validated. \r
+\r
+. A validated configuration can be committed and the affected modules can be reconfigured. \r
+\r
+In fact, each configuration operation is wrapped in a transaction. Once a transaction is created, it can be configured. A user can abort the transaction during this stage. After the transaction configuration is done, it is committed to the validation stage. In this stage, the validation procedures are invoked. If one or more validations fail, the transaction can be reconfigured. On success, the second phase commit is invoked. If this commit is successful, the transaction enters the last stage known as committed. After that, the required modules are reconfigured. If the second phase commit fails, it means that the transaction is unhealthy. Basically, a new configuration instance creation failed, and the application can be in an inconsistent state.\r
+\r
+image::configuration.jpg[title="Configuration stage", alt="Configuration stage"]\r
+\r
+image::Transaction.jpg[title="Transaction stage", alt="Transaction stage"]\r
+\r
+\r
+To secure the consistency and safety of a new configuration, and to avoid conflicts, the configuration validation process is necessary. Usually, validation checks the input parameters of a new configuration and verifies module-specific relationships. The validation procedure results in a decision indicating whether the proposed configuration is healthy.\r
+\r
+Since there can be dependencies between modules, a change of a module configuration can affect the state of other modules. Therefore, we need to verify whether dependencies on other modules can be resolved. The dependency resolver acts similar to dependency injectors. A dependency tree is built.\r
+\r
+=== SPIs\r
+\r
+Module org.opendaylight.controller.config.spi.Module is a common interface for all modules. Every module must implement it. The module is designated to hold configuration attributes, validate them, and create an instance of service based on the attributes. This instance must implement AutoCloseable interface, owing to resources clean up. If the module was created from an already running instance, it contains an old instance of the module. The module can implement multiple services. If the module depends on other modules, setters need to be annotated with @RequireInterface.\r
+\r
+In creating the module, firstly, the module needs to be configured, be set with all required attributes. Thereafter, the module is moved to the commit stage, where validation is performed. If it fails, the module attributes can be reconfigured. Otherwise, a new instance is created or an old instance is reconfigured. A module instance is identified by ModuleIdentifier which consists of the factory name and instance name.\r
+\r
+\r
+ModuleFactory org.opendaylight.controller.config.spi.ModuleFactory interface must be implemented by each module factory. The module factory can create new module instance in two ways: from an existing module instance or a pure new instance. Also, it can return default modules, useful for populating registry with an already existing configuration. A module factory implementation must have a globally unique name.\r
+\r
+=== APIs\r
+\r
+* *ConfigRegistry*: Represents functionality provided by configuration transaction (create, destroy module, validate, abort transaction).\r
+\r
+\r
+* *ConfigTransactionController?*: Represents functionality for manipulating configuration transactions (begin, commit config ).\r
+\r
+\r
+* *RuntimeBeanRegistratorAwareConfiBean*: The module implementing this interface will recieve RuntimeBeanRegistrator before getInstance is invoked.\r
+\r
+=== Runtime APIs\r
+\r
+* *RuntimeBean*: The common interface for all runtime beans.\r
+\r
+* *RootRuntimeBeanRegistrator*: Represents functionality for the root runtime bean registration, which subsequently allows hierarchical registrations.\r
+\r
+* *HierarchicalRuntimeBeanRegistration*: Represents functionality for the runtime bean registration and unreregistration from hierarchy.\r
+\r
+* *JMX APIs*: JMX API is purposed as a transition between Client API and JMX platform.\r
+\r
+* *ConfigTransactionControllerMXBean*: Extends ConfigTransactionController, executed by Jolokia clients on configuration transaction.\r
+\r
+* *ConfigRegistryMXBean*: Represents the entry point of configuration management for MXBeans.\r
+\r
+NOTE: The Object Name is the pattern used in JMX to locate JMX beans. It consists of domain and key properties (at least one key-value pair). Domain is defined as "org.opendaylight.controller". The only mandatory property is "type".\r
+\r
+=== Use case scenarios\r
+\r
+The list provides a few samples of successful and unsuccessful transactions scenarios.\r
+\r
+==== Successful commit scenario\r
+\r
+. The user creates a transaction calling creteTransaction() method on ConfigRegistry.\r
+\r
+. The ConfigRegisty creates a transaction controller and registers the transaction as a new bean.\r
+\r
+\r
+. Runtime configurations are copied to the transaction. The user can create modules, and set their attributes.\r
+\r
+\r
+. The configuration transaction is committed.\r
+\r
+\r
+. The validation process is performed.\r
+\r
+\r
+. After successful validation, the second phase commit begins.\r
+\r
+\r
+. Modules proposed to be destroyed are destroyed, their service instances are closed.\r
+\r
+\r
+. The Runtime beans are set to registrator.\r
+\r
+\r
+. The transaction controller invokes the method getInstance on each module.\r
+\r
+\r
+. The transaction is committed and resources are closed or released.\r
+\r
+\r
+\r
+==== Validation failure scenario\r
+\r
+The transaction is the same as previous case until the validation step.\r
+\r
+. The user creates a transaction calling creteTransaction() method on ConfigRegistry.\r
+\r
+. The ConfigRegisty creates a transaction controller and registers the transaction as a new bean.\r
+\r
+\r
+. Runtime configurations are copied to the transaction. The user can create modules, and set their attributes.\r
+\r
+\r
+. The configuration transaction is committed.\r
+\r
+\r
+. The validation process is performed.\r
+\r
+\r
+. If validation fails such as illegal input attributes values or dependency resolver failure, ValidationException is thrown and exposed to the user.\r
+\r
+. The user can decide to reconfigure the transaction, commit again, or abort current transaction.\r
+\r
+\r
+. On aborted transactions, TransactionController and JMXRegistrator are properly closed.\r
+\r
+\r
+. The Unregistration event is sent to ConfigRegistry.\r
+\r
+=== Default module instances\r
+\r
+The configuration subsystem provides a way for modules to create default instances. Default instance is an instance of a module that is created at the module bundle startup (module becomes visible for configuration subsystem for example, its bundle is activated in OSGi environment). By default, no default instances are produced.\r
+\r
+\r
+The default instance does not differ from instances created later in the module lifecycle. The only difference is that the configuration for the default instance cannot be provided by the configuration subsystem. The module has to acquire the configuration for these instances on its own, and it can be acquired from, for example, environment variables. After the creation of a default instance, it acts as a regular instance, and fully participates in the configuration subsystem (It can be reconfigured or deleted in following transactions.).\r
+\r
--- /dev/null
+== Kick-starter for OpenDaylight developers\r
+\r
+See updated developer getting started information at the https://wiki.opendaylight.org/view/GettingStarted:Developer_Main[Getting Started for Developers Page].\r
+\r
+=== Downloading the OpenDaylight software\r
+\r
+You can either download the software using CLI or Eclipse. See the relevant sections in the OpenDaylight wiki.\r
+\r
+\r
+=== OpenDaylight infrastructure\r
+\r
+\r
+NOTE: This section is for developers who wish to contribute to the OpenDaylight project. For developers who wish to build proprietary applications based on OpenDaylight, see the section on RESTCONF.\r
+\r
+The OpenDaylight infrastructure consists of the following components.\r
+\r
+* *Source code manager:* http://git-scm.com/[Git]. For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Gerrit_Setup[Getting started with Git and Gerrit].\r
+\r
+* *Code review tool:* https://git.opendaylight.org/gerrit/[Gerrit]. For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Gerrit_Setup[Getting started with Git and Gerrit].\r
+\r
+* *Continuous integration:* https://jenkins.opendaylight.org/[OpenDaylight Jenkins]. For more information, see Getting started with Jenkins.\r
+\r
+* *Artefact repository:* https://nexus.opendaylight.org/[OpenDaylight Nexus] For more information, see https://wiki.opendaylight.org/view/Infrastructure:Nexus[Getting started with Nexus].\r
+\r
+* *Quality Management:* https://sonar.opendaylight.org/[OpenDaylight Sonar]. \r
+\r
+* *Bug tracking:* http://bugs.opendaylight.org/[OpenDaylight Bugzilla]. \r
+\r
+* *Wiki:* https://wiki.opendaylight.org/[OpenDaylight wiki]. \r
+\r
+=== Development workflow for contributing to the OpenDaylight project\r
+\r
+The steps below detail the development workflow for contributing to the OpenDaylight project, including any of its sub projects.\r
+\r
+\r
+. *Identifying the project:* Identify the project under OpenDaylight for which you are going to contribute code. For the list of available projects, see https://wiki.opendaylight.org/view/Main_Page#Projects[OpenDaylight Projects].\r
+\r
+[start=2]\r
+. *Locating the project repository:* Navigate to the selected project page and identify the repository for the project. It maybe listed in the main page or in one of the sub-pages.\r
+\r
+[start=4]\r
+. *Pulling the dependent artefacts:* Pull the dependent artefacts. Most Java and OSGI code bases have a large number of dependencies that are managed by maven. During build, the artefacts (usually binary jars) for those dependencies are pulled from a Development Nexus Artefact Repository.\r
+\r
+[start=3]\r
+. *Pulling the code:* Pull the code from the repository to your local system. For more information, see the relevant section about the project in this developer's guide.\r
+\r
+\r
+[start=5]\r
+. *Contributing to the code:* Start working on the code in your local system. If you think your contributions are ready for review by a group of peer collaborators, push the code to the repository.\r
+\r
+. *Triggering a Jenkins verification:* Trigger a Jenkins verification in Gerrit. Jenkins runs continuous integration tests.\r
+\r
+[start=8]\r
+. *Running CI and verifying the patch:* If the Jenkins tests are successful, the patch is verified in Gerrit.\r
+\r
+. *Reviewing the patch:* A committer picks the patch for consideration. The committer may have comments for you to fix in your code. In this case, make the code changes and re-submit the code for review.\r
+\r
+. *Submitting the patch:* If there are no more comments, the committer indicates to Gerrit that the patch is approved and verified.\r
+\r
+. *Merging the patch:* Gerrit merges the patch into the branch.\r
+\r
+. *Triggering a Jenkins verification:* Jenkins is triggered to run the continuous integration tests on the result of the merge.\r
+\r
+. *Running a Jenkins merge:* Jenkins kicks off the builds for the new artefacts that need to be in the Development Nexus Artifact Repository.\r
+\r
+. *Uploading new artefacts:* If builds (and possible other CI tasks) are successful, Jenkins uploads the new artefacts to the Development Nexus Artefact Repository.\r
+\r
+\r
+=== OpenDaylight architectural principles\r
+\r
+\r
+* *Runtime Modularity and Extensibility*: Allow for a modular, extensible controller that supports installation, removal, and updates to service implementations within a running controller. The feature is also known as in service software upgrade (ISSU).\r
+\r
+* *Multiprotocol Southbound*: Allow for more than one protocol interface with network elements with diverse capabilities southbound from the controller.\r
+\r
+\r
+* *Service Abstraction Layer (SAL)*: Where possible, allow for multiple southbound protocols to present the same northbound service interfaces.\r
+\r
+\r
+* *Open Extensible Northbound API*: Allow for an extensible set of application-facing APIs both across runtimes using REST (level 3 API) and within the same runtime using function calls (level 2 API). The set of accessible functions must be the same.\r
+\r
+\r
+* *Support for Multitenancy/Slicing*: Allow for the network to be logically (and/or physically) split into different slices or tenants with parts of the controller and modules explicitly dedicated to one or a subset of these slices. This includes allowing the controller to present different views of the controller depending on which slice the caller is from.\r
+\r
+\r
+* *Consistent Clustering*: Clustering that gives fine-grained redundancy and scale-out while insuring network consistency.\r
+\r
+\r
+=== Open extensible northbound API\r
+\r
+Allow for an extensible set of application-facing APIs both across runtimes using REST (level 3 API) and within the same runtime using function calls (level 2 API). The set of accessible functions must be the same.\r
+\r
+\r
+Here are the APIs presented by the OpenDaylight projects:\r
+\r
+* OpenDaylight Controller:\r
+** AD-SAL https://wiki.opendaylight.org/view/OpenDaylight_Controller:REST_Reference_and_Authentication[REST and Java APIs]\r
+\r
+\r
+** MD-SAL https://wiki.opendaylight.org/view/OpenDaylight_Controller:RESTCONF_Northbound_APIs[RESTCONF Northbound APIs]\r
+\r
+\r
+* OpenDaylight Virtual Tenant Network - https://wiki.opendaylight.org/view/OpenDaylight_Virtual_Tenant_Network_(VTN):VTN_Coordinator:RestApi[REST API]\r
+\r
+\r
+* Open DOVE - https://wiki.opendaylight.org/view/Open_DOVE:API[Northbound API]\r
+\r
+\r
+* OpenFlow Plugin - N/A\r
+\r
+\r
+* Affinity Metadata Service - N/A\r
+\r
+\r
+* YANG Tools - https://wiki.opendaylight.org/view/YANG_Tools:Available_Models[Available YANG models]\r
+\r
+\r
+* LISP Flow Mapping - https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:Java_API[Java API] and https://wiki.opendaylight.org/view/OpenDaylight_Lisp_Flow_Mapping:REST_API[REST API]\r
+\r
+\r
+* OVSDB - https://wiki.opendaylight.org/view/OVSDB_Integration:REST_API[REST API]\r
+\r
+\r
+* OpenFlow Protocol Library - https://wiki.opendaylight.org/view/Openflow_Protocol_Library:Main#Public_API[public API]\r
+\r
+\r
+* BGP-LS/PCEP - N/A\r
+\r
+\r
+* Defense4All - N/A\r
+\r
+\r
+* SNMP4SDN - https://wiki.opendaylight.org/view/File:SAL_API_for_SNMP_SouthBound_Plugin.pdf[(proposed) API]\r
+\r
--- /dev/null
+== Overview of AD-SAL\r
+\r
+API-Driven Service Abstraction Layer (AD-SAL) is a flavour of the SAL created for the OpenDaylight controller project. The main task of AD-SAL is primarily to create a layer against which the applications can be developed without needing to know the underlying SDN protocols. Using AD-SAL, you can control two different type of network elements in an SDN fashion, meaning by accessing them in a programmatic way. \r
+\r
+AD-SAL was introduced based on the requirements of the network user, such as:\r
+\r
+* Given a network element, list the neighbours and build the network graph.\r
+\r
+* Given a network element, list the interfaces attached to it and what properties they carry.\r
+\r
+Starting from these requirements, we can also assume that certain aspects of the SDN protocols would be common no matter what the actual protocol is doing underneath. This idea allows us to describe the aspects in a generic way using a Java Contract which is usually a set of Java interfaces and supporting objects that represent the data. This way of creating contracts that allows a consumer of the contract to be insulated by the possible implementation is rather common in the Java world. Some examples are as follows:\r
+\r
+* https://www.jcp.org/en/jsr/detail?id=315[Servlet 3.0]\r
+\r
+* http://en.wikipedia.org/wiki/Jax-rs[JAX-RS]\r
+\r
+These examples use http://en.wikipedia.org/wiki/Java_Specification_Request[JSR (Java Specification Request)] which can be implemented by different providers.\r
+\r
+For example Servlet 3.0 contracts can be implemented by Tomcat or Jetty or other servlet container. Going by the same analogy, the protocol plugins (i.e. the components that can understand an SDN protocol and convert them to the common layer) can implement one or more of these contracts based on the capabilities. The SAL defined in AD-SAL is just an adaptation layer to enable the protocol plugins to speak common aspects but only if they can do it. The SAL does not force a lowest common denominator for all to be spoken, but rather given a certain aspect if the protocol plugins supports it, it will be supported in a common fashion.\r
+\r
+=== An example of protocols in AD-SAL\r
+\r
+image::multiprotocol_AD-SAL.jpg[title="Protocols in AD-SAL", alt="Protocols in AD-SAL"]\r
+\r
+\r
+In the image above, there are 4 types of contracts, identified by the coloured triangles, and there are 3 protocol plugins that provide implementation for those contracts. \r
+\r
+For example the *Topology* contract (the one used to learn the network graph) is implemented by all of the protocol plugins while the *Bridge Configuration* contract is only implemented by OVSDB because the others are not capable of it. That is perfectly fine and actually expected because that allows us not to revert to the lowest common denominator feature for all the protocol plugins. \r
+\r
+The image below explains how an application has to deal with the optional presence of a contract on a given network element. In the image, an application is trying to create a bridge on Nodes O1, O2 and OF1, the first two are capable of that contract, the third one is not, so the application has to take care of it and handle the return code.\r
+\r
+image::Applications_AD-SAL.jpg[title="Applications using AD-SAL", alt="Applications using AD-SAL"]\r
+\r
+In summary AD-SAL is just enforcing that the protocol plugins speak a common language for words that can be expressed in a common language. The dictionary of the common language is not hardcoded, it can be extended supplying new contracts to AD-SAL such that new protocols plugin can implement it and applications can consume them.\r
+\r
+To migrate from AD-SAL to MD-SAL, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:AD-SAL_Compatibility[MD-SAL:AD-SAL Compatibility].\r
+\r
+NOTE: For information on MD-SAL, see the relevant pages in this document.\r
+\r
+=== Differences between AD-SAL and MD-SAL\r
+\r
+.Differences between AD-SAL and MD-SAL\r
+\r
+[cols="2*", options="header"]\r
+\r
+|===\r
+\r
+|AD-SAL |MD-SAL \r
+\r
+|API-Driven SAL\r
+\r
+|Model-Driven SAL\r
+\r
+\r
+|The SAL APIs request routing between consumers and providers. Data adaptations are all statically defined at compile or build time.\r
+\r
+|The SAL APIs request routing between consumers and providers as defined from models, and data adaptations are provided by internal adaptation plugins.\r
+\r
+|The AD-SAL typically has both northbound and southbound APIs even for functions or services that are mapped 1:1 between southbound plugins and northbound plugins.\r
+\r
+|The MD-SAL allows both the northbound and southbound plugins to use the same API generated from a model. One plugin becomes an API (service) provider; the other becomes an API (service) consumer.\r
+\r
+|In AD-SAL there is a dedicated REST API for each northbound or southbound plugin.\r
+\r
+| MD-SAL provides a common REST API to access data and functions defined in models.\r
+\r
+|The AD-SAL provides request routing (selects a southbound plugin based on service type) and optionally provides service adaptation, if an northbound (Service, abstract) API is different from its corresponding southbound (protocol) API.\r
+\r
+| The MD-SAL provides request routing and the infrastructure to support service adaptation, but it does not provide service adaptation itself, service adaptation is provided by plugins.\r
+\r
+\r
+|Request routing is based on plugin type. The SAL knows which node instance is served by which plugin, and when a northbound plugin requests an operation on a given node, the request is routed to the appropriate plugin which then routes the request to the appropriate node.\r
+\r
+| Request Routing in the MD-SAL is done on both protocol type and node instances, since node instance data is exported from the plugin into the SAL.\r
+\r
+|AD-SAL is stateless.\r
+\r
+| MD-SAL can store data for models defined by plugins. Provider and consumer plugins can exchange data through the MD-SAL storage.\r
+\r
+\r
+|Limited to flow-capable device and service models only.\r
+\r
+|Model agnostic. It can support any device or service models and is not limited to flow-capable device and service models only.\r
+\r
+\r
+\r
+|AD-SAL services usually provide both asynchronous and synchronous versions of the same API method.\r
+\r
+|In MD-SAL, service model APIs only provide asynchronous APIs, but they return a *java.concurrent.Future* object, which allows a caller to block until the call is processed and a result object is available. Same API can be used for both synchronous and asynchronous approach. Thus MD-SAL encourages asynchronous approach to application design but does not preclude synchronous applications.\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
--- /dev/null
+== OpenDaylight controller overview\r
+\r
+The Open Daylight controller is a JVM software and can be run from any operating system and hardware as long as it supports Java. It is a implementation of the concept of Software Defined Network (SDN).\r
+\r
+=== Background to the emergence of SDN\r
+\r
+Current generation networks and architectures are statically configured and vertically integrated. New generation applications require networks to be agile and flexibly adapt to application requirements. As networks get larger, especially in massively scalable datcenters and cloud, there is a large requirement for ease-of-management and orchestration.\r
+\r
+The following are the requirements of modern consumers of the networking industry:\r
+\r
+\r
+* *Agile networks*: As application programmers require their applications to be moved around in a datacenter or across clouds, it becomes imperative that the network becomes agile in meeting the requirements (bandwidth, services like load balancing, firewall) of the applications.\r
+\r
+* *Vendor neutrality*: Network abstraction and virtualization is required as it allows the network operators to operate the network at a higher level without worrying about the quirkiness of different products from the same or different vendors.\r
+\r
+\r
+* *Ease of building new applications*: Network operators require that they be able to influence the forwarding and other network behavior based on their own algorithms and business logic. That means there is a need for the network to not be vertically integrated with the networking control logic coming only from the networking vendor.\r
+\r
+\r
+=== SDN architecture principles\r
+\r
+SDN consists of a network applications layer on the top written to open API. There is a controller in the middle interacting with and managing network devices. Clearly there needs to be some sort of API or protocol needed for the controller and the network devices to communicate with each other. OpenFlow is one such protocol which has come out of the efforts of Open Networking Foundation (ONF). The network devices support agents which interpret the protocol and the API.\r
+\r
+\r
+Central to the SDN effort is the controller which provides the ability to deploy software to control the network gear and redeploy as needed. The vision is to have a modular controller with a well published Northbound API for network applications to write towards while utilizing southbound protocols such as OpenFlow to communicate with supported downstream network nodes. The industry and end users will benefit immensely by having an OpenSource controller with contributions from various industry players.\r
+\r
+The Open Daylight controller supports not only the OpenFlow protocol but also other open protocols to allow communication with devices which have OpenFlow and/or respective agents. It also includes Northbound APIs to allow customer applications (software) to work with the controller in controlling the network. The customer applications cover a wide spectrum of solutions for solving customer needs across different vertical market segments.\r
+\r
+The controller architecture supports both the hybrid switch model as well as the classical OpenFlow model of having a fully centralized control plane.\r
+\r
+=== OpenDaylight controller framework\r
+\r
+The following image shows the framework of the OpenDaylight controller.\r
+\r
+\r
+image::odl-framework.jpg[title="Framework of OpenDaylight", alt="Framework of OpenDaylight"]\r
+\r
+OpenDaylight uses the following tools or paradigms:\r
+\r
+* *Maven*: OpenDaylight uses Maven for easier build automation. Maven uses pom.xml (Project Object Model) to script the dependencies between bundle and also to describe what bundles to load and start.\r
+\r
+* *OSGi*: This framework is the back-end of OpenDaylight as it allows dynamically loading bundles and packages JAR files, and binding bundles together for exchanging information.\r
+\r
+* *JAVA interfaces*: Java interfaces are used for event listening, specifications, and forming patterns. This is the main way in which specific bundles implement call-back functions for events and also to indicate awareness of specific state.\r
+\r
+* *REST APIs*: These are northbound APIs such as topology manager, host tracker, flow programmer, static routing, and so on.\r
+\r
+The controller exposes open northbound APIs which are used by applications. The OSGi framework and bidirectional REST are supported for the northbound APIs. The OSGi framework is used for applications that run in the same address space as the controller while the REST (web-based) API is used for applications that do not run in the same address space (or even the same system) as the controller. The business logic and algorithms reside in the applications. These applications use the controller to gather network intelligence, run its algorithm to do analytics, and then orchestrate the new rules throughout the network.\r
+\r
+On the southbound, multiple protocols are supported as plugins, e.g. OpenFlow 1.0, OpenFlow 1.3, BGP-LS, and so on. The OpenDaylight controller starts with an OpenFlow 1.0 southbound plugin. Other OpenDaylight contributors begin adding to the controller code. These modules are linked dynamically into a *Service Abstraction Layer* (SAL). \r
+\r
+The SAL exposes services to which the modules north of it are written. The SAL figures out how to fulfil the requested service irrespective of the underlying protocol used between the controller and the network devices. This provides investment protection to the applications as OpenFlow and other protocols evolve over time. For the controller to control devices in its domain, it needs to know about the devices, their capabilities, reachability, and so on. This information is stored and managed by the *Topology Manager*. The other components like ARP handler, Host Tracker, Device Manager, and Switch Manager help in generating the topology database for the Topology Manager.\r
+\r
+The controller has a built in GUI. The GUI is implemented as an application using the same Northbound API as would be available for any other user application.\r
+\r
+See the sections below for an overview of the main components of the OpenDaylight controller.\r
+\r
+=== Service Abstraction Layer framework\r
+\r
+Service Abstraction Layer (SAL) is at the heart of the modular design of the controller and allows it to support multiple protocols on the southbound. SAL also provides consistent services for modules and applications where the business logic is embedded.\r
+\r
+image::SAL.jpg[title="Framework of SAL", alt="Framework of SAL"]\r
+\r
+The OSGi framework allows dynamically linking plugins for the evolving southbound protocols. The SAL provides basic services such as device discovery which is used by modules like Topology Manager to build the topology and device capabilities. Services are constructed using the features exposed by the plugins (based on the presence of a plugin and capabilities of a network device). Based on the service request, the SAL maps to the appropriate plugin and uses the most appropriate southbound protocol to interact with a given network device. Each plugin is independent of others and is loosely coupled with the SAL.\r
+\r
+NOTE: The OpenFlow 1.0 plugin is currently provided with OpenDaylight and other plugins shown in the images are examples of the extensibility of the SAL framework. The SAL framework is included in the Open Daylight controller contribution.\r
+\r
+=== SAL architecture\r
+\r
+\r
+image::sal_architecture.jpg[title="SAL system architecture", alt="SAL system architecture"]\r
+\r
+\r
+The subsystems in the above figure are as follows:\r
+\r
+* *Provider*: A component that exhibits functionality to applications and other providers (plugins) through its northbound API. A provider can be a consumer of other providers. There are two types of providers:\r
+\r
+** *Binding Independent Providers*: Their functionality is exhibited in the binding-independent Data DOM format.\r
+\r
+** *Binding Aware Providers*: Their functionality is exposed in a format compiled against one or more generated binding interfaces.\r
+\r
+* *Consumer*: A component that consumes functionality provided by one or more providers. There are two types of consumers:\r
+\r
+** *Binding Independent Consumers*: Their functionality is consumed in the binding-independent Data DOM format.\r
+\r
+** *Binding Independent Consumers*: Their functionality is consumed using one or more generated binding interfaces.\r
+\r
+* *Binding Independent Broker*: The core component of the model-driven SAL. It routes RPCs, notifications and data changes between various providers and consumers.\r
+\r
+* *Binding Aware Broker*: Provides programmatic APIs and Java language support to both consumers such as controller applications or plugins and providers. It is a façade or proxy built on top of the Binding Independent Broker that simplifies access to data and services provided by Binding-Independent providers and Binding-Aware providers.\r
+\r
+\r
+* *BI Data Repository*: A binding-independent infrastructure component of SAL that is responsible for storage of configuration and transient data.\r
+\r
+* *Binding Schema Repository*: An infrastructure component responsible for storing specifications of YANG–Java relationships and mapping between language-binding APIs to binding-independent API calls.\r
+\r
+* *Binding Generator*: A SAL infrastructure component which generates implementations of binding interfaces and data mappers to the binding-independent format.\r
+\r
+=== SAL architecture subsystems\r
+\r
+In context of the controller architecture, two subsystem categories are defined:\r
+\r
+\r
+* *Top-Level Subsystems*: Subsystems such as a data store, or a validator. There is typically only a single instance of a top-level subsystem per API revision. Top-level subsystems can be controller components or applications (providers or consumers) deployed in the controller that use the controller SAL to communicate with other controller components, applications, and plugins.\r
+Top-Level Subsystems usually have either a single instance per system or API, or multiple versioned instances, where each instance is unique to a revision of the contract defined by YANG models. In the latter case, each instance represents a single closed system. Prime examples for top-level subsystem are brokers and data repositories.\r
+\r
+* *Nested Subsystems*: A subsystem which could be local or remote. It can expose a set of functionality at multiple places or in multiple instances. A network element, such as a router or switch, is an example of a nested subsystem. Data of a nested subsystem is attached or mounted under a node in the controller’s datastore. The data in a nested subsystem may represent data present in another system or in a local controller component, such as a plugin. It may also be dynamically generated by a controller component, or translated from other protocols.\r
+\r
+NOTE: Consumers may need to invoke the functionality provided by nested subsystems. An RPC Broker must provide functionality that enableS nested RPC functionality in Providers. Furthermore, a Broker must be able to route RPCs to the Providers of nested subsystems for further processing.\r
+\r
+\r
+=== SAL service sets\r
+\r
+* *Topology services* is a set of services that allow to convey topology information such as discovering a new node, a new link, and so on.\r
+\r
+* *Data Packet services* are SAL services that deliver the packets coming from the agents to applications.\r
+\r
+* *Flow Programming services* provide the necessary logic to program different match-actions rules.\r
+\r
+* *Statistics services* export APIs to collect statistics per flow, node connector, queue, and so on.\r
+\r
+* *Inventory services* provide APIs for returning inventory information about the node and node connectors for example.\r
+\r
+* *Resource services* is a placeholder to query resource status.\r
+\r
+\r
+==== Data packet service as example of SAL service implementation\r
+\r
+As an example of a SAL service implementation, see the Data Packet Service with OpenFlow 1.0 plugin in the section below.\r
+\r
+image::data_packet_service.jpg[title="Data packet service ", alt="Data packet service"]\r
+\r
+\r
+* *IListenDataPacket* is a service implemented by the upper layer module or application (ARP Handler is one such module) which wants to receive data packets.\r
+\r
+\r
+* *IDataPacketService* is an interface that provides the service of sending and receiving packets from the agent. This service is registered in the OSGi service registry so that an application can retrieve it.\r
+\r
+* *IPluginOutDataPacketService* is an interface that is exported by SAL when a protocol plugin wants to deliver a packet toward the application layer.\r
+\r
+* *IPluginInDataPacketService* is an interface that is exported by the protocol plugin and is used to send out the packets through SAL towards the agent on the network devices.\r
+\r
+The process followed by the SAL is described as follows:\r
+\r
+. The OpenFlow plugin receives an ARP packet that must be dispatched to the ARP handler application.\r
+\r
+. The OpenFlow Plugin calls *IPluginOutDataPacketService* to get the packet to the SAL.\r
+\r
+. The ARP handler application is registered to the *IListenDataPacket Service*. The SAL hands over the packet to the ARP handler application.\r
+\r
+\r
+. The application now processes the packet.\r
+\r
+\r
+For the reverse process of the application sending a packet out, the process followed is described below:\r
+\r
+. The application constructs the packet and calls the interface *IDataPacketService* to send the packet. The destination network device is to be provided as part of the API.\r
+\r
+. SAL calls the *IPluginInDataPacketService* interface for a given protocol plugin based on the destination network device, the protocol is OpenFlow in this case.\r
+\r
+. The protocol plugin then ships the packet to the appropriate network element. The plugin handles all protocol-specific processing.\r
+\r
+NOTE: For more information on other service sets, see the Java and API documentation.\r
+\r
+=== Northbound and southbound plugins\r
+\r
+See the images below for examples of SAL northbound and southbound plugins.\r
+\r
+image::SAL_NB_Plugins.jpg[title="SAL northbound plugins", alt="SAL northbound plugins"]\r
+\r
+\r
+image::SAL_sb.jpg[title="SAL southbound plugins", alt="SAL southbound plugins"]\r
+\r
+=== OpenDaylight modules\r
+\r
+The following are the OpenDaylight modules. See the relevant sections for an overview of each module.\r
+\r
+* AD-SAL - API-Driven Service Abstraction Layer\r
+\r
+* AD-SAL Network Service Functions for OpenFlow-capable nodes:\r
+\r
+** Switch Manager\r
+\r
+** Statistics Manager\r
+\r
+** Host Tracker\r
+\r
+** ARP Handler\r
+\r
+** Forwarding Rules Manager (FRM)\r
+\r
+** Topology Manager\r
+\r
+* Clustering and High-Availability Services for AD-SAL\r
+\r
+* MD-SAL - Model-Driven Service Adaptation Layer\r
+\r
+* MD-SAL Base Network Functions:\r
+\r
+** Topology Exporters\r
+\r
+** Inventory Managers\r
+\r
+* MD-SAL Network Service Functions for OpenFlow-capable nodes:\r
+\r
+** Forwarding Rules Manager (FRM)\r
+\r
+** Statistics Manager\r
+\r
+* MD-SAL Netconf Connector (Southbound Netconf Plugin)\r
+\r
+* MD-SAL Restconf Connector (Northbound Restconf Plugin) - an infrastructure component that renders REST APIs for device/service models loaded into the controller\r
+\r
+* Config Subsystem - Netconf/Yang based framework for configuration, performance and fault management of controller infrastructure and plugins deployed into the controller\r
+\r
+* NSF Adapters - Network Service Function Adapter that allow the MD-SAL based OF1.0/1.3 Plugin to talk with AS-SAL based Network Service Functions\r
+\r
+\r
+=== OpenDaylight controller GUI\r
+\r
+The GUI is implemented as an application and uses the northbound REST API to interact with the other modules of the controller. The architecture thus ensures that whatever is available with the GUI is also available using the REST API. The controller can be integrated easily into other management or orchestration systems.\r
+\r
+=== High Availability\r
+\r
+The OpenDaylight controller supports a cluster-based high availability model. There are several instances of the OpenDaylight controller which logically act as one logical controller. This not only gives redundancy but also allows a scale-out model for linear scalability. To make the controller highly available, resilience needs to be added at the controller, OpenFlow-enabled switches, and the applications.\r
+\r
+The OpenFlow enabled switches connect to two or more instances of the controller using persistent point-to-point TCP/IP connection. On the northbound side, between the controller and the applications, the interaction is done using RESTful webservices. This is applicable for all the request-response types of interaction. The interactions based on HTTP and being HTTP based on non-persistent connections between the server and the client, it's possible to leverage all the high-available techniques used to give resilience on the web such as:\r
+\r
+* Providing the cluster of controller with a virtual IP to be reached using an anycast type of solution\r
+\r
+\r
+* Having the application to talk to the cluster after a DNS request is done using a DNS round-robin technique\r
+\r
+* Deploying between the applications and the cluster of controller an HTTP load-balancer that can not only provide resilience but also distributed the workload accordingly to the URL requested.\r
+\r
+The interaction between the controller(s) and the Open-Flow enabled switches is essentially to have one Openflow switch multi-homed to multiple controller, so if one of the controller goes down another is ready to control the switch. This interaction has already been specified in the OpenFlow 1.2 specifications in particular Section 6.3 of Openflow 1.2 specifications. To summarize it when having multiple controllers connected to one switch, the openflow 1.2 specification specify two mode of operations:\r
+\r
+* Equal interaction: in this case all the controllers have read/write access to the switch, which means they have to syncronize in order no to step on each other feet.\r
+\r
+\r
+* Master/Slave interaction: in this case there will be one master and multiple slaves (there could be still multiple equal as well)\r
+\r
+\r
+For more information, see the OpenDaylight wiki.\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
--- /dev/null
+== Getting started with Git and Gerrit\r
+\r
+Git is an opensource distributed version control system (dvcs) written in the C language and originally developed by Linus Torvalds and others to manage the Linux kernel. In Git, there is no central copy of the repository. After you have cloned the repository, you have a functioning copy of the source code with all the branches and tagged releases, in your local repository.\r
+\r
+Gerrit is an opensource web-based collaborative code review tool that integrates with Git. It was developed at Google by Shawn Pearce. Gerrit provides a framework for reviewing code commits before they are accepted into the code base. Changes can be uploaded to Gerrit by any user. However, the changes are not made a part of the project until a code review is completed. Gerrit is also a good collaboration tool for storing the conversations that occur around the code commits.\r
+\r
+The OpenDaylight source code is hosted in a repository in Git. Developers must use Gerrit to commit code to the OpenDaylight repository.\r
+\r
+NOTE: For more information on Git, see http://git-scm.com/. For more information on Gerrit, see https://code.google.com/p/gerrit/.\r
+\r
+=== Setting up a Gerrit account\r
+\r
+. Using a Google Chrome or Mozilla Firefox browser, go to https://git.opendaylight.org/gerrit\r
+\r
+The main page shows existing Gerrit requests. These are patches that have been pushed to the repository and not yet verified, reviewed, and merged.\r
+\r
+NOTE: If you already have an OpenDaylight account, you can click *Sign In* in the top right corner of the page and follow the instructions to enter the OpenDaylight page.\r
+\r
+.Signing in to OpenDaylight account\r
+\r
+image::Sign_in.jpg[Signing in to OpenDaylight account]\r
+\r
+[start=2]\r
+\r
+. If you do not have an existing OpenDaylight account, click *Account signup/management* on the top bar of the main Gerrit page.\r
+\r
+The *WS02 Identity Server* page is displayed.\r
+\r
+\r
+.Gerrit Account signup/management link\r
+\r
+image::Gerrit_setup.jpg[Account signup/management link]\r
+\r
+[start=3]\r
+\r
+. In the *WS02 Identity Server* page, click *Sign-up* in the left pane.\r
+\r
+There is also an option to authenticate your sign in with OpenID. This option is not described in this document.\r
+\r
+.Sign-up link for Gerrit account\r
+\r
+image::sign-up.jpg[Sign-up link for Gerrit account]\r
+\r
+[start=4]\r
+\r
+. Click on the *Sign-up with User Name/Password* image on the right pane to continue to the actual sign-up page.\r
+\r
+.Sign-up with User Name/Password Image\r
+\r
+image::signup_image.jpg[Sign-up with User Name / Password Image]\r
+\r
+[start=5]\r
+\r
+. Fill out the details in the account creation form and then click *Submit*.\r
+\r
+.Filling out the details\r
+\r
+image::form_details.jpg[Filling out the details]\r
+\r
+You now have an OpenDaylight account that can be used with Gerrit to pull the OpenDaylight code.\r
+\r
+=== Generating SSH keys for your system\r
+\r
+You must have SSH keys for your system to register with your Gerrit account. The method for generating SSH keys is different for different types of operating systems.\r
+\r
+The key you register with Gerrit must be identical to the one you will use later to pull or edit the code. For example, if you have a development VM which has a different UID login and keygen than that of your laptop, the SSH key you generate for the VM is different from the laptop. If you register the SSH key generated on your VM with Gerrit and do not reuse it on your laptop when using Git on the laptop, the pull fails.\r
+\r
+NOTE: For more information on SSH keys for Ubuntu, see https://help.ubuntu.com/community/SSH/OpenSSH/Keys. For generating SSH keys for Windows, see https://help.github.com/articles/generating-ssh-keys.\r
+\r
+For a system running Ubuntu operating system, follow the steps below:\r
+\r
+. Run the following command:\r
+\r
+[literal]\r
+\r
+mkdir ~/.ssh\r
+chmod 700 ~/.ssh\r
+ssh-keygen -t rsa\r
+\r
+[start=2]\r
+\r
+. You are prompted for a location to save the keys, and a passphrase for the keys.\r
+\r
+This passphrase protects your private key while it is stored on the hard drive. You must use the passphrase to use the keys every time you need to login to a key-based system.\r
+\r
+[literal]\r
+\r
+Generating public/private rsa key pair.\r
+Enter file in which to save the key (/home/b/.ssh/id_rsa):\r
+Enter passphrase (empty for no passphrase):\r
+Enter same passphrase again:\r
+Your identification has been saved in /home/b/.ssh/id_rsa.\r
+Your public key has been saved in /home/b/.ssh/id_rsa.pub.\r
+\r
+Your public key is now available as *.ssh/id_rsa.pub* in your home folder.\r
+\r
+=== Registering your SSH key with Gerrit\r
+\r
+. Using a Google Chrome or Mozilla Firefox browser, go to https://git.opendaylight.org/gerrit.\r
+\r
+[start=2]\r
+. Click *Sign In* to access the OpenDaylight repository.\r
+\r
+.Signin in to OpenDaylight repository\r
+\r
+image::Sign_in.jpg[Signin in to OpenDaylight repository]\r
+\r
+[start=3]\r
+. Click your name in the top right corner of the window and then click *Settings*.\r
+\r
+The *Settings* page is displayed.\r
+\r
+.Settings page for your Gerrit account\r
+\r
+image::Gerrit_settings.jpg[Settings page for your Gerrit account]\r
+\r
+[start=4]\r
+. Click *SSH Public Keys* under *Settings*.\r
+\r
+. Click *Add Key*.\r
+\r
+. In the *Add SSH Public Key* text box, paste the contents of your *id_rsa.pub* file and then click *Add*.\r
+\r
+.Adding your SSH key\r
+\r
+image::SSH_keys.jpg[Adding your SSH key]\r
+\r
+To verify your SSH key is working correctly, try using an SSH client to connect to Gerrit's SSHD port. \r
+\r
+[literal]\r
+\r
+$ ssh -p 29418 <sshusername>@git.opendaylight.org\r
+Enter passphrase for key '/home/cisco/.ssh/id_rsa': \r
+**** Welcome to Gerrit Code Review ****\r
+Hi <user>, you have successfully connected over SSH.\r
+Unfortunately, interactive shells are disabled.\r
+To clone a hosted Git repository, use: git clone ssh://<user>@git.opendaylight.org:29418/REPOSITORY_NAME.git\r
+Connection to git.opendaylight.org closed.\r
+\r
+You can now proceed to either Pulling, Hacking, and Pushing the Code from the CLI or Pulling, Hacking, and Pushing the Code from Eclipse depending on your implementation.\r
+\r
+\r
+\r
+\r
--- /dev/null
+== Load balancer service as a sample OpenDaylight application\r
+\r
+This is a sample load balancer application that balances traffic to back-end servers based on the source address and source port on each incoming packet. The service reactively installs OpenFlow rules to direct all packets with a specific source address and source port to one of the appropriate back-end servers. The servers may be selected using a round robin policy or a random policy. This service can be configured using a REST API which is similar to the OpenStack Quantum LBaaS (Load-balancer-as-a-Service) v1.0 API proposal at http://wiki.openstack.org/Quantum/LBaaS.\r
+\r
+To use the load balancer service, a virtual IP (or VIP) must be introduced to the clients of the service and used as the destination address. \r
+\r
+NOTE: A VIP is an entity that comprises of a virtual IP, port, and protocol (TCP or UDP).\r
+\r
+=== Assumptions for the VIP\r
+\r
+The assumptions for the VIP are as follows:\r
+\r
+* One or more VIPs may be mapped to the same server pool. \r
+\r
+* All VIPs that share the same pool must also share the same load balancing policy. The policy may be random or round robin.\r
+\r
+* Only one server pool can be be assigned to a VIP.\r
+\r
+* All flow rules are installed with an idle time-out of 5 seconds.\r
+\r
+* The flow rules must automatically time out after the idle time-out of 5 seconds.\r
+\r
+* Packets to a VIP must leave the OpenFlow cluster from the same switch from where they entered.\r
+\r
+\r
+* When you delete a VIP or a server pool or a server from a pool, the service does not delete the already installed flow rules. \r
+\r
+\r
+=== Load balancer REST APIs summary\r
+\r
+.Load balancer REST APIs summary\r
+\r
+[cols="5*", options="header"]\r
+\r
+|===\r
+\r
+|Description |URI |Type |Request Body/Arguments |Response Codes\r
+\r
+|List details of all existing pools\r
+\r
+|/one/nb/v2/lb/{container-name*}/\r
+\r
+|GET\r
+\r
+| \r
+\r
+\r
+|200 ("Operation successful") +\r
+\r
+404 ("The containerName is not found") +\r
+\r
+503 "Load balancer service is unavailable")\r
+\r
+\r
+\r
+|List details of all existing VIPs\r
+\r
+|/one/nb/v2/lb/{container-name}/vips\r
+\r
+|GET\r
+\r
+|\r
+\r
+\r
+|200 ("Operation successful") +\r
+\r
+404 ("The containerName is not found") +\r
+\r
+503 ("Load balancer service is unavailable")\r
+\r
+\r
+\r
+|Create pool \r
+\r
+|/one/nb/v2/lb/{container-name}/create/pool\r
+\r
+\r
+|POST\r
+\r
+\r
+|{\r
+"name":"",\r
+"lbmethod":""\r
+}\r
+\r
+|201 ("Pool created successfully") +\r
+\r
+404 ("The containerName not found") +\r
+\r
+503 ("Load balancer service is unavailable") +\r
+\r
+409 ("Pool already exist") +\r
+\r
+415 ("Invalid input data") +\r
+ \r
+\r
+|Delete pool\r
+\r
+|/one/nb/v2/lb/{container-name}/delete/pool/{pool-name}\r
+\r
+|Delete\r
+\r
+|\r
+\r
+\r
+|200 ("Pool deleted successfully") + \r
+\r
+404 ("The containerName not found") +\r
+\r
+503 ("Load balancer service is unavailable") +\r
+\r
+404 ("Pool not found") +\r
+\r
+500 ("Failed to delete pool")\r
+\r
+|Create VIP\r
+\r
+|/one/nb/v2/lb/{container-name}/create/vip\r
+\r
+|POST\r
+\r
+|{\r
+"name":"", \r
+"ip":"ip in (xxx.xxx.xxx.xxx) format", \r
+"protocol":"TCP/UDP", \r
+"port":"any valid port number", \r
+"poolname":"" (optional) \r
+}\r
+\r
+|201 ("VIP created successfully")+\r
+ \r
+404 ("The containerName not found") +\r
+\r
+503 ("Load balancer service is unavailable")+\r
+ \r
+409 ("VIP already exists") +\r
+\r
+415 ("Invalid input data")\r
+\r
+\r
+|Update VIP\r
+\r
+|/one/nb/v2/lb/{container-name}/update/vip\r
+\r
+|PUT\r
+\r
+|{ \r
+"name":"", \r
+"poolname":"" \r
+}\r
+\r
+|201 ("VIP updated successfully") +\r
+\r
+404 ("The containerName not found") +\r
+\r
+503 ("VIP not found") +\r
+\r
+404 ("Pool not found") +\r
+\r
+405 ("Pool already attached to the VIP") +\r
+\r
+415 ("Invalid input name")\r
+\r
+|Delete VIP\r
+\r
+|/one/nb/v2/lb/{container-name}/delete/vip/{vip-name}\r
+\r
+|DELETE\r
+\r
+|\r
+\r
+\r
+|200 ("VIP deleted successfully") +\r
+\r
+404 ("The containerName not found") +\r
+\r
+503 ("Load balancer service is unavailable") +\r
+\r
+404 ("VIP not found") +\r
+\r
+500 ("Failed to delete VIP") \r
+\r
+\r
+|Create pool member\r
+\r
+\r
+|/one/nb/v2/lb/{container-name}/create/poolmember\r
+\r
+\r
+|POST\r
+\r
+|{ \r
+"name":"", \r
+"ip":"ip in (xxx.xxx.xxx.xxx) format", \r
+"poolname":"existing pool name" \r
+}\r
+\r
+\r
+|201 ("Pool member created successfully") +\r
+ \r
+404 ("The containerName not found") +\r
+\r
+503 ("Load balancer service is unavailable") +\r
+\r
+404 ("Pool not found") +\r
+\r
+409 ("Pool member already exists") +\r
+\r
+415 ("Invalid input data") +\r
+ \r
+\r
+|Delete pool member \r
+\r
+|/one/nb/v2/lb/{container-name}/delete/poolmember/{pool-member-name}/{pool-name}\r
+\r
+|DELETE\r
+\r
+|\r
+\r
+|200 ("Pool member deleted successfully") +\r
+\r
+404 ("The containerName not found") +\r
+\r
+503 ("Load balancer service is unavailable") +\r
+\r
+404 ("Pool member not found") +\r
+\r
+404 ("Pool not found")\r
+\r
+|===\r
+\r
+\r
+NOTE: Current implementation of OpenDaylight uses `default` as a container name. Property `name` of each individual entity must be unique.\r
+\r
+=== Starting the load balancer\r
+\r
+. Start the OpenDaylight controller. Ensure that the *samples.loadbalancer* and *samples.loadbalancer.northbound* modules are loaded by the controller.\r
+\r
+. Create any mininet topology and connect it to the controller. For this example, assume a tree topology with *depth=2* and *fanout=4*. This topology creates 16 hosts, 4 edge switches each connected to 4 hosts, and 1 core switch connected to all the 4 edge switches. You can use the following command to start mininet with this tree topology.\r
+\r
+[literal]\r
+\r
+mn --topo=tree,2,4 --controller=remote,ip=<Host IP where controller is running>,port=6633\r
+\r
+This default tree topology assigns ip addresses from 10.0.0.1 to 10.0.0.16/8 IP to its 16 hosts.\r
+\r
+[start=3]\r
+\r
+. Add a default gateway in OpenDaylight for the mininet network as mentioned in the following URL: https://wiki.opendaylight.org/view/OpenDaylight_Controller:Installation\r
+\r
+. Run the command *pingall* in mininet and make sure that all the hosts are reachable from each other.\r
+\r
+. Create the load balancer pool with round robin load balancing policy as follows:\r
+\r
+[literal]\r
+\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/create/pool -d '{"name":"PoolRR","lbmethod":"roundrobin"}'\r
+\r
+[start=6]\r
+. Create the load balancer VIP as follows:\r
+\r
+[literal]\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/create/vip -d '{"name":"VIP-RR","ip":"10.0.0.20","protocol":"TCP","port":"5550","poolname":"PoolRR"}'\r
+\r
+Pool-name data in the REST call above is optional. In case no pool exists while creating the VIP, you can attach the pool at a later point of time by using the following REST call:\r
+\r
+[literal]\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X PUT\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/update/vip -d '{"name":"VIP-RR","poolname":"PoolRR"}'\r
+\r
+\r
+[start=7]\r
+. Add pool members to the load balancer pool. Host H1 (10.0.0.1) will be used as a source or client that sends traffic to the VIP.\r
+\r
+[literal]\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/create/poolmember -d '{"name":"PM2","ip":"10.0.0.2","poolname":"PoolRR"}'\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X POST\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/create/poolmember -d '{"name":"PM3","ip":"10.0.0.3","poolname":"PoolRR"}'\r
+\r
+Similarly you can add all the remaining 13 hosts to the pool.\r
+\r
+[start=8]\r
+. Since the VIP created in step 6 does not exist in the network, the controller does not resolve the ARP for the IP of the VIP. The load balancer application assumes that if the VIP is configured and exposed by the user to an internal or external network. Packets that are destined to the VIP's IP address gets routed to it through external mechanisms. For this example, we can locally resolve the ARP for the VIP's IP, by adding static entry to the ARP table of the client or source host. The steps below takes you through details of how to accomplish the step.\r
+\r
+==== Locally resolving ARP for the VIP's IP\r
+\r
+. Spawn xterm for hosts h1 to h4 from the mininet prompt.\r
+\r
+. Add static ARP entry for VIP's IP address in the host h1 ARP cache. Run the following command in the h1 xterm window to add the ARP entry.\r
+\r
+[literal]\r
+arp -s 10.0.0.20 00:00:10:00:00:20\r
+\r
+[start=3]\r
+\r
+. On h1, start iperf client that sends traffic to the virtual ip address.\r
+\r
+[literal]\r
+iperf -c 10.0.0.20 -p 5550\r
+\r
+The iperf client connects to the iperf server running on host h2.\r
+\r
+[start=4]\r
+\r
+. After the previous test of iperf finishes, trigger the iperf client again. The iperf client connects to the iperf server running on host h3. Similarly, in the next iteration, it connects to the h4 node in round robin fashion.\r
+\r
+Similarly, you can try the random load balancing policy by creating the load balancer pool with `random` policy. \r
+\r
+\r
+=== Cleaning the load balancer entity\r
+\r
+You can run the following curl commands to clean up the load balancer entities you created in the previous section.\r
+\r
+==== Deleting pool members\r
+\r
+Delete pool members by running the command below:\r
+\r
+[literal]\r
+\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X DELETE\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/delete/poolmember/PM2/PoolRR'\r
+\r
+You can delete the remaining pool members similarly.\r
+\r
+==== Deleting VIP\r
+\r
+Delete VIP by running the command below:\r
+\r
+[literal]\r
+\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X DELETE\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/delete/vip/VIP-RR\r
+\r
+\r
+==== Deleting pool\r
+\r
+Delete pool by running the command below:\r
+\r
+[literal]\r
+curl --user "admin":"admin" -H "Accept: application/json" -H "Content-type: application/json" -X DELETE\r
+http://<Controller_IP>:8080/one/nb/v2/lb/default/delete/pool/PoolRR\r
+\r
--- /dev/null
+== Pulling, contributing, and pushing the OpenDaylight controller code using the GIT CLI\r
+\r
+The OpenDaylight project has a number of sub-projects under it. Each of these sub-projects have their own repositories in Gerrit. You can use either Git or Eclipse to contribute to the code for any of these sub-projects.\r
+\r
+For a list of OpenDaylight projects, see https://wiki.opendaylight.org/view/Main_Page#Projects[OpenDaylight Projects].\r
+\r
+=== Prerequisites for contributing code to the OpenDaylight project\r
+\r
+* You have created a Gerrit account and have registered a public-private key pair for using Git over SSH. For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Gerrit_Setup[Getting started with Git and Gerrit].\r
+\r
+* Your credentials (name, email) are configured properly in Git by running the following command:\r
+\r
+[literal]\r
+git config --global user.name "John Doe"\r
+git config --global user.email johndoe@example.com\r
+\r
+* You are familiar with Git commands. For more information, see https://wiki.opendaylight.org/view/GIT_Cheat_Sheet[GIT Cheat Sheet].\r
+\r
+* You have installed Maven in your system. For more information about Maven, see http://maven.apache.org/[Apache Maven Project].\r
+\r
+To install Maven using *yum* as the package manager, run the command:\r
+\r
+[literal]\r
+sudo yum install maven\r
+\r
+* You have installed Java 1.7+ in your system, including the JDK. For more information, see http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java SE Downloads].\r
+\r
+To install Java using *yum* as the package manager, run the command:\r
+\r
+[literal]\r
+sudo yum install java-1.7.0-openjdk\r
+\r
+The output must match the sample message given below:\r
+\r
+[literal]\r
+[~]$ java -version\r
+java version "1.7.0_55"\r
+OpenJDK Runtime Environment (fedora-2.4.7.0.fc20-x86_64 u55-b13)\r
+OpenJDK 64-Bit Server VM (build 24.51-b03, mixed mode)\r
+\r
+NOTE: For more information on setting up the environment for developing code for OpenDaylight, see https://wiki.opendaylight.org/view/GettingStarted:Development_Environment_Setup[Getting Started with the Development Environment].\r
+\r
+NOTE: You may also use the git review tool to push your changes to the repository. For more information, see https://wiki.opendaylight.org/view/Git-review_Workflow[Git Review Workflow]\r
+\r
+\r
+\r
+\r
+=== Building the OpenDaylight code\r
+\r
+Run the following command:\r
+\r
+[literal]\r
+cd opendaylight/distribution/opendaylight/\r
+mvn clean install\r
+\r
+=== Troubleshooting Maven issues\r
+\r
+* The Maven build may run out of PermGen depending on the number of artifacts built. This issue usually occurs when building the opendaylight distribution. To resolve the issue, increase the PermGens. Set the value of the environment variable as follows:\r
+\r
+[literal]\r
+MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=512m"\r
+/* syntax for setting varies on the OS used by the build machine.*/\r
+\r
+* If you receive a Maven error when building northbound integration tests, you can skip building the tests by running the following command:\r
+\r
+[literal]\r
+mvn clean install -DskipTests \r
+/* instead of "mvn clean install" */\r
+\r
+* If you have issues with maven needing a proxy, see http://www.mkyong.com/maven/how-to-enable-proxy-setting-in-maven/[How To Enable Proxy Setting In Maven].\r
+\r
+=== Running the OpenDaylight controller\r
+\r
+. Run the following command:\r
+\r
+[literal]\r
+cd controller/opendaylight/distribution/opendaylight/target/distribution.opendaylight-osgipackage/opendaylight/\r
+./run.sh\r
+\r
+\r
+[start=2]\r
+. Go to *http://localhost:8080/* and login in with username *admin* and password *admin*.\r
+\r
+\r
+NOTE: For more information in running the controller, see the Installation Guide.\r
+\r
+\r
+=== Pulling the code from the remote repository\r
+\r
+To pull the latest changes from the Git repository, run the following command:\r
+\r
+[literal]\r
+git pull ssh://<username>@git.opendaylight.org:29418/controller.git HEAD:refs/for/master\r
+\r
+=== Committing the code using the Developer Certificate of Origin\r
+\r
+Your contributions to the OpenDaylight code is accepted only if you attach the http://elinux.org/Developer_Certificate_Of_Origin[Developer Certificate Of Origin]. The certificate implies that you have made the changes and the work was done as part of an open-source license.\r
+\r
+To attach the certificate, run the command below:\r
+\r
+[literal]\r
+git commit --signoff\r
+\r
+Or\r
+\r
+[literal]\r
+git commit -s\r
+\r
+You are prompted for a commit message. If you are fixing an issue from Bugzilla, you can add the information to your commit message and it will get linked from Gerrit.\r
+\r
+[literal]\r
+Fix for bug 2.\r
+Signed-off-by: Ed Warnicke <eaw@cisco.com>\r
+# Please enter the commit message for your changes. Lines starting\r
+# with '#' will be ignored, and an empty message aborts the commit.\r
+# On branch master\r
+# Changes to be committed:\r
+# (use "git reset HEAD <file>..." to unstage)\r
+#\r
+# modified: README\r
+#\r
+\r
+If you wish to add the signoff to the commit message on your every commit without the need to specify *--s* or *--signoff*, add the following lines in the end of *.git/hooks/commit-msg*, after the line *"add_ChangeId"*:\r
+\r
+[literal]\r
+SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')\r
+grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"\r
+\r
+\r
+=== Pushing the code\r
+\r
+* To push your changes to the repository, run the command below:\r
+\r
+[literal]\r
+git push ssh://<username>@git.opendaylight.org:29418/controller.git HEAD:refs/for/master\r
+\r
+To push a draft that is not to be merged, run the command below:\r
+\r
+[literal]\r
+git push ssh://<username>@git.opendaylight.org:29418/controller.git HEAD:refs/drafts/master\r
+\r
+A message similar to the following is displayed:\r
+\r
+[literal]\r
+remote: Resolving deltas: 100% (2/2)\r
+remote: Processing changes: new: 1, refs: 1, done \r
+remote: \r
+remote: New Changes:\r
+remote: http://git.opendaylight.org/gerrit/64\r
+remote: \r
+\r
+=== Reviewing and merging the code\r
+\r
+. Copy the link from the display message of your git push command and run it in a browser.\r
+The link must display that the code is verified by the Jenkins Controller User and a link is provided to the Jenkins build. See the figure below.\r
+\r
+image::Jenkins_message.jpg[title="Code Changes in Gerrit", alt="Code Changes in Gerrit"]\r
+\r
+\r
+[start=2]\r
+. After your code is reviewed and submitted by a committer, it will be merged into the authoritative repository. See the figure below.\r
+\r
+image::merged_code.jpg[title="Merging Code in Gerrit", alt="Merging Code in Gerrit"]\r
+\r
+=== Troubleshooting blocked port 29418\r
+\r
+There have been reports that many firewalls may block port 29418. To resolve the issue, use HTTP to clone the repository.\r
+\r
+[literal]\r
+git clone https://<your_username>@git.opendaylight.org/gerrit/p/controller.git\r
+\r
+You are prompted for the password you generated in https://wiki.opendaylight.org/view/OpenDaylight_Controller:Setting_up_HTTP_in_Gerrit[Setting up HTTP in Gerrit].\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
+\r
--- /dev/null
+== Running the OpenDaylight controller\r
+\r
+NOTE: Download the latest build of the controller from https://jenkins.opendaylight.org/controller/job/controller-merge/lastSuccessfulBuild/artifact/opendaylight/distribution/opendaylight/target/[here]. The source code of the OpenDaylight controller is in a directory called opendaylight. In this directory (the corresponding directory in the git repository is usually the distribution/opendaylight/target/distribution.opendaylight-0.1.0-SNAPSHOT-osgipackage/opendaylight).\r
+\r
+NOTE: The controller platform has specific core bundles, each of which export important services through Java interfaces. Here is a brief list of important ones that come in handy while developing network services. These are located at https://wiki.opendaylight.org/view/Controller_Projects%27_Modules/Bundles_and_Interfaces[Controller Projects' Modules, Bundles, and Interfaces].\r
+\r
+NOTE: For a list of files in OpenDaylight karaf, see https://wiki.opendaylight.org/view/Karaf_Distribution_Folder_and_File_Guide[Karaf Distribution Folder and File Guide].\r
+\r
+Apache Karaf is a small OSGi based runtime which provides a lightweight container onto which various components and applications can be deployed. It tends to be helpful to think of Karaf as providing an ecosystem for an application where various libraries and frameworks are collected and tested that they work well together, simplifying your runtime experience.\r
+\r
+There are two ways to start the controller in Karaf.\r
+\r
+. Run the command below to access the Karaf console:\r
+\r
+[literal]\r
+\r
+bin/karaf\r
+\r
+. Run the command below to start Karaf as a background task, accessing the console using SSH:\r
+\r
+[literal]\r
+\r
+bin/start\r
+\r
+SSH is listening on 8101 and the default username and password is karaf/karaf. Run the command below to access the console\r
+\r
+[literal]\r
+ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 8101 karaf@<controllerIP>\r
+\r
+To log out of the SSH shell, run the command below:\r
+\r
+[literal]\r
+shell: logout\r
+\r
+==== Installing or uninstalling controller features\r
+\r
+Features that are installed as part of the karaf-compatible-all integration job include the following files: \r
+\r
+* odl-restconf\r
+* odl-mdsal-apidocs\r
+* odl-integration-compatible-with-l2switch \r
+\r
+Before starting karaf, you can edit the file *etc/org.apache.karaf.features.cfg* to install additional features. Modify the line `featuresBoot=config,standard,region,package,kar,ssh,management` to be `featuresBoot=config,standard,region,package,kar,ssh,management,odl-restconf,odl-mdsal-apidocs, odl-integration-compatible-with-l2switch`\r
+\r
+\r
+\r
+=== Karaf CLI\r
+\r
+* To list only installed features, run the command: \r
+\r
+[literal]\r
+ feature:list -i \r
+ \r
+\r
+* Filter with grep\r
+\r
+[literal]\r
+feature:list | grep openflowplugin \r
+\r
+* List bundles loaded\r
+\r
+[literal]\r
+ bundle:list -s\r
+ \r
+List web endpoints\r
+\r
+[literal]\r
+web:list\r
+\r
+\r
+Uninstall a feature\r
+\r
+\r
+[literal]\r
+ feature:uninstall odl-l2switch-switch \r
+\r
+ \r
+=== Running the controller GUI\r
+\r
+\r
+. Navigate to http://controller-ip:8080 to open the web interface, then use the following credentials to log in:\r
+\r
+** *User*: admin\r
+\r
+** *Password*: admin\r
+\r
+\r
--- /dev/null
+== Welcome to the OpenDaylight project\r
+\r
+\r
+The Open Daylight Project is a collaborative open source project under the Linux foundation that aims to accelerate adoption of Software-Defined Networking (SDN) and create a solid foundation for Network Functions Virtualization (NFV) for a more transparent approach that fosters new innovation and reduces risk. Founded by industry leaders and open to all, the OpenDaylight community is developing a common, open SDN framework consisting of code and blueprints.\r
+\r
+\r
+=== OpenDaylight project scope\r
+\r
+The projects chosen by the Technical Steering Committee (TSC) are limited to the following areas:\r
+\r
+* The OpenDaylight controller\r
+\r
+* Software for forwarding elements\r
+\r
+* Southbound plugins to enable the controller to speak to the OpenDaylight supplied and other network elements\r
+\r
+* Northbound plugins to expose interfaces to those writing applications to the controller\r
+\r
+* Network services and applications intended to run on top of the controller, integration between the controller and other elements\r
+\r
+* Support projects such as tools, infrastructure, or testing\r
+\r
+* Plugins for inter-controller communication\r
+\r
+\r
+=== OpenDaylight project goals\r
+\r
+* *Code*: To create a robust, extensible, open source code base that covers the major common components required to build an SDN solution.\r
+\r
+* *Acceptance*: To get broad industry acceptance amongst vendors and users.\r
+\r
+* *Community*: To have a thriving and growing technical community contributing to the code base, using the code in commercial products, and adding value above, below and around. \r
+\r
+=== Additional information for the OpenDaylight project\r
+\r
+* For frequently asked questions about the OpenDaylight project, see the http://www.opendaylight.org/project/faq[FAQ].\r
+\r
+\r
+* You can join OpenDaylight as a user, developer, or as a member of the project. See the http://www.opendaylight.org/resources/getting-started-guide[ Getting Started with OpenDaylight].\r
+\r
+\r
+* Exhaustive information about OpenDaylight is available in the https://wiki.opendaylight.org/view/Main_Page[OpenDaylight Wiki].\r
+\r
+\r
+\r
+\r
--- /dev/null
+== Overview of RESTCONF\r
+\r
+NOTE: Important characteristics of RESTCONF are described below. For more information, see the http://www.ietf.org/archive/id/draft-bierman-netconf-restconf-04.txt[RESTCONF Protocol].\r
+\r
+* RESTCONF is a REST-like protocol that provides a programmatic interface over HTTP for accessing data defined in YANG, using the datastores defined in NETCONF.\r
+\r
+* RESTCONF is not intended to replace NETCONF, but rather provide an additional simplified interface that follows REST-like principles and is compatible with a resource-oriented device abstraction.\r
+\r
+* The RESTCONF protocol operates on a conceptual datastore defined with the YANG data modeling language. The server lists each YANG module it supports under “/restconf/modules” in the top-level API resource type, using a structure based on the YANG module capability URI format.\r
+\r
+* The conceptual datastore contents, data-model-specific operations and notification events are identified by the set of YANG module resources. All RESTCONF content identified as either a data resource, operation resource, or event stream resource is defined with the YANG language.\r
+\r
+* The classification of data as configuration or non-configuration is derived from the YANG “config” statement. Data ordering behavior is derived from the YANG “ordered-by” statement.\r
+\r
+* RESTCONF allows access to datastores located in the controller. There are two datastores\r
+*Config* that contains data inserted via the controller and *Operational* that contains data inserted via the network.\r
+\r
+* RESTCONF listens on port 8080 for HTTP requests\r
+\r
+* RESTCONF supports OPTIONS, GET, PUT, POST, DELETE operations.\r
+\r
+* Request and response data can be in XML or JSON format. XML has structure according to yang by XML-YANG and JSON by JSON-YANG.\r
+\r
+\r
+The NETCONF protocol defines configuration datastores and a set of Create, Retrieve, Update, Delete (CRUD) operations that can be used to access these datastores. For more information on NETCONF, see RFC6241.\r
+\r
+The YANG language defines the syntax and semantics of datastore content, operational data, protocol operations, and notification events. For more information on YANG, see RFC6020.\r
+\r
+The RESTCONF protocol uses HTTP methods to identify the CRUD operation requested for a particular resource. The following table shows how the RESTCONF operations relate to NETCONF protocol operations:\r
+\r
+\r
+=== RESTCONF in OpenDaylight\r
+\r
+Restconf allows access to datastores in the controller. There are two datastores:\r
+\r
+* Config: Contains data inserted via controller\r
+\r
+* Operational: Contains other data\r
+\r
+NOTE: Each request must start with URI /restconf. Restconf listens on port 8080 for HTTP requests.\r
+\r
+Restconf supports `OPTIONS`, `GET`, `PUT`, `POST`, and `DELETE` operations. Request and response data can either be in the XML or JSON format. XML structures according to yang are defined at: http://tools.ietf.org/html/rfc6020[XML-YANG]. JSON structures are defined at: http://tools.ietf.org/html/draft-lhotka-netmod-yang-json-02[JSON-YANG]. Data in the request must have a correctly set “Content-Type” field in the http header with the allowed value of the media type. The media type of the requested data has to be set in the “Accept” field. Get the media types for each resource by calling the OPTIONS operation. \r
+\r
+\r
+Most of the RESTCONF endpoints paths use Instance Identifier. <identifier> is used in the explanation of the operations. \r
+\r
+\r
+`<identifier>`\r
+\r
+\r
+* It must start with <moduleName>:<nodeName> where <moduleName> is a name of the module and <nodeName> is the name of a node in the module. It is sufficient to just use <nodeName> after <moduleName>:<nodeName>. Each <nodeName> has to be separated by /.\r
+\r
+\r
+* <nodeName> can represent a data node which is a list or container yang built-in type. If the data node is a list, there must be defined keys of the list behind the data node name for example, <nodeName>/<valueOfKey1>/<valueOfKey2>.\r
+\r
+\r
+* The format <moduleName>:<nodeName> has to be used in this case as well:\r
+Module A has node A1. Module B augments node A1 by adding node X. Module C augments node A1 by adding node X. Then for clarification it has to be known which node X is thought (e.g. C:X).\r
+\r
+\r
+For more details about encoding see: http://tools.ietf.org/html/draft-bierman-netconf-restconf-02#section-5.3.1[Restconf 02 - Encoding YANG Instance Identifiers in the Request URI].\r
+\r
+NOTE: A Node can be behind a mount point. In this case, the URI has to be in format <identifier>/yang-ext:mount/<identifier>. The first <identifier> is the path to a mount point and the second <identifier> is the path to a node behind the mount point. A URI can end in a mount point itself by using <identifier>/yang-ext:mount. For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf.\r
+\r
+NOTE: For more information on RESTCONF, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf.\r
+\r
+\r
+=== URLs exposed by RESTCONF in OpenDaylight\r
+\r
+* The RESTCONF API to access nodes in OpenDaylight inventory is http://<controller-ip>:8080/restconf/operational/opendaylight-inventory:nodes/\r
+\r
+* The RESTCONF API to access information of a particular node in OpenDaylight inventory is http://<controller-ip>:8080/restconf/operational/opendaylight-inventory:nodes/node/id [replace id by the actual node id]\r
+\r
+* The RESTCONF API to access OpenDaylight topology information is http://<controller-ip>:8080/restconf/operational/network-topology:network-topology/topology/flow:1\r
+\r
+=== RESTCONF Northbound APIs for OpenDaylight controller\r
+\r
+Yang models are used in the MD-SAL and in MD-SAL-based applications to define all APIs such as inter-component APIs, plugin APIs, northbound APIs, etc. Yang models are used to generate Java APIs at compile time with OpenDaylight Yang Tools and to render REST APIs at run time according to the RESTCONF specification. Plugins designed for MD-SAL define yang models for their northbound REST APIs, which are then exposed to applications via an MD-SAL RESTCONF adapter.\r
+\r
+\r
+image::SAL_nb_pugins.jpg[title="SAL Northbound Examples", alt="SAL Northbound Plugin Examples"]\r
+\r
+\r
+=== Writing a new application for OpenDaylight\r
+\r
+. Download the OpenDaylight VM and set up the controller. For more information, see the Installation Guide for the OpenDaylight controller.\r
+\r
+. Update the dependencies and services exported in the new bundle's pom.xml.\r
+\r
+. List dependencies imported and interfaces implemented in the module's activator.java.\r
+\r
+. Update set or unset bindings in the module's class so as to access other bundle objects.\r
+\r
+. Implement the interface functions to handle the async events or use other bundle objects to edit the state.\r
+\r
+. Add the required northbound REST API and associate with the web bundle.\r
+\r
+\r
+=== Creating a new northbound REST bundle\r
+\r
+\r
+The easiest way of introducing a new northbound REST API is to copy an existing one and making the relevant changes as below:\r
+\r
+. pom.xml – update the artifact-name , Web-ContextPath and dependencies.\r
+\r
+. enunciate.xml – update the defaultRestSubContext and the description.\r
+\r
+. src/main/java/…/*Northbound*.java – Rename/Update the request handler and the necessary logic as required.\r
+\r
+. src/main/test/… - Add necessary unit tests.\r
+\r
+\r
+. commons/northbound-integrationtest module - Add necessary integration tests.\r
+\r
+. Reference the bundle from the distribution assembly descriptor to be included in the distribution.\r
+\r
+\r
+\r
+\r
+\r
+\r
--- /dev/null
+== OpenDaylight controller REST reference and authentication\r
+\r
+You can locate the REST API reference information for each of the modules by navigating to the northbound module directories in your installation. The OpenDaylight Controller REST API contains the following modules. The associated module directory for the API reference content is listed:\r
+\r
+For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:REST_Reference_and_Authentication.\r
+\r
--- /dev/null
+=== Using Mininet\r
+\r
+Mininet creates a realistic virtual network, running real kernel, switch and application code, on a single machine (VM, cloud or native) with a single command and within a short time. Using Mininet, you can easily interact with your network using the Mininet CLI (and API), customize it, share it with others, or deploy it on real hardware, Mininet is useful for development, teaching, and research.\r
+\r
+Mininet is also a great way to develop, share, and experiment with OpenFlow and Software-Defined Networking systems.\r
+\r
+NOTE: To know more about Mininet, see http://mininet.org/walkthrough/[Mininet Walkthrough].\r
+\r
+To use Mininet for OpenDaylight, \r
+\r
+. Download http://mininet.github.com/download/[Mininet] . OpenDaylight controller is tested against the Mininet VM (Option 1). It has not been tested against other Mininet installation options.\r
+\r
+. Launch the Mininet VM with VirtualBox or another virtualization application.\r
+\r
+. Log on to the Mininet VM with the following credentials:\r
+\r
+*** *user*: mininet\r
+\r
+*** *password*: mininet\r
+\r
+. Determine the IP address of the server hosting the OpenDaylight controller, and use it to start a virtual network by running the following command:\r
+\r
+[literal]\r
+\r
+sudo mn --controller=remote,ip=controller-ip --topo tree,3\r
+\r
+Mininet connects to OpenDaylight controller and sets up a three-level tree topology.\r
+\r
+\r
+[literal]\r
+mininet@mininet-vm:~$ sudo mn --controller=remote,ip=172.16.102.161 --topo tree,3\r
+*** Creating network\r
+*** Adding controller\r
+*** Adding hosts:\r
+h1 h2 h3 h4 h5 h6 h7 h8 \r
+*** Adding switches:\r
+s1 s2 s3 s4 s5 s6 s7 \r
+*** Adding links:\r
+(h1, s3) (h2, s3) (h3, s4) (h4, s4) (h5, s6) (h6, s6) (h7, s7) (h8, s7) (s1, s2) (s1, s5) (s2, s3) (s2, s4) (s5, s6) (s5, s7) \r
+*** Configuring hosts \r
+h1 h2 h3 h4 h5 h6 h7 h8 \r
+*** Starting controller\r
+*** Starting 7 switches\r
+s1 s2 s3 s4 s5 s6 s7 \r
+*** Starting CLI:\r
+mininet>\r
+\r
+NOTE: See the http://mininet.github.com/walkthrough/Mininet[Mininet Walkthrough] for a more detailed explanation of Mininet configuration options. There is an appendix that explains how to configure Mininet to use a remote controller.\r
+\r
+=== Troubleshooting Mininet\r
+\r
+If you are running VirtualBox on the same host or desktop where the controller is running, and trying to start the virtual network on Mininet VM, the following error is displayed `"Unable to contact the remote controller at ...",` then the following steps resolves the issue:\r
+\r
+. In VirtualBox, go to File > Preferences > Network and make sure you have at least one interface defined as *Host-Only*. Lets say its name is `vboxnet0`.\r
+\r
+. In VirtualBox > Mininet VM > Settings > Network, check that the adapter is of type *Host-Only*, and is connected to the interface from item 1 `(vboxnet0)`.\r
+\r
+. On your host where the controller and VirtualBox run, run the `ifconfig` command to display all network interfaces on the machine.\r
+\r
+Search for the interface as in item 1 (`vboxnet0` in our example). Take the ip address specified (most probably 192.168.56.1 - default), and use that as the correct remote controller ip address when starting a VM in mininet as stated in the example above (--controller=remote,ip=192.168.56.1).\r
+\r
+. If you are still not able to connect, you might want to consider temporarily disabling firewall on the host running the controller (on Linux, for example, `iptables -F` will do the job).\r
+\r
+. Sometimes, the way you start the mininet is can be an issue. It does not give an error, but does not connect to the remote server either. Here is such an example:\r
+\r
+[literal]\r
+sudo mn --topo=tree,3 --mac --switch=ovsk --controller=remote, ip=192.168.16.10\r
+\r
+Here is the correct example:\r
+\r
+[literal]\r
+sudo mn --topo=tree,3 --mac --switch=ovsk --controller=remote,ip=192.168.16.10\r
+\r
+NOTE: The difference is the "SPACE" between "remote," and "ip".\r
+\r
+If Mininet crashes or if you lose your console from a remote connection, the switches remain configured in the database. Run the following command to clean up:\r
+\r
+[literal]\r
+\r
+$ sudo mn -c\r
+\r
+=== Resetting Mininet\r
+\r
+Here's a perl from the appendix mentioned above:\r
+\r
+If Mininet crashes or if you lose your console from a remote connection, the switches remain configured in the database and you'll want to clean them up.\r
+\r
+[literal]\r
+\r
+$ sudo mn -c\r
+\r
+\r
+\r
+=== Using the Simple Forwarding Application\r
+\r
+The OpenDaylight Controller includes an application called Simple Forwarding that lets you use the basic services for making forwarding decisions and install flows across all devices on the Openflow network. This application discovers the presence of a host via ARP message and installs dest-only /32 entries across all switches in the network, with the corresponding output ports toward the host.\r
+\r
+. With OpenDaylight Controller and Mininet running as described in previous sections, log into the web interface.\r
+\r
+image::Devices1.jpg[title="OpenDaylight GUI", alt="OpenDaylight GUI"]\r
+\r
+[start=2]\r
+. Drag and drop devices to organize the topology into its logical arrangement, then save the configuration.\r
+\r
+image::Devices2.jpg[title="Clicking Save", alt="Clicking Save"]\r
+\r
+\r
+[start=3]\r
+. Click the *Add Gateway IP Address* (shown in the figure above) and add the IP and subnet of `10.0.0.254/8`.\r
+\r
+\r
+image::GatewayIP.jpg[title="Adding the Gateway IP Address", alt="Adding the Gateway IP Address"]\r
+\r
+[start=4]\r
+. Confirm that hosts are now reachable from one another. On the console where Mininet is running, have one host ping another.\r
+\r
+[literal]\r
+\r
+mininet> h1 ping h7\r
+PING 10.0.0.7 (10.0.0.7) 56(84) bytes of data.\r
+64 bytes from 10.0.0.7: icmp_req=1 ttl=64 time=1.52 ms\r
+64 bytes from 10.0.0.7: icmp_req=2 ttl=64 time=0.054 ms\r
+64 bytes from 10.0.0.7: icmp_req=3 ttl=64 time=0.060 ms\r
+64 bytes from 10.0.0.7: icmp_req=4 ttl=64 time=0.052 ms\r
+--- 10.0.0.7 ping statistics ---\r
+4 packets transmitted, 4 received, 0% packet loss, time 2999ms\r
+rtt min/avg/max/mdev = 0.052/0.422/1.523/0.635 ms\r
+mininet> \r
+\r
+[start=5]\r
+. Click the *Troubleshooting* tab and then load the *Flows* for one of the switches.\r
+\r
+image::FlowStatitistics.jpg[title="Flow statistics", alt="Flow statistics"]\r
+\r
+\r
+[start=6]\r
+. View the *Ports* details.\r
+image::PortsStatistics.jpg[title="Port Statistics", alt="Port Statistics"]\r
+\r
+\r
+[start=7]\r
+. On the OSGI console, type `ss simple`. You will see that the Simple Forwarding application is ACTIVE.\r
+\r
+[literal]\r
+osgi> ss simple\r
+"Framework is launched."\r
+id State Bundle\r
+45 ACTIVE org.opendaylight.controller.samples.simpleforwarding_0.4.0.SNAPSHOT\r
+\r
+\r
+\r
Code Review / docs.git / commitdiff
