This is the content provided by Emmanuel Set and Divya Shetty.
Change-Id: Ia19ede0ab6d8b8413ba435a1717afe0301c1a6fb
Signed-off-by: Emmanuel Set <eset@cisco.com>
Signed-off-by: Divya Shetty <dshetty@brocade.com>
Signed-off-by: Mathieu Lemay <mlemay@inocybe.com>
[[bk-user-guide]]
= OpenDaylight User Guide
-:docinfo:
+== Table of Contents
-[dedication]
-Example Dedication
-------------------
-Optional dedication.
+link:ch-introduction.adoc[OpenDaylight Controller Overview]
-This document is an AsciiDoc book skeleton containing briefly
-annotated example elements plus a couple of example index entries and
-footnotes.
+link:dlux-userguide.adoc[Using the OpenDaylight User Interface (DLUX)]
-Books are normally used to generate DocBook markup and the titles of
-the preface, appendix, bibliography, glossary and index sections are
-significant ('specialsections').
-
-
-[preface]
-Example Preface
----------------
-Optional preface.
-
-Preface Sub-section
-~~~~~~~~~~~~~~~~~~~
-Preface sub-section body.
-
-//////////////////////////
-Please note and leave the blank line between include statements here.
-
-It is a defensive measure to prevent individual projects' .adoc files
-from eating the next section if they forget to leave a blank line at
-the end of their file.
-//////////////////////////
-include::addons/aaa.adoc[]
-
-include::addons/bgpcep.adoc[]
-
-include::addons/defense4all.adoc[]
-
-include::addons/groupbasedpolicy.adoc[]
-
-include::addons/l2switch.adoc[]
-
-include::addons/lispflow.adoc[]
-
-include::addons/ovsdb.adoc[]
-
-include::addons/pcmm.adoc[]
-
-include::addons/plugin2oc.adoc[]
-
-include::addons/sfc.adoc[]
-
-include::addons/snbi.adoc[]
-
-include::addons/snmp4sdn.adoc[]
-
-include::addons/vtn.adoc[]
-
-include::addons/yangtools.adoc[]
-
-:numbered!:
-
-[appendix]
-Example Appendix
-----------------
-One or more optional appendixes go here at section level 1.
-
-Appendix Sub-section
-~~~~~~~~~~~~~~~~~~~
-Sub-section body.
-
-
-[glossary]
-Example Glossary
-----------------
-Glossaries are optional. Glossaries entries are an example of a style
-of AsciiDoc labeled lists.
-
-[glossary]
-A glossary term::
- The corresponding (indented) definition.
-
-A second glossary term::
- The corresponding (indented) definition.
-
-
-[colophon]
-Example Colophon
-----------------
-Text at the end of a book describing facts about its production.
-
-
-[index]
-Example Index
--------------
-////////////////////////////////////////////////////////////////
-The index is normally left completely empty, it's contents being
-generated automatically by the DocBook toolchain.
-////////////////////////////////////////////////////////////////
+link:ch-clustering.adoc[Setting Up Clustering on an OpenDaylight Controller]
+link:ch-xsql-commands.adoc[Running XSQL Console Commands and Queries]
\ No newline at end of file
--- /dev/null
+== Setting Up Clustering on an OpenDaylight Controller
+
+* <<Clustering Overview>>
+* <<Single Node Clustering>>
+* <<Multiple Node Clustering>>
+** <<Deployment Considerations>>
+** <<Setting Up a Multiple Node Cluster>>
+*** <<Enabling HA on a Multiple Node Cluster>>
+
+=== Clustering Overview
+
+Clustering is a mechanism that enables multiple processes and programs to work together as one entity. For example, when you go to google.com and search for something, it may seem like your search request is processed by only one web server. In reality, your search request is processed by thousands of web servers connected in a cluster. Similarly, you can have multiple instances of the OpenDaylight controller working together as one entity. There are a number of uses for clustering:
+
+* Scaling: If you have multiple controllers running, you can potentially do more work with or store more data on those controllers if they are clustered. You can also break up your data into smaller chunks (known as shards) and either distribute that data across the cluster or perform certain operations on certain members of the cluster.
+
+* High Availability: If you have multiple controllers running and one of them crashes, you would still have the other instances working and available.
+
+* Data Persistence: You will not lose any data gathered by your controller after a manual restart or a crash.
+
+The following sections describe how to set up clustering on both individual and multiple OpenDaylight controllers.
+
+=== Single Node Clustering
+To enable clustering on a single OpenDaylight controller, do the following:
+
+'''
+
+. Download and unzip a base controller distribution. You must use the new openflow plugin, so download a distribution where the new openflow plugin is either the default or can be enabled.
+. Navigate to the _<Karaf-distribution-location>_/bin directory.
+. Run Karaf: *./karaf*
+. Install the clustering feature: *feature:install odl-mdsal-clustering*
+. If you are using the integration distribution of Karaf, you should also install the open flow plugin flow services: *feature:install odl-openflowplugin-flow-services*
+. Install the Jolokia bundle: *install -s mvn:org.jolokia/jolokia-osgi/1.1.5*
+
+'''
+
+After enabling the DistributedDataStore feature in a single instance, you can access the following features:
+
+* Data Sharding: The in-memory MD-SAL tree is broken up into a number of smaller sub-trees (inventory, topology, and default).
+* Data Persistence: All of the data available on defined data shards is stored on a disk. By restarting the controller, you can use the persisted data to reinstate those shards to their previous state.
+
+=== Multiple Node Clustering
+
+The following sections describe how to set up multiple node clusters in OpenDaylight.
+
+==== Deployment Considerations
+
+Here is some information to keep in mind when you implement clustering:
+
+* When setting up a cluster with multiple nodes, we recommend that you do so with a minimum of three machines. You can set up with a cluster with just two nodes. However, if one of those two nodes go down, the controller will no longer be operational.
+
+* Every device that belongs to a cluster needs to have an identifier. For this purpose, OpenDaylight uses the node’s role. After you define the first node’s role as _member-1_ in the akka.conf file, OpenDaylight uses _member-1_ to identify that node.
+
+* Data shards are used to house all or a certain segment of a module’s data. For example, one shard can contain all of a module’s inventory data while another shard contains all of it’s topology data. If you do not specify a module in the modules.conf file and do not specify a shard in module-shards.conf, then (by default) all the data is places onto the default shard (which must also be defined in module-shards.conf file). Each shard has replicas configured, and the module-shards.conf file is where you can specify where these replicas reside.
+
+* Say you have a three node cluster on which HA is enabled. A replica of every defined data shard must be running on all three cluster nodes. This is because OpenDaylight’s clustering implementation requires a majority of the defined shard replicas to be running in order to function. If you only define data shard replicas on two of the cluster nodes and one of those nodes goes down, the corresponding data shards will not function.
+
+* If you have a three node cluster and have defined replicas for a data shard on each of those nodes, that shard will still function even if only two of the cluster nodes are running. Note that if one of those two nodes go down, your controller will no longer be operational.
+
+*What considerations need to be made when setting the seed nodes for each member? Why are we referring to multiple seed nodes when you set only one IP address? Can you set multiple seed nodes for functional testing?*
+
+We recommend that you have multiple seed nodes configured. After a cluster member is started, it sends a message to all of its seed nodes. The cluster member then sends a join command to the first seed node that responds. If none of its seed nodes reply, the cluster member repeats this process until it successfully establishes a connection or it is shutdown.
+
+*What happens after one node becomes unreachable? Do the other two nodes function normally? When the first node reconnects, does it automatically synchronize with the other nodes?*
+
+After a node becomes unreachable, it remains down for configurable period of time (10 seconds, by default). Once a node goes down, you need to restart it so that it can rejoin the cluster. Once a restarted node joins a cluster, it will synchronize with the lead node automatically.
+
+*Can you run a two node cluster for functional testing?*
+
+For functional testing, yes. For HA testing, you need to run all three nodes.
+
+==== Setting Up a Multiple Node Cluster
+
+To run an OpenDaylight controller in a three node cluster, do the following:
+
+'''
+
+. Determine the three machines that will make up the cluster and copy the controller distribution to each of those machines.
+. Unzip the controller distribution.
+. Navigate to the _<Karaf-distribution-location>_/bin directory.
+. Run Karaf: *./karaf*
+. Install the clustering feature: *feature:install odl-mdsal-clustering*
+
+NOTE: To run clustering, you must install the odl-mdsal-clustering feature on each of your nodes.
+
+[start=6]
+. If you are using the integration distribution of Karaf, you should also install the open flow plugin flow services: *feature:install odl-openflowplugin-flow-services*
+. Install the Jolokia bundle: *install -s mvn:org.jolokia/jolokia-osgi/1.1.5*
+. On each node, open the following .conf files:
+
+* configuration/initial/akka.conf
+* configuration/initial/module-shards.conf
+
+. In each configuration file, make the following changes:
+
+.. Find every instance of the following lines and replace _127.0.0.1_ with the hostname or IP address of the machine on which the controller will run:
+
+ netty.tcp {
+ hostname = "127.0.0.1"
+
+NOTE: The value you need to specify will be different for each node in the cluster.
+
+[start=2]
+.. Find the following lines and replace _127.0.0.1_ with the hostname or IP address of any of the machines that will be part of the cluster:
+
+ cluster {
+ seed-nodes = ["akka.tcp://opendaylight-cluster-data@127.0.0.1:2550"]
+
+.. Find the following section and specify the role for each member node. For example, you could assign the first node with the _member-1_ role, the second node with the _member-2_ role, and the third node with the _member-3_ role.
+
+
+ roles = [
+ "member-1"
+ ]
+
+.. Open the configuration/initial/module-shards.conf file and update the items listed in the following section so that the replicas match roles defined in this host’s akka.conf file.
+
+ replicas = [
+ "member-1"
+ ]
+
+For reference, view a sample akka.conf file here: https://gist.github.com/moizr/88f4bd4ac2b03cfa45f0
+
+[start=5]
+.. Run the following commands on each of your cluster’s nodes:
+
+* *JAVA_MAX_MEM=4G JAVA_MAX_PERM_MEM=512m ./karaf*
+
+* *JAVA_MAX_MEM=4G JAVA_MAX_PERM_MEM=512m ./karaf*
+
+* *JAVA_MAX_MEM=4G JAVA_MAX_PERM_MEM=512m ./karaf*
+
+'''
+
+The OpenDaylight controller can now run in a three node cluster. Use any of the three member nodes to access the data residing in the datastore.
+
+Say you want to view information about shard designated as _member-1_ on a node. To do so, query the shard’s data by making the following HTTP request:
+
+'''
+
+*GET http://_<host>_:8181/jolokia/read/org.opendaylight.controller:Category=Shards,name=member-1-shard-inventory-config,type=DistributedConfigDatastore*
+
+NOTE: If prompted, enter _admin_ as both the username and password.
+
+'''
+
+This request should return the following information:
+
+ {
+ "timestamp": 1410524741,
+ "status": 200,
+ "request": {
+ "mbean": "org.opendaylight.controller:Category=Shards,name=member-1-shard-inventory-config,type=DistributedConfigDatastore",
+ "type": "read"
+ },
+ "value": {
+ "ReadWriteTransactionCount": 0,
+ "LastLogIndex": -1,
+ "MaxNotificationMgrListenerQueueSize": 1000,
+ "ReadOnlyTransactionCount": 0,
+ "LastLogTerm": -1,
+ "CommitIndex": -1,
+ "CurrentTerm": 1,
+ "FailedReadTransactionsCount": 0,
+ "Leader": "member-1-shard-inventory-config",
+ "ShardName": "member-1-shard-inventory-config",
+ "DataStoreExecutorStats": {
+ "activeThreadCount": 0,
+ "largestQueueSize": 0,
+ "currentThreadPoolSize": 1,
+ "maxThreadPoolSize": 1,
+ "totalTaskCount": 1,
+ "largestThreadPoolSize": 1,
+ "currentQueueSize": 0,
+ "completedTaskCount": 1,
+ "rejectedTaskCount": 0,
+ "maxQueueSize": 5000
+ },
+ "FailedTransactionsCount": 0,
+ "CommittedTransactionsCount": 0,
+ "NotificationMgrExecutorStats": {
+ "activeThreadCount": 0,
+ "largestQueueSize": 0,
+ "currentThreadPoolSize": 0,
+ "maxThreadPoolSize": 20,
+ "totalTaskCount": 0,
+ "largestThreadPoolSize": 0,
+ "currentQueueSize": 0,
+ "completedTaskCount": 0,
+ "rejectedTaskCount": 0,
+ "maxQueueSize": 1000
+ },
+ "LastApplied": -1,
+ "AbortTransactionsCount": 0,
+ "WriteOnlyTransactionCount": 0,
+ "LastCommittedTransactionTime": "1969-12-31 16:00:00.000",
+ "RaftState": "Leader",
+ "CurrentNotificationMgrListenerQueueStats": []
+ }
+ }
+
+The key thing here is the name of the shard. Shard names are structured as follows:
+
+_<member-name>_-shard-_<shard-name-as-per-configuration>_-_<store-type>_
+
+Here are a couple sample data short names:
+
+* member-1-shard-topology-config
+* member-2-shard-default-operational
+
+===== Enabling HA on a Multiple Node Cluster
+
+To enable HA in a three node cluster:
+
+'''
+
+. Open the configuration/initial/module-shards.conf file on each cluster node.
+. Add _member-2_ and _member-3_ to the replica list for each data shard.
+. Restart all of the nodes. The nodes should automatically sync up with member-1. After some time, the cluster should be ready for operation.
+
+'''
+
+When HA is enabled, you must have at least three replicas of every shard. Each node’s configuration files should look something like this:
+
+ module-shards = [
+ {
+ name = "default"
+ shards = [
+ {
+ name="default"
+ replicas = [
+ "member-1",
+ "member-2",
+ "member-3"
+ ]
+ }
+ ]
+ },
+ {
+ name = "topology"
+ shards = [
+ {
+ name="topology"
+ replicas = [
+ "member-1",
+ "member-2",
+ "member-3"
+ ]
+ }
+ ]
+ },
+ {
+ name = "inventory"
+ shards = [
+ {
+ name="inventory"
+ replicas = [
+ "member-1",
+ "member-2",
+ "member-3"
+ ]
+ }
+ ]
+ },
+ {
+ name = "toaster"
+ shards = [
+ {
+ name="toaster"
+ replicas = [
+ "member-1",
+ "member-2",
+ "member-3"
+ ]
+ }
+ ]
+ }
+ ]
+
+When HA is enabled on multiple nodes, shards will replicate the data for those nodes. Whenever the lead replica on a data shard is brought down, another replica takes its place. As a result, the cluster should remain available. To determine which replica is acting as the lead on a data shard, make an HTTP request to obtain the information for a data shard on any of the nodes. The resulting information will indicate which replica is acting as the lead.
+
--- /dev/null
+== OpenDaylight Controller Overview
+
+The OpenDaylight controller is JVM software and can be run from any operating system and hardware as long as it supports Java. The controller is an implementation of the Software Defined Network (SDN) concept and makes use of the following tools:
+
+* *Maven*: OpenDaylight uses Maven for easier build automation. Maven uses pom.xml (Project Object Model) to script the dependencies between bundle and also to describe what bundles to load and start.
+
+* *OSGi*: This framework is the back-end of OpenDaylight as it allows dynamically loading bundles and packages JAR files, and binding bundles together for exchanging information.
+* *JAVA interfaces*: Java interfaces are used for event listening, specifications, and forming patterns. This is the main way in which specific bundles implement call-back functions for events and also to indicate awareness of specific state.
+* *REST APIs*: These are northbound APIs such as topology manager, host tracker, flow programmer, static routing, and so on.
+
+The controller exposes open northbound APIs which are used by applications. The OSGi framework and bidirectional REST are supported for the northbound APIs. The OSGi framework is used for applications that run in the same address space as the controller while the REST (web-based) API is used for applications that do not run in the same address space (or even the same system) as the controller. The business logic and algorithms reside in the applications. These applications use the controller to gather network intelligence, run its algorithm to do analytics, and then orchestrate the new rules throughout the network.
+
+On the southbound, multiple protocols are supported as plugins, e.g. OpenFlow 1.0, OpenFlow 1.3, BGP-LS, and so on. The OpenDaylight controller starts with an OpenFlow 1.0 southbound plugin. Other OpenDaylight contributors begin adding to the controller code. These modules are linked dynamically into a *Service Abstraction Layer* (SAL).
+
+The SAL exposes services to which the modules north of it are written. The SAL figures out how to fulfill the requested service irrespective of the underlying protocol used between the controller and the network devices. This provides investment protection to the applications as OpenFlow and other protocols evolve over time. For the controller to control devices in its domain, it needs to know about the devices, their capabilities, reachability, and so on. This information is stored and managed by the *Topology Manager*. The other components like ARP handler, Host Tracker, Device Manager, and Switch Manager help in generating the topology database for the Topology Manager.
+
+For a more detailed overview of the OpenDaylight controller, see the _OpenDaylight Developer Guide_.
\ No newline at end of file
--- /dev/null
+== Running XSQL Console Commands and Queries
+
+* <<XSQL Overview>>
+* <<Installing XSQL>>
+* <<XSQL Console Commands>>
+* <<XSQL Queries>>
+** <<Example: skip Criteria Operator>>
+
+=== XSQL Overview
+
+XSQL is an XML-based query language that describes simple stored procedures which parse XML data, query or update database tables, and compose XML output. It allows you to query tree models as if they were a sequential database. For example, you could run a query that lists all of the ports configured on a particular module and their attributes.
+
+The following sections will cover the XSQL installation process, supported XSQL commands, and the proper way to structure queries.
+
+=== Installing XSQL
+
+Before you can run commands from the XSQL console, you must first install XSQL onto your system:
+
+'''
+
+. Navigate to the directory in which you unzipped the OpenDaylight source files.
+. Start Karaf: *./karaf*
+. Install XSQL: *feature:install odl-mdsal-xsql*
+
+'''
+
+=== XSQL Console Commands
+
+When entering a command in the XSQL console, structure it as follows: *odl:xsql* _<XSQL command>_
+
+The following table describes the commands supported in the OpenDaylight Helium release.
+
+.Supported XSQL Console Commands
+[cols=\u201c2*\u201d]
+|==============================================
+| *Command* | *Description*
+| *r* | Repeats the last command you executed.
+| *list vtables* | Lists the schema node containers that are currently installed. Whenever an OpenDaylight module is installed, its YANG model is placed in the Schema Context. At that point, the XSQL receives a notification, confirms that the module’s YANG model resides in the Schema Context, and then maps the model to XSQL by setting up the necessary vtables and vfields. This command is useful when you need to determine vtable information for a query.
+| *list vfields* _<vtable name>_ | Lists the vfields present in a specific vtable. This command is useful when you need to determine vfields information for a query.
+| *jdbc* _<ip address>_ | When the ODL server is behind a firewall, and the JDBC client cannot connect to the JDBC server, run this command to start the client as if it was a server and establish a connection.
+| *exit* | Closes the console.
+| *tocsv* | Enables/disables the forwarding of query output as a .csv file.
+| *filename* _<filename>_ | Specifies the .tocsv file to which query data is exported. If you do not specify a value for this option when the toccsv option is enabled, the filename for the query data file is generated automatically.
+|==============================================
+
+=== XSQL Queries
+
+Using the information provided by the *list vtables* and *list vfields* _<vtable name>_ commands, you can run a query to extract information that meets the criteria you specify. Any query you run should be structured as follows:
+
+*select* _<vfields you want to search for, separated by a comma and a space>_ *from* _<vtables you want to search in, separated by a comma and a space>_ *where* _<criteria>_ **’**_<criteria operator>_**’****;**
+
+For example, say you want to search the nodes/node.ID field in the nodes/node-connector table and find every instance of the Hardware-Address object that contains _BA_ in its text string. To do so, you would enter the following query:\r*Select nodes/node.ID from nodes/node-connector where Hardware-Address like ’%BA%’;*\r
+
+The following criteria operators are supported:
+
+.Supported XSQL Query Criteria Operators
+[cols=\u201c2*\u201d]
+|==============================================
+| *Criteria Operators* | *Description*
+| *=* | Lists results that equal the value you specify.\r| *!=* | Lists results that do not equal the value you specify.\r| *like* | Lists results that contain the substring you specify. For example, if you specify *like %BC%*, every string that contains that particular substring is displayed.
+| *<* | Lists results that are less than the value you specify.\r| *>* | Lists results that are more than the value you specify.\r| *and* | Lists results that match both values you specify.\r| *or* | Lists results that match either of the two values you specify.\r| *>=* | Lists results that are more than or equal to the value you specify.\r| *<=* | Lists results that are less than or equal to the value you specify.\r| *is null* | Lists results for which no value is assigned.\r| *not null* | Lists results for which any value is assigned.\r| *skip* | Use this operator to list matching results from a child node, even if its parent node does not meet the specified criteria. See the following example for more information.
+|==============================================
+
+==== Example: skip Criteria Operator
+
+Say you are looking at the following structure and want to determine all of the ports that belong to a YY type module:
+
+* Network Element 1
+** Module 1, Type XX
+*** Module 1.1, Type YY
+**** Port 1
+**** Port 2
+** Module 2, Type YY
+*** Port 1
+*** Port 2
+
+If you specify *Module.Type=’YY’* in your query criteria, the ports associated with module 1.1 will not be returned since its parent module is type XX. Instead, enter *Module.Type=’YY’ or skip Module!=’YY’*. This tells XSQL to disregard any parent module data that does not meet the type YY criteria and collect results for any matching child modules. In this example, you are instructing the query to skip module 1 and collect the relevant data from module 1.1.
+
--- /dev/null
+== Using the OpenDaylight User Interface (DLUX)
+
+* <<Getting Started with DLUX>>
+* <<Logging In>>
+* <<Working with DLUX>>
+* <<Viewing Network Statistics>>
+* <<Viewing Network Topology>>
+* <<Interacting with the Open Daylight Controller (ODL)>>
+
+
+This section introduces you to the OpenDaylight User Experience (DLUX) application. DLUX is an openflow network management application for Opendaylight controller. For detailed information about Opendaylight overview and architecture, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Overview[Opendaylight Overview], https://wiki.opendaylight.org/view/OpenDaylight_Controller:Architectural_Framework[Opendaylight Architecture]. +
+
+OpendaylightController has two interfaces namely: +
+
+* AD-SAL
+* MD-SAL
+
+Controller receives information from the various https://wiki.opendaylight.org/view/File:ODL-Helium-dependency.png[interdependent modules] through the SAL services. For more information about the SAL services available, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:SAL[SAL Services].
+DLUX also uses the SAL services to obtain network related information and use it to provide network management capabilities.
+
+=== Getting Started with DLUX
+
+You can either use DLUX as a stand-alone plug-in or integrate with the Opendaylight controller. +
+
+To install DLUX as a standalone application see https://wiki.opendaylight.org/view/OpenDaylight_DLUX:Setup_and_Run[OpenDaylight DLUX:Setup and Run]. +
+
+To integrate with Opendaylight Controller you must enable DLUX Karaf feature. You can enable adsal, md sal and various other bundles within Karaf depending on the features you would like to access using DLUX.
+Each feature can be enabled or disabled separately.
+
+IMPORTANT: Ensure that you have created a topology and enabled MD-SAL feature in the Karaf distribution before you use DLUX for network management.
+
+For more information about enabling the Karaf features for DLUX, see https://wiki.opendaylight.org/view/OpenDaylight_DLUX:DLUX_Karaf_Feature[OpenDaylight DLUX:DLUX Karaf Feature].
+
+=== Logging In
+
+To log in to DLUX, after installing the application:
+
+'''
+
+
+. Open a browser and enter the login URL. If you have installed DLUX as a stand-alone, then the login URL is http://localhost:9000/DLUX/index.html. However if you have deployed DLUX with Karaf, then the login URL is http://<your IP>:8181/dlux/index.html.
+NOTE: Ensure that you use the port applicable for the DLUX installation type. *local host* is the IP address of the machine where the application us installed. +
+
+. Login to the application with user ID and password credentials as *admin*.
+NOTE: admin is the only user type available for DLUX in this release.
+
+'''
+
+=== Working with DLUX
+
+After you login to DLUX, you will see all the modules that are available for DLUX in the left pane. However the modules disappear if the features are not enabled in the Karaf distribution.
+
+To get a complete DLUX feature list, install restconf, odl l2 switch, and switch while you start the DLUX distribution. For more information about enabling features on DLUX, see https://wiki.opendaylight.org/view/OpenDaylight_DLUX:DLUX_Karaf_Feature[OpenDaylight DLUX:DLUX Karaf Feature].
+
+.DLUX Modules +
+
+image::DLUX-login.PNG["DLUX Page"]
+
+
+Modules that use the MD SAL based apis are : +
+
+* Nodes
+* Yang UI
+* Topology
+
+Modules that use the AD SAL based apis are: +
+
+* Connection manager
+* Container
+* Network
+* Flows
+
+NOTE: DLUX enables only those modules, whose APIs are responding. If you enable just the MD-SAL in beginning and then start dlux, only MD-SAL related tabs will be visible. While using the GUI if you enable AD-SAL karaf features, those tabs will appear automatically.
+
+To view features that are enabled:
+
+'''
+
+. Right click on the DLUX page.
+. Select *Inspect Element* and then click *Network*. +
+ A table that contains the list of features and if they are available in the DLUX distribution. The features that are not enabled is highlighted with red font and has status *404 Not Found*.
+
+'''
+
+=== Viewing Network Statistics
+
+The *Nodes* module on the left pane enables you to view the network statistics and port information for the switches in the network. +
+
+To use the *Nodes* module:
+
+'''
+
+. Select *Nodes* on the left pane.
+ The right pane displays atable that lists all the nodes, node connectors and the statistics.
+. Enter a node ID in the *Search Nodes* tab to search by node connectors.
+. Click on the *Node Connector* number to view details such as port ID, port name, number of ports per switch, MAC Address, and so on.
+. Click *Flows* in the Statistics column to view Flow Table Statistics for the particular node like table ID, packet match, active flows and so on.
+. Click *Node Connectors* to view Node Connector Statistics for the particular node ID.
+
+'''
+
+=== Viewing Network Topology
+
+The Topology tab displays a graphical representation of network topology created.
+
+NOTE: DLUX UI does not provide ability to add topology information. The Topology should be created using an open flow plugin. Controller stores this information in the database and displays on the DLUX page, when the you connect to the controller using openflow.
+
+To view network topology:
+
+'''
+
+. Select *Topology* on the left pane. You will view the graphical representation on the right pane.
+ In the diagram blue boxes represent the switches, the black represents the hosts available, and lines represents how switches are connected.
+. Hover your mouse on hosts,links, or switches to view source and destination ports.
+. Zoom in and zoom out using mouse scroll to verify topology for huge topologies.
+
+'''
+
+.Topology Module +
+
+image::DLUX-topology.PNG["DLUX Topology Page"]
+
+=== Interacting with the Open Daylight Controller (ODL)
+
+The *Yang UI* module enables you to interact with the ODL. For more information about Yang Tools, see https://wiki.opendaylight.org/view/YANG_Tools:Main [YANG_Tools].
+
+image::DLUX-yang-ui-screen.PNG["DLUX Yang UI Page"]
+
+To use Yang UI:
+
+'''
+
+. Select *Yang UI* on the left pane. The right pane is divided in two parts.
+
+. The top part displays a tree of APIs and subAPIs and buttons to call possible functions (GET, POST, PUT, DELETE, …). Not every subAPIs can call every function.
+ For example, subAPIs “operational” have GET functionality only.
+ Inputs can be filled from ODL when existing data from ODL is displayed or can be filled by user on the page and sent to ODL. +
+ +
+ Buttons under the API tree are variable. It depends on subAPI specifications. Common buttons are: +
+ * GET to get data from ODL,
+ * PUT and POST for sending data to ODL for saving
+ * DELETE for sending data to ODL for deleting. +
+ You must specify the xpath for all these operations. This path is displayed in the same row before buttons and it can include text inputs for specific path elements identifiers. +
++
+image::DLUX-yang-api-specification.PNG["DLUX Yang UI API Specification Page"]
+
+. The bottom part of the right pane displays inputs according to the chosen subAPI. Every subAPI is represented by list elements of list statement. It is possible to have a many list elements of one list. +
+ +
+ For example, a device can store multiple flows. In this case “flow” is name of the list and every list element is different by a key value. List element of list can obtain other lists.
+ Every list element has a list name, a key name and its value, and a button for removing this list element. Usually the key of the list statement obtains an ID.
+ Inputs can be filled from ODL using GET button from xpath part, or can be filled by user on the page and sent to ODL. +
++
+image::DLUX-yang-sub-api-screen.PNG["DLUX Yang UI Sub API Specification Page"]
+
+. Click *Show Preview* button under API tree to display request that will be sent to ODL.
+ A pane is displayed on the right side with text of request when some input is filled.
+
+'''
+
+==== Displaying Topology on the *Yang UI*
+
+To display topology:
+
+'''
+
+. Select subAPI network-topology <topology revision number> -> operational -> network-topology.
+. Get data from ODL by clicking on the “GET” button.
+. Click *Display Topology*.
+
+image::DLUX-yang-topology.PNG["DLUX Yang Topology Page"]
+
+'''
+
+==== Configuring List Elements on the *Yang UI*
+
+The list is displayed like tree structure with possibility to expand or collapse by the arrow before name of the list. To configure list elements on the Yang UI:
+
+'''
+
+. To add a new list element with empty inputs use the plus icon-button **+** that is provided after list name. When some list element is added, button with his name and key value is displayed. +
+. To remove several list elements, use the *X* button that is provided after every list element.
++
+image::DLUX-yang-list elements.PNG[DLUX list buttons]
+. Key of list is one or more inputs, which are used like identifier of list element. All list elements in one list must have different key values. If some elements has the same key values, the new warning icon *!* is displayed near their name buttons.
++
+image::DLUX-yang-list-warning.PNG[DLUX list buttons]
+. When the list obtains at least one list element, after *+* icon is icon for selecting the list element displayed. You can choose one of them by clicking the icon. The name button of the list element and name buttons of its neighbours will be displayed in the row list. You can can forward or backward row list of list elements name buttons by clicking on the arrow button on the end of row.
++
+image::DLUX-yang-list-button1.PNG[DLUX list buttons]
+
+'''
Code Review / docs.git / commitdiff
