Page History

Table of Contents

Contributors

Overview

This section provides an overview on the REST southbound protocol implementation in ONOS that is used to obtain information and configure devices through interaction with the REST APIs that they expose.

Interfaces and Classes

• RestSBController.java, implemented by RestSBControllerImpl.java: tracks all the NETCONF devices, serves as a one stop for connecting and obtaining a device and (un)register listeners on device events. It also exposes interface methods to do REST CRUD operations on a device identified by a DeviceId.

• RestSBDevice.java implemented by NetconfDeviceImplby DefaultRestSBDevice.java: represents a NETCONF REST capable device connected known to the ONOS core with his own NetconfSession and his informations saved in an instance of NetconfDeviceInfoall the information needed such as Ip,port,name,password,protocol, deviceId.
• RestDeviceProvider.java: manages any NETCONF REST device role and all the interactions with the ONOS core.
• XMLConfigParser.java: parser for reading and producing XML files to and from the REST device. For now has only configuration reader and edit controllers configuration producer.

Through implementing the NetconfDeviceOutputEventListener.java and adding the listener to the session anybody who needs to obtain device notifications can listen on device generated messages that are picked up by the listeners implementations that is in the set of to be notified listeners in the StreamHandler implementation, right now NetconfStreamThread.java.

Connect your own device to ONOS

• , such as provisioning the ports and the initial device setup. Has his own internalConfigListener from which it gets notified when a configuration is pushed to ONOS via restAPI. The device is added to ONOS if replies on the ip and port that the configuration provides.

Notify ONOS of your REST device 

This section specifies how to notify the ONOS core of a device that support REST operations for configurationIf you have your own device that talks NETCONF protocol follow this section, if you don't but want to try ONOS NETCONF implementation out proceed to the Example section.

Once you have your device Running on some IP address and some port, in order to make ONOS see it you should follow these steps. 

• start ONOS

• activate the netconf REST southbound app :

  Code Block
  onos> app activate org.onosproject.netconfrestsb

• activate the REST drivers for your device (i.e. ciena drivers) :

  Code Block
  onos> app activate org.onosproject.drivers.ciena.waveserver

• give ONOS the information to connect to regarding the device and which driver to use for you your device in a json file. You need to specify username, password, ip and port. If you wrote a specific driver that has also to be changed form the standard "netconfrest" one.

  Code Block

  { "devices": { "netconfrest:<username>@<ip><ip>:<port>": { "basicrest": { "driverusername":"ovs-netconf"<username>, } "password":<password>, } }, "appsip":{ <ip in string format>, "org.onosproject.netconfport":{ <port in integer formato> "protocol":<portocol, i.e. http> "devicesurl":[{ <url for the base get operation of the "name":<username>,device, {optional}> "password":<password>}, "ipbasic":<ip>, { "portdriver":<port> <driver-name> }] } } }

  A working example is in $ONOS_ROOT/tools/test/configs/netconfrestSB-cfg.json. Change the IP both in the DeviceId at the top and in the devices array. The port number by default on NETCONF is 830, so unless you made any changes to that leave it as is. This example expects that your are running a REST server locally (127.0.0.1) on port 8080.
  You can also add other information, more than the driver, to the basic device configuration information: "type": "<device-type>", "manufacturer": "<device-manufacturer>","hwVersion": "<hw-version>","swVersion": "<sw-version>". If added, the url field will be used to contact the device and find it's reachability instead of ip:port. This url will also be used as a base for URL composition to reach other resources. 

   

• upload the configuration you just wrote to the instance of ONOS you are running, in our case localhost:

  Code Block
  <your_machine>~$ curl -X POST -H "content-type:application/json" http://localhost:8181/onos/v1/network/configuration -d @<path_to_your_json_configuration_file> --user onos:rocks

  or 

  Code Block
  <your_machine>~$ onos-netcfg localhost <path_to_your_json_configuration_file>

• Check if the device is present in ONOS:

  Code Block
  onos> devices

  should return, among other devices also something like:

  Code Block
  onos> id=netconfrest:mininet@10127.10.90.241:18308080, available=true, role=MASTER, type=SWITCH, mfr=unknown, hw=unknown, sw=unknown, serial=unknown, ipaddress=10127.10.90.241, driver=ovs-netconfrestCiena, name=netconfrest:mininet@10127.10.90.241:18308080

  If the device is not present the then it could have been and an error and you have to check the logs.

  • for localhost logs

    Code Block
    <your_machine>~$ tl

    or for remote logs

    Code Block
    <your_machine>~$ ol

  • verify that the logs don't contain NETCONF REST related exceptions and this warning error does not appear:

    Code Block
    2016-01-19 15:19:28,102 | INFOERROR | event-dispatch-0 | NetconfDeviceProviderRestDeviceProvider | 186192 - org.onosproject.onos-netconfrestsb-provider-device - 1.45.0.SNAPSHOT | Device Can't<device> connectnot toreachable, NETCONFerror devicecreating on <ip>:<port>HTTP connection java.net.ConnectException: Connection refused

    In case the log is preset present it means that the device was not able to reply on the given IP and Port. Verify Ip and Port in the Json file you posted and retry. If any other exception is present, such as no device name, please read the log and react to it accordingly.

• Once the device is present in ONOS you can interact with it.

