Page History

...

Contributors

Overview

This section provides an overview on the NETCONF protocol implementation in ONOS.

...

For more background on NETCONF operations, check this out.

Connect your own device to ONOS

Devices are discovered based on the Network Configuration Service, which uses a JSON file to represent the configuration of as well as provide information about devices.

If you have your own device that talks NETCONF protocol follow this section. Otherwise, if you want to try ONOS NETCONF implementation out with a test VM 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. 

...

activate the netconf app :

onos> app activate org.onosproject.netconf

...

if you wrote your own driver for your device activate that specific driver (i.e.) :

onos> app activate org.onosproject.drivers.fujitsu

...

give ONOS the information to connect to the device and which driver to use for you 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 "netconf" one.

{
  "devices":{
    "netconf:<ip>:<port>":{
      "basic":{
        "driver": <driver-name>
      }
    }
  },
  "apps":{
    "org.onosproject.netconf":{
      "devices":[{
        "name":<username>,
        "password":<password>,
        "ip":<ip>,
        "port":<port>
      }]
    }
  }
}

A working example is in $ONOS_ROOT/tools/test/configs/netconf-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.
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>".

...

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

<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 

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

...

Check if the device is present in ONOS:

onos> devices

should return, among other devices also something like:

onos> id=netconf:10.1.9.24:1830, available=true, role=MASTER, type=SWITCH, mfr=unknown, hw=unknown, sw=unknown, serial=unknown, ipaddress=10.1.9.24, driver=ovs-netconf, name=netconf:10.1.9.24:1830

If the device is not present the could have been and 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 <IP Address with ONOS instance>

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

  Code Block
  WARN | event-dispatch-0 | ListenerRegistry <.....> org.onosproject.netconf.NetconfException: Can't connect to NETCONF device on 10.1.9.24:1830

  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.

refer to this reference source about NETCONF protocol operations.

Device Discovery

Currently, ONOS is made aware of NETCONF devices through the use of a Network Configuration Service JSON file, which represents the configuration of and provides information about devices. An example of such a file is provided here on GitHub if you don't have the source code checked out or in the ONOS source code in ${ONOS_ROOT}/tools/test/configs/netconf-cfg.json. This JSON file informs ONOS of the existence of such devices when it is pushed, but the confirmation of their reachability and availability occurs in the device provider, NetconfDeviceProvider. For more information about the device subsystem, refer to the Device Subsystem wiki page. When the NETCONF devices from the JSON files are pushed to ONOS, the devices are created with the default availability set to false, indicating inability to use the device. Shortly after (approximately 3 seconds after devices configuration is pushed to ONOS), and at intervals of 30 seconds afterwards, the reachability of all devices in the configuration is checked, and according to the information collected, the devices are either marked online (available=true), marked offline (available=false), or the availability state is left unchanged.

Connect your own device to ONOS

If you have your own device that talks NETCONF protocol follow this section. Otherwise, if you want to try ONOS NETCONF implementation out with a test VM 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 app :

  Code Block
  onos> app activate org.onosproject.netconf

• if you wrote your own driver for your device activate that specific driver (i.e.) :

  Code Block
  onos> app activate org.onosproject.drivers.fujitsu

• give ONOS the information to connect to the device and which driver to use for you 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 "netconf" one.

  Code Block
  { "devices": { "netconf:<ip>:<port>": { "netconf": { "ip": "<ip>", "port": <port>, "username": "<username>", "password": "<password>" }, "basic": { "driver": "<driver-name>" } } } }

  A working example is here on GitHub or in $ONOS_ROOT/tools/test/configs/netconf-cfg.json if you have the source code. 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. For passwordless ssh, don't provide password field in the netconf-cfg.json and generate ssh keys on onos host machine at path /root/.ssh/ with name id_rsa using ssh-keygen -m PEM -t rsa -N "" -f /root/.ssh/id_rsa. ONOS will automatically pick up private key from this path and use it for authenticating ssh session.
  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 you don't specify any driver-name in the basic configuration ONOS will assign the default one. Being the default one very much related to OpenFlow devices. It's suggested to always specify the driver-name  with yours or the "netconf" one.

   

• 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=netconf:10.1.9.24:830, available=true, role=MASTER, type=SWITCH, mfr=unknown, hw=unknown, sw=unknown, serial=unknown, ipaddress=10.1.9.24, driver=ovs-netconf, name=netconf:10.1.9.24:830

  If the device is not present then it could have been and 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 <IP Address with ONOS instance>

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

    Code Block
    WARN | event-dispatch-0 | ListenerRegistry <.....> org.onosproject.netconf.NetconfException: Can't connect to NETCONF device on 10.1.9.24:830

    In case the log is 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.

Timeouts

The NETCONF controller has 3 timeout parameters which control how the underlying SSH client connects to the remote NETCONF device

• The connect timeout - the length of time in seconds that is allowed for the SSH connection protocol to complete - this is 5 seconds by default
• The reply timeout - the length of time in seconds that is allowed for a reply to a NETCONF command to be returned - this is 5 seconds by default
• The idle timeout - the length of time in seconds that the SSH connection will be automatically closed after if no traffic is detected - this is 300 seconds by default

These 3 parameters are changeable both system wide through the Configuration Service and individually per NETCONF device through the Network Configuration Service.

The system-wide adjustment can be made through the ONOS CLI "cfg get" shows the values and "cfg set" changes the values:

onos> cfg get org.onosproject.netconf.ctl.impl.NetconfControllerImpl 
org.onosproject.netconf.ctl.impl.NetconfControllerImpl
    name=sshLibrary, type=string, value=apache-mina, defaultValue=apache-mina, description=Ssh Library instead of apache_mina (i.e. ethz-ssh2
    name=netconfIdleTimeout, type=integer, value=300, defaultValue=300, description=Time (in seconds) SSH session will close if no traffic seen
    name=netconfConnectTimeout, type=integer, value=5, defaultValue=5, description=Time (in seconds) to wait for a NETCONF connect.
    name=netconfReplyTimeout, type=integer, value=5, defaultValue=5, description=Time (in seconds) waiting for a NetConf reply
onos>

Values for individual devices are settable through the Network Configuration Service. Under the "netconf" grouping the following additional attributes can be optionally added in any order

• "connect-timeout": <int - values below 1 will be ignored>
• "reply-timeout": <int - values below 1 will be ignored>
• "idle-timeout": <int - values below 1 will be ignored>

If individual device settings exist for a device, they will take priority over system wide settings for that device. It is at the creation of the NETCONF session that the values are taken in to account and changing them after that will have no effect on that session. If the session is closed however, and a new session opened, then any new values are taken in to account.

 "devices": {
    <device-id>: {
    "netconf": {
          "username": <user>,
          "password": <pw>,
          "ip": <ip>,
          "port": <port>,
          "connect-timeout": 20,
          "reply-timeout": 25
    },

SSH Client

Two different SSH Client libraries are available in ONOS for NETCONF connections - Apache Mina SSH Client and Ganymede SSH Client - Apache Mina is the default library.

Again the client library may be set system wide or individually per device. To set it per device use the following when provisioning the device through the Network Configuration Service.

• "ssh-client": <value - either "ethz-ssh2" or "apache-mina">

NOTE : ethz-ssh2 has been removed from ONOS 1.10 onwards

...

.

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 communicate 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 actual 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 and 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

...

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

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

...

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.