include::lacp/lacp-dev.adoc[]
+include::controller/netconf/odl-netconf-dev.adoc[]
+
include::nic/nic-dev.adoc[]
include::neutron/neutron.adoc[]
--- /dev/null
+== NETCONF Developer Guide
+
+NOTE: Reading the NETCONF section in the User Guide is likely useful as
+ it contains an overview of NETCONF in OpenDaylight and a how-to
+ for spawning and configuring NETCONF connectors.
+
+This chapter is recommended for application developers who want to
+interact with mounted NETCONF devices from their application code. It
+tries to demonstrate all the use cases from user guide with
+RESTCONF but now from the code level. One important difference would
+be the demonstration of NETCONF notifications and notification
+listeners. The notifications were not shown using RESTCONF because
+*RESTCONF does not support notifications from mounted NETCONF
+devices.*
+
+NOTE: It may also be useful to read the generic
+ https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:MD-SAL_App_Tutorial[OpenDaylight
+ MD-SAL app
+ development tutorial] before diving into this chapter.
+ This guide assumes awareness of basic OpenDaylight application
+ development.
+
+=== Sample app overview
+All the examples presented here are implemented by a sample OpenDaylight
+application called *ncmount* in the `coretutorials` OpenDaylight project.
+It can be found on the github mirror of OpenDaylight's repositories:
+
+* https://github.com/opendaylight/coretutorials/tree/stable/lithium/ncmount
+
+or checked out from the official OpenDaylight repository:
+
+* https://git.opendaylight.org/gerrit/#/admin/projects/coretutorials
+
+*The application was built using the
+https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Startup_Project_Archetype[project
+startup maven archetype] and demonstrates how to:*
+
+* preconfigure connectors to NETCONF devices
+* retrieve MountPointService (registry of available mount points)
+* listen and react to changing connection state of netconf-connector
+* add custom device YANG models to the app and work with them
+* read data from device in binding aware format (generated java APIs
+ from provided YANG models)
+* write data into device in binding aware format
+* trigger and listen to NETCONF notifications in binding aware format
+
+Detailed information about the structure of the application can be
+found at:
+https://wiki.opendaylight.org/view/Controller_Core_Functionality_Tutorials:Tutorials:Netconf_Mount
+// TODO Migrate the information from wiki here
+
+NOTE: The code in ncmount is fully *binding aware* (works with generated
+java APIs from provided YANG models). However it is also possible to
+perform the same operations in *binding independent* manner.
+// TODO Add BI NcmountProvider version into the sample app and link it from here
+
+==== NcmountProvider
+The NcmountProvider class (found in NcmountProvider.java) is the central
+point of the ncmount application and all the application logic is
+contained there. The following sections will detail its most interesting
+pieces.
+
+===== Retrieve MountPointService
+The MountPointService is a central registry of all available mount points
+in OpenDaylight. It is just another MD-SAL service and is available from the
++session+ attribute passed by +onSessionInitiated+ callback:
+
+----
+@Override
+public void onSessionInitiated(ProviderContext session) {
+ LOG.info("NcmountProvider Session Initiated");
+
+ // Get references to the data broker and mount service
+ this.mountService = session.getSALService(MountPointService.class);
+
+ ...
+
+ }
+}
+----
+
+===== Listen for connection state changes
+It is important to know when a mount point appears, when it is fully
+connected and when it is disconnected or removed. The exact states of a
+mount point are:
+
+* Connected
+* Connecting
+* Unable to connect
+
+To receive this kind of information, an application has to register
+itself as a notification listener for the preconfigured
+netconf-topology subtree in MD-SAL's datastore. This can be performed
+in the +onSessionInitiated+ callback as well:
+
+----
+@Override
+public void onSessionInitiated(ProviderContext session) {
+
+ ...
+
+ this.dataBroker = session.getSALService(DataBroker.class);
+
+ // Register ourselves as the REST API RPC implementation
+ this.rpcReg = session.addRpcImplementation(NcmountService.class, this);
+
+ // Register ourselves as data change listener for changes on Netconf
+ // nodes. Netconf nodes are accessed via "Netconf Topology" - a special
+ // topology that is created by the system infrastructure. It contains
+ // all Netconf nodes the Netconf connector knows about. NETCONF_TOPO_IID
+ // is equivalent to the following URL:
+ // .../restconf/operational/network-topology:network-topology/topology/topology-netconf
+ if (dataBroker != null) {
+ this.dclReg = dataBroker.registerDataChangeListener(LogicalDatastoreType.OPERATIONAL,
+ NETCONF_TOPO_IID.child(Node.class),
+ this,
+ DataChangeScope.SUBTREE);
+ }
+}
+----
+
+The implementation of the callback from MD-SAL when the data change can be
+found in the
++onDataChanged(AsyncDataChangeEvent<InstanceIdentifier<?>, DataObject>
+change)+ callback of
+https://github.com/opendaylight/coretutorials/blob/stable/lithium/ncmount/impl/src/main/java/ncmount/impl/NcmountProvider.java[NcmountProvider
+class].
+
+===== Reading data from the device
+The first step when trying to interact with the device is to get the exact
+mount point instance (identified by an instance identifier) from the MountPointService:
+
+----
+@Override
+public Future<RpcResult<ShowNodeOutput>> showNode(ShowNodeInput input) {
+ LOG.info("showNode called, input {}", input);
+
+ // Get the mount point for the specified node
+ // Equivalent to '.../restconf/<config | operational>/opendaylight-inventory:nodes/node/<node-name>/yang-ext:mount/'
+ // Note that we can read both config and operational data from the same
+ // mount point
+ final Optional<MountPoint> xrNodeOptional = mountService.getMountPoint(NETCONF_TOPO_IID
+ .child(Node.class, new NodeKey(new NodeId(input.getNodeName()))));
+
+ Preconditions.checkArgument(xrNodeOptional.isPresent(),
+ "Unable to locate mountpoint: %s, not mounted yet or not configured",
+ input.getNodeName());
+ final MountPoint xrNode = xrNodeOptional.get();
+
+ ....
+}
+----
+
+NOTE: The triggering method in this case is called +showNode+. It is a
+YANG-defined RPC and NcmountProvider serves as an MD-SAL RPC
+implementation among other things. This means that +showNode+ an be
+triggered using RESTCONF.
+
+The next step is to retrieve an instance of the +DataBroker+ API from the
+mount point and start a read transaction:
+
+----
+@Override
+public Future<RpcResult<ShowNodeOutput>> showNode(ShowNodeInput input) {
+
+ ...
+
+ // Get the DataBroker for the mounted node
+ final DataBroker xrNodeBroker = xrNode.getService(DataBroker.class).get();
+ // Start a new read only transaction that we will use to read data
+ // from the device
+ final ReadOnlyTransaction xrNodeReadTx = xrNodeBroker.newReadOnlyTransaction();
+
+ ...
+}
+----
+
+Finally, it is possible to perform the read operation:
+
+----
+@Override
+public Future<RpcResult<ShowNodeOutput>> showNode(ShowNodeInput input) {
+
+ ...
+
+ InstanceIdentifier<InterfaceConfigurations> iid =
+ InstanceIdentifier.create(InterfaceConfigurations.class);
+
+ Optional<InterfaceConfigurations> ifConfig;
+ try {
+ // Read from a transaction is asynchronous, but a simple
+ // get/checkedGet makes the call synchronous
+ ifConfig = xrNodeReadTx.read(LogicalDatastoreType.CONFIGURATION, iid).checkedGet();
+ } catch (ReadFailedException e) {
+ throw new IllegalStateException("Unexpected error reading data from " + input.getNodeName(), e);
+ }
+
+ ...
+}
+----
+
+The instance identifier is used here again to specify a subtree to read
+from the device. At this point application can process the data as it sees
+fit. The ncmount app transforms the data into its own format and returns
+it from +showNode+.
+
+NOTE: More information can be found in the source code of ncmount
+sample app + on wiki:
+https://wiki.opendaylight.org/view/Controller_Core_Functionality_Tutorials:Tutorials:Netconf_Mount
// END COMMENT
//////////////////////////
-include::ch-introduction.adoc[]
-
include::release-notes.adoc[OpenDaylight Release Notes]
include::general_installation.adoc[]
+= Getting to know OpenDaylight
+
+include::ch-introduction.adoc[]
+
+include::ch-dlux.adoc[]
+
+include::ch-xsql-commands.adoc[]
+
+include::ch-clustering.adoc[]
+
+= Project-specific Installation Guides
+
include::opflex/agent-ovs-install.adoc[]
include::ovsdb/ovsdb-install.adoc[]
--- /dev/null
+== 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 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 instance of OpenDaylight, perform the
+following steps:
+
+. Download, unzip, and run the OpenDaylight distribution
+. Install the clustering feature:
++
+ feature:install odl-mdsal-clustering
+
+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
+
+The following sections describe how to set up multiple node clusters in OpenDaylight.
+
+==== Deployment Considerations
+
+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 OpenDaylight in a three node cluster, perform the following:
+
+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 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.
++
+.. 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. 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"
+ ]
++
+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-2",
+ "member-3"
+ ]
++
+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
--- /dev/null
+== Using the OpenDaylight User Interface (DLUX)
+
+This section introduces you to the OpenDaylight User Experience (DLUX) application.
+
+=== Getting Started with DLUX
+
+DLUX provides a number of different Karaf features, which you can enable and disable separately. In Lithium they are:
+. odl-dlux-core
+. odl-dlux-node
+. odl-dlux-yangui
+. odl-dlux-yangvisualizer
+
+=== Logging In
+
+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 your username and password credentials.
+
+NOTE: OpenDaylight's default credentials are _admin_ for both the username and password.
+
+=== Working with DLUX
+
+After you login to DLUX, if you enable only odl-dlux-core feature, you will see only topology application available in the left pane.
+
+NOTE: To make sure topology displays all the details, enable the odl-l2switch-switch feature in Karaf.
+
+DLUX has other applications such as node, yang UI and those apps won't show up, until you enable their features odl-dlux-node and odl-dlux-yangui respectively in the Karaf distribution.
+
+.DLUX Modules
+image::dlux-login.png["DLUX Page",width=500]
+
+NOTE: If you install your application in dlux, they will also show up on the left hand navigation after browser page refresh.
+
+=== 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 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 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 the YANG-based MD-SAL datastore
+
+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, 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.
++
+* 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]
++
+. 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 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*
+
+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.
+. 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]
++
+. 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 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]
--- /dev/null
+== Running XSQL Console Commands and Queries
+
+//* <<XSQL Overview>>
+//* <<Installing XSQL>>
+//* <<XSQL Console Commands>>
+//* <<XSQL Queries>>
+//** <<Example: skip Criteria Operator>>
+:toc:
+
+=== 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.
+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 cover the XSQL installation process, supported XSQL
+commands, and the way to structure queries.
+
+=== Installing XSQL
+
+To run commands from the XSQL console, you must first install XSQL on your
+system:
+
+. Navigate to the directory in which you unzipped OpenDaylight
+. Start Karaf:
++
+ ./bin/karaf
++
+. Install XSQL:
++
+ feature:install odl-mdsal-xsql
+
+=== XSQL Console Commands
+
+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.
+
+.Supported XSQL Console Commands
+[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.
+| *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 a server and
+establish a connection.
+| *exit*
+| Closes the console.
+| *tocsv*
+| Enables or disables the forwarding of query output as a .csv file.
+| *filename* _<filename>_
+| 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
+
+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>_*';*
+
+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:
+
+ 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="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.
+| *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.
+|==============================================
+
+==== Example: Skip Criteria Operator
+
+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
+*** 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.
+
//
// TBD
-=== Installing the DLUX web interface
-
-The OpenDaylight web interface; DLUX, draws information from topology and host databases to display information about the topology of the network,
-flow statistics, host locations. You can either use DLUX as a stand-alone plug-in or integrate with OpenDaylight.
-To install DLUX as a standalone application, refer to https://wiki.opendaylight.org/view/OpenDaylight_DLUX:Setup_and_Run
-To integrate with OpenDaylight you must enable DLUX Karaf feature. You can enable AD-SAL, 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, refer to https://wiki.opendaylight.org/view/OpenDaylight_DLUX:DLUX_Karaf_Feature
+// Commenting this out as it appears to be out of date and there is already
+// information about installing and using DLUX above.
+//
+//=== Installing the DLUX web interface
+//
+//The OpenDaylight web interface; DLUX, draws information from topology and host databases to display information about the topology of the network,
+//flow statistics, host locations. You can either use DLUX as a stand-alone plug-in or integrate with OpenDaylight.
+//To install DLUX as a standalone application, refer to https://wiki.opendaylight.org/view/OpenDaylight_DLUX:Setup_and_Run
+//To integrate with OpenDaylight you must enable DLUX Karaf feature. You can enable AD-SAL, 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, refer to https://wiki.opendaylight.org/view/OpenDaylight_DLUX:DLUX_Karaf_Feature
=== Installing MD-SAL clustering
The MD-SAL clustering feature has "special" compatibility criteria. You *must*
. Install the required features with these commands:
feature:install odl-ovsdb-openstack
-===== Sample output from the Karaf console
+==== Sample output from the Karaf console
----
opendaylight-user@root>feature:list -i | grep ovsdb
odl-ovsdb-southbound-api | 1.1.0-SNAPSHOT | x | odl-ovsdb-southbound-1.1.0-SNAPSHOT
include::ch-introduction.adoc[OpenDaylight Controller Overview]
-include::ch-dlux-userguide.adoc[Using the OpenDaylight User Interface (DLUX)]
+//TODO: these three includes are a hugely ugly hack that needs to go
+include::../../../../getting-started-guide/src/main/asciidoc/ch-dlux.adoc[]
-include::ch-xsql-commands.adoc[Running XSQL Console Commands and Queries]
+include::../../../../getting-started-guide/src/main/asciidoc/ch-xsql-commands.adoc[]
-include::ch-clustering.adoc[Setting Up Clustering on an OpenDaylight Controller]
+include::../../../../getting-started-guide/src/main/asciidoc/ch-clustering.adoc[]
= Applications and Plugins
+++ /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
-== Using the OpenDaylight User Interface (DLUX)
-
-This section introduces you to the OpenDaylight User Experience (DLUX) application.
-
-=== Getting Started with DLUX
-
-DLUX provides a number of different Karaf features, which you can enable and disable separately. In Lithium they are:
-. odl-dlux-core
-. odl-dlux-node
-. odl-dlux-yangui
-. odl-dlux-yangvisualizer
-
-=== Logging In
-
-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*.
-
-NOTE: admin is the only user type available for DLUX in this release.
-
-=== Working with DLUX
-
-After you login to DLUX, if you enable only odl-dlux-core feature, you will see only topology application available in the left pane.
-
-NOTE: To make sure topology displays all the details, enable the odl-l2switch-switch feature in Karaf.
-
-DLUX has other applications such as node, yang UI and those apps won't show up, until you enable their features odl-dlux-node and odl-dlux-yangui respectively in the Karaf distribution.
-
-.DLUX Modules
-image::dlux-login.png["DLUX Page",width=500]
-
-NOTE: If you install your application in dlux, they will also show up on the left hand navigation after browser page refresh.
-
-=== 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 OpenFlow 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",width=500]
-
-=== Interacting with OpenDaylight
-
-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].
-
-.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. +
-+
-
-.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. +
-+
-
-.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.
-
-'''
-
-==== 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*.
-
-.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:
-
-'''
-
-. 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.
-+
-
-.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.
-+
-
-.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.
-+
-
-.DLUX List Button1
-image::dlux-yang-list-button1.png[DLUX list button1,width=500]
-
-'''
+++ /dev/null
-== Running XSQL Console Commands and Queries
-
-//* <<XSQL Overview>>
-//* <<Installing XSQL>>
-//* <<XSQL Console Commands>>
-//* <<XSQL Queries>>
-//** <<Example: skip Criteria Operator>>
-:toc:
-
-=== 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 this OpenDaylight release.
-
-.Supported XSQL Console Commands
-[cols="2",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.
-| *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:
-*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"]
-|==============================================
-| *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.
-| *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.
-|==============================================
-
-==== 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.
-
Code Review / docs.git / commitdiff