Example: Get and Set Controllers.

An example of NETCONF infrastructure usage is getting and setting controllers on a device. These operations are defined in an ONOS Behaviour, in our case the NetconfControllerConfig.java, that implements ControllerConfig general behaviour. To do in the Behaviour operations on the devices, you need the NetconfController, which you can obtain through the DriverHandler. The NetconfController instance now gives you access to all the device or a single device. Once you have the device you are interested in based upon the deviceId you can get the NetconfSession object to comunicate with the device and do operations on the physical devices, like getting the configuration in in the get controllers methods or setting a pre-built new one for the setControllers. XmlConfigParser.java offers a method to extract the desired information from an devices's XML response and another method to produce the correct XML to set one or more controller on a specific device.

You can take a look at the acutal implementation of the get and set controllers operation in the NetconfControllerConfig.java class. For an example of other operations that can be implemented the OVSDB infrastructure provides a good starting point.

To call the getControllers and setControllers methods you need to obtain the ControllerConfig Behaviour nad then call on this instance the methods. The set and get commands are implemented, as an example, in DeviceControllersCommand.java and DeviceSetControllersCommand.java that provide, in two CLI commands

onos> device-controllers

onos> device-setcontrollers

Example: Testing infrastructure

To test locally (not on real switches) the NETCONF implementation you need the Mininet machine with of-config installed (link to mininet machine).

...

• If your driver specifies a PortDiscovery implementation, such as PortDiscoveryCienaWaveserverImpl.java the Rest southbound provider also queries the ports that are available on that device and updates the information in the ONOS core. 
  So if your run in ONOS the command:

  Code Block
  onos> ports

  should return, among other devices also something like:

  Code Block

  onos> id=rest:127.0.0.1:8080, available=true, role=MASTER, type=SWITCH, mfr=unknown, hw=unknown, sw=unknown, serial=unknown, ipaddress=127.0.0.1, driver=restCiena, name=rest:127.0.0.1:8080 port=4, state=enabled, type=och, signalType=ODU4, isTunable=yes , name=1.1 port=5, state=enabled, type=och, signalType=ODU4, isTunable=yes , name=1.2 port=20, state=enabled, type=oduclt, signalType=CLT_100GBE , name=5 port=24, state=enabled, type=oduclt, signalType=CLT_100GBE , name=6 port=28, state=enabled, type=oduclt, signalType=CLT_100GBE , name=7 port=32, state=enabled, type=oduclt, signalType=CLT_100GBE , name=8 port=48, state=enabled, type=och, signalType=ODU4, isTunable=yes , name=12.1 port=49, state=enabled, type=och, signalType=ODU4, isTunable=yes , name=12.2

• Once the device is present in ONOS you can interact with it via the driver/provider subsystem.

of-config is wrapper for an openvswitch instance, that uses NETCONF protocol and translates it to OVSDB in order to use that database implementation. 

Infrastructure Setup:

• Start the Mininet machine with of-config installed under Virtual-Box

• [Optional] Set a controller with the set controller command. For Example, you will have a different IP for your ONOS instance.

  Code Block
  mininet-vm:~$ sudo ovs-vsctl set-controller ofc-bridge tcp:10.128.12.1:6653

• Start the ofc-server in the Mininet machine

  Code Block
  mininet-vm:~$ sudo ofc-server -v 3 -f

• start ONOS

• activate the netconf app :

  Code Block
  onos> app activate org.onosproject.netconf

• give ONOS the information to connect to the device and which driver to use for it in the $ONOS_ROOT/tools/test/configs/netconf-cfg.json file. Change the IP both in the DeviceId at the top and in the devices array. The port number by default on NETCONF is 830, so unless you made any changes to that leave it as is.

• upload the configuration you just modified to the instance of ONOS you are running, in our case localhost:

  Code Block
  <your_machine>~$ curl -X POST -H "content-type:application/json" http://localhost:8181/onos/v1/network/configuration -d @$ONOS_ROOT/tools/test/configs/netconf-cfg.json --user onos:rocks

  or 

  Code Block
  <your_machine>~$ onos-netcfg localhost $ONOS_ROOT/tools/test/configs/netconf-cfg.json

• open the onos logs 

  for localhost logs

  Code Block
  <your_machine>~$ tl

  or for remote logs

  Code Block
  <your_machine>~$ ol

• verify that the logs don't contain NETCONF related exceptions and this warning does not appear:

  Code Block
  | WARN | event-dispatch-0 | NetconfDeviceProvider | 186 - org.onosproject.onos-netconf-provider-device - 1.4.0.SNAPSHOT | Can't connect to NETCONF device on <ip>:<port>

  In case the log is preset it means that the device was not able to reply on the given IP and Port. Verify Ip and Port in the Json file you posted and retry. If any other exception is present, such as no device name, please read the log and react to it accordingly.

• Call the command or run the app you have written. For example:

  Code Block
  onos> device-controllers netconf:mininet@10.1.9.24:830

Future Work

There is much room for improvement and testing, this is only a basic skeleton of the infrastructure. The improvement should be focused on extracting the XML that is now encoded in the NetconfSessionImpl's methods and testing each operation. In the future the XML can be generated through YANG models so it can be specific for every type of device we want to connect.

...