-== 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>>
+== Setting Up Clustering
=== 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.
+Clustering is a mechanism that enables multiple processes and programs to work
+together as one entity. For example, when you search for something on
+google.com, it may seem like your search request is processed by only one web
+server. In reality, your search request is processed by may web servers
+connected in a cluster. Similarly, you can have multiple instances of
+OpenDaylight working together as one entity.
+
+Advantages of clustering are:
+
+* Scaling: If you have multiple instances of OpenDaylight running, you can
+ potentially do more work and store more data than you could with only one
+ instance. You can also break up your data into smaller chunks (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 instances of OpenDaylight running and
+ one of them crashes, you will still have the other instances working and
+ available.
+* Data Persistence: You will not lose any data stored in OpenDaylight after a
+ manual restart or a crash.
+
+The following sections describe how to set up clustering on both individual and
+multiple OpenDaylight instances.
=== 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*
+To enable clustering on a single instance of OpenDaylight, perform the
+following steps:
-'''
+. Download, install, and run OpenDaylight as
+ <<_getting_and_installing_opendaylight_lithium,described above>>
+. Install the clustering feature:
++
+ feature:install odl-mdsal-clustering
-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.
+NOTE: This will enabled the cluster-ready version of the MD-SAL data store, but
+ will not actually create a cluster of multiple instances. The result is
+ that you will get data persistence, but not the scaling or high
+ availability advantages.
=== Multiple Node Clustering
==== 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.
+To implement clustering, the deployment considerations are as follows:
+
+* To set up a cluster with multiple nodes, we recommend that you use a minimum
+ of three machines. You can set up a cluster with just two nodes. However, if
+ one of the two nodes fail, the cluster will not be operational.
++
+NOTE: This is because clustering in OpenDaylight requires a majority of the
+ nodes to be up and one node cannot be a majority of two nodes.
++
+* Every device that belongs to a cluster needs to have an identifier.
+ OpenDaylight uses the node's +role+ for this purpose. 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 contain all or a certain segment of a OpenDaylight's
+ MD-SAL datastore. For example, one shard can contain all the inventory data
+ while another shard contains all of the 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 placed in
+the default shard (which must also be defined in +module-shards.conf+ file).
+Each shard has replicas configured. You can specify the details of where the
+replicas reside in +module-shards.conf+ file.
+
+* If you have a three node cluster and would like to be able to tolerate any
+ single node crashing, a replica of every defined data shard must be running
+ on all three cluster nodes.
++
+NOTE: This is because OpenDaylight's clustering implementation requires a
+ majority of the defined shard replicas to be running in order to
+ function. If you 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 remaining two nodes
+ goes down, the shard will not be operational.
+
+* It is recommended 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 shut down.
+
+* After a node is 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.
==== Setting Up a Multiple Node Cluster
-To run an OpenDaylight controller in a three node cluster, do the following:
-
-'''
+To run OpenDaylight in a three node cluster, perform 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
+First, determine the three machines that will make up the cluster. After that,
+do the following on each machine:
+. Copy the OpenDaylight distribution zip file to the machine.
+. Unzip the distribution.
+. 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:
-
+.. Find every instance of the following lines and replace _127.0.0.1_ with the
+ hostname or IP address of the machine on which this file resides and
+ OpenDaylight 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:
-
++
+NOTE: The value you need to specify will be different for each node in the
+ cluster.
++
+.. 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.
-
-
++
+.. Find the following section and specify the role for each member node. Here
+ we 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.
-
++
+NOTE: This step should use a different role on each node.
++
+.. Open the configuration/initial/module-shards.conf file and update the
+ replicas so that each shard is replicated to all three nodes:
++
replicas = [
- "member-1"
+ "member-1",
+ "member-2",
+ "member-3"
]
-
-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.
-
++
+For reference, view a sample config files <<_sample_config_files,below>>.
++
+. Move into the +<karaf-distribution-directory>/bin+ directory.
+. Run the following command:
++
+ JAVA_MAX_MEM=4G JAVA_MAX_PERM_MEM=512m ./karaf
++
+. Enable clustering by running the following command at the Karaf command line:
++
+ feature:install odl-mdsal-clustering
+
+OpenDaylight should now be running in a three node cluster. You can use any of
+the three member nodes to access the data residing in the datastore.
+
+// This doesn't work at the moment. The install -s command fails.
+//===== Debugging Clustering
+//
+//To debug clustering first install Jolokia by entering the following command:
+//
+// install -s mvn:org.jolokia/jolokia-osgi/1.1.5
+//
+//After that, you can view specific information about the cluster. For example,
+//to view information about shard designated as _member-1_ on a node, query the
+//shard's data by sending 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 your credentials for OpenDaylight. The default
+// credentials are a username and password of _admin_.
+//
+//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 information 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
+
+===== Sample Config Files
+
+.Sample +akka.conf+ file
+----
+odl-cluster-data {
+ bounded-mailbox {
+ mailbox-type = "org.opendaylight.controller.cluster.common.actor.MeteredBoundedMailbox"
+ mailbox-capacity = 1000
+ mailbox-push-timeout-time = 100ms
+ }
+
+ metric-capture-enabled = true
+
+ akka {
+ loglevel = "DEBUG"
+ loggers = ["akka.event.slf4j.Slf4jLogger"]
+
+ actor {
+
+ provider = "akka.cluster.ClusterActorRefProvider"
+ serializers {
+ java = "akka.serialization.JavaSerializer"
+ proto = "akka.remote.serialization.ProtobufSerializer"
+ }
+
+ serialization-bindings {
+ "com.google.protobuf.Message" = proto
+
+ }
+ }
+ remote {
+ log-remote-lifecycle-events = off
+ netty.tcp {
+ hostname = "10.194.189.96"
+ port = 2550
+ maximum-frame-size = 419430400
+ send-buffer-size = 52428800
+ receive-buffer-size = 52428800
+ }
+ }
+
+ cluster {
+ seed-nodes = ["akka.tcp://opendaylight-cluster-data@10.194.189.96:2550"]
+
+ auto-down-unreachable-after = 10s
+
+ roles = [
+ "member-1"
+ ]
+
+ }
+ }
+}
+
+odl-cluster-rpc {
+ bounded-mailbox {
+ mailbox-type = "org.opendaylight.controller.cluster.common.actor.MeteredBoundedMailbox"
+ mailbox-capacity = 1000
+ mailbox-push-timeout-time = 100ms
+ }
+
+ metric-capture-enabled = true
+
+ akka {
+ loglevel = "INFO"
+ loggers = ["akka.event.slf4j.Slf4jLogger"]
+
+ actor {
+ provider = "akka.cluster.ClusterActorRefProvider"
+
+ }
+ remote {
+ log-remote-lifecycle-events = off
+ netty.tcp {
+ hostname = "10.194.189.96"
+ port = 2551
+ }
+ }
+
+ cluster {
+ seed-nodes = ["akka.tcp://opendaylight-cluster-rpc@10.194.189.96:2551"]
+
+ auto-down-unreachable-after = 10s
+ }
+ }
+}
+----
+
+.Sample +module-shards.conf+ file
+----
+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"
+ ]
+ }
+ ]
+ }
+]
+----
\ No newline at end of file
To log in to DLUX, after installing the application:
. Open a browser and enter the login URL http://<your-karaf-ip>:8181/index.html in your browser (Chrome is recommended).
-. Login to the application with user ID and password credentials as *admin*.
+. Login to the application with your username and password credentials.
-NOTE: admin is the only user type available for DLUX in this release.
+NOTE: OpenDaylight's default credentials are _admin_ for both the username and password.
=== Working with DLUX
=== 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. +
+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:
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 OpenFlow plugin. Controller stores this information in the database and displays on the DLUX page, when the you connect to the controller using OpenFlow.
+NOTE: DLUX does not allow for editing or adding topology information. The topology is generated and edited in other modules, e.g., the OpenFlow plugin. OpenDaylight stores this information in the MD-SAL datastore where DLUX can read and display it.
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.
-
-'''
+ In the diagram blue boxes represent the switches, the black represents the hosts available, and lines represents how the switches and hosts 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 larger topologies.
.Topology Module
image::dlux-topology.png["DLUX Topology Page",width=500]
-=== Interacting with OpenDaylight
+=== Interacting with the YANG-based MD-SAL datastore
-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].
+The *Yang UI* module enables you to interact with the YANG-based MD-SAL datastore. For more information about YANG and how it interacts with the MD-SAL datastore, see the _Controller_ and _YANG Tools_ section of the _OpenDaylight Developer Guide_.
.Yang UI
image::dlux-yang-ui-screen.png["DLUX Yang UI Page",width=500]
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. +
+. The top part displays a tree of APIs, subAPIs, and buttons to call possible functions (GET, POST, PUT, and DELETE).
++
+NOTE: Not every subAPI can call every function. For example, subAPIs in the _operational_ store have GET functionality only.
++
+Inputs can be filled from OpenDaylight when existing data from OpenDaylight is displayed or can be filled by user on the page and sent to OpenDaylight.
++
+Buttons under the API tree are variable. It depends on subAPI specifications. Common buttons are:
++
+* GET to get data from OpenDaylight,
+* PUT and POST for sending data to OpenDaylight for saving
+* DELETE for sending data to OpenDaylight for deleting.
++
+You must specify the xpath for all these operations. This path is displayed in the same row before buttons and it may include text inputs for specific path element identifiers.
+
-
.Yang API Specification
image::dlux-yang-api-specification.png["DLUX Yang UI API Specification Page",width=500]
-
-. 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. +
+. The bottom part of the right pane displays inputs according to the chosen subAPI.
++
+* Lists are handled as a special case. For example, a device can store multiple flows. In this case "flow" is name of the list and every list element is identified by a unique key value. Elements of a list can, in turn, contain other lists.
+* In Yang UI, each list element is rendered with the name of the list it belongs to, its key, its value, and a button for removing it from the list.
+
-
.Yang UI API Specification
image::dlux-yang-sub-api-screen.png["DLUX Yang UI Sub API Specification Page",width=500]
-
-. 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.
-
-'''
++
+. After filling in the relevant inputs, click the *Show Preview* button under the API tree to display request that will be sent to OpenDaylight.
+ 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.
+. Select subAPI network-topology <topology revision number> == > operational == > network-topology.
+. Get data from OpenDaylight by clicking on the "GET" button.
. Click *Display Topology*.
.DLUX Yang Topology
image::dlux-yang-topology.png["DLUX Yang Topology Page",width=500]
-'''
-
==== 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:
-
-'''
+Lists in Yang UI are displayed as trees. To expand or collapse a list, click the arrow before name of the list. To configure list elements in 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 add a new list element with empty inputs use the plus icon-button **+** that is provided after list name.
. To remove several list elements, use the *X* button that is provided after every list element.
+
-
.DLUX List Elements
-image::dlux-yang-list elements.png[DLUX list elements,width=500]
-. 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-elements.png[DLUX list elements,width=500]
++
+. In the YANG-based data store all elements of a list must have a unique key. If you try to assign two or more elements the same key, a warning icon *!* is displayed near their name buttons.
+
-
.DLUX List Warnings
image::dlux-yang-list-warning.png[DLUX list warnings,width=500]
-. 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.
+
-
+. When the list contains at least one list element, after the *+* icon, there are buttons to select each individual list element. You can choose one of them by clicking on it. In addition, to the right of the list name, there is a button which will display a vertically scrollable pane with all the list elements.
++
.DLUX List Button1
image::dlux-yang-list-button1.png[DLUX list button1,width=500]
-
-'''
=== 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.
+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.
+XSQL allows you to query tree models like 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.
+The following sections cover the XSQL installation process, supported XSQL
+commands, and the way to structure queries.
=== Installing XSQL
-Before you can run commands from the XSQL console, you must first install XSQL onto your system:
+To run commands from the XSQL console, you must first install XSQL on your
+system:
-'''
-
-. Navigate to the directory in which you unzipped the OpenDaylight source files.
-. Start Karaf: *./karaf*
-. Install XSQL: *feature:install odl-mdsal-xsql*
-
-'''
+. Navigate to the directory in which you unzipped OpenDaylight
+. Start Karaf:
++
+ ./bin/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>_
+To enter a command in the XSQL console, structure the command as follows:
+*odl:xsql* _<XSQL command>_
-The following table describes the commands supported in this OpenDaylight release.
+The following table describes the commands supported in this OpenDaylight
+release.
.Supported XSQL Console Commands
-[cols="2",options="headers"]
+[cols="30%,70%",options="headers"]
|==============================================
| *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.
+| 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.
+| 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.
+| 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 a server and
+establish a connection.
| *exit*
| Closes the console.
| *tocsv*
-| Enables/disables the forwarding of query output as a .csv file.
+| Enables or 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.
+| Specifies the .tocsv file to which the 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:
+You can run a query to extract information that meets the criteria you specify
+using the information provided by the *list vtables* and *list vfields*
+_<vtable name>_ commands. 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>_*';*
-*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, if 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, enter the following query:
-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:
-*Select nodes/node.ID from nodes/node-connector where Hardware-Address like ’%BA%’;*
+ select nodes/node.ID from nodes/node-connector where Hardware-Address like '%BA%';
The following criteria operators are supported:
.Supported XSQL Query Criteria Operators
-[cols="2",options="headers"]
+[cols="20%,80%",options="headers"]
|==============================================
| *Criteria Operators* | *Description*
-| *=* | Lists results that equal the value you specify.
-| *!=* | Lists results that do not equal the value you specify.
-| *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.
-| *>* | Lists results that are more than the value you specify.
-| *and* | Lists results that match both values you specify.
-| *or* | Lists results that match either of the two values you specify.
-| *>=* | Lists results that are more than or equal to the value you specify.
-| *<=* | Lists results that are less than or equal to the value you specify.
-| *is null* | Lists results for which no value is assigned.
+| *=* | Lists results that equal the value you specify.
+| *!=* | Lists results that do not equal the value you specify.
+| *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.
+| *>* | Lists results that are more than the value you specify.
+| *and* | Lists results that match both values you specify.
+| *or* | Lists results that match either of the two values you specify.
+| *>=* | Lists results that are more than or equal to the value you specify.
+| *<=* | Lists results that are less than or equal to the value you specify.
+| *is null* | Lists results for which no value is assigned.
| *not null* | Lists results for which any value is assigned.
-| *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.
+| *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
+==== 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:
+If 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
*** 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.
+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.
Code Review / docs.git / commitdiff