manuals/user-guide/src/main/asciidoc/controller/netconf/odl-netconf-southbound-user.adoc

   1 === Southbound (netconf-connector)
   2 NETCONF southbound plugin is capable of connecting to remote NETCONF
   3 devices and expose their configuration/operational datastores, rpcs and
   4 notifications as MD-SAL mount points. These mount points allow
   5 applications and remote users (over RESTCONF) to interact with the
   6 mounted devices.
   7
   8 In terms of RFCs, the connector supports:
   9
  10 * http://tools.ietf.org/html/rfc6241[RFC-6241],
  11 * https://tools.ietf.org/html/rfc5277[RFC-5277],
  12 * https://tools.ietf.org/html/rfc6022[RFC-6022],
  13
  14 *Netconf-connector is fully model driven (utilising YANG modeling language) so in addition to
  15 the above RFCs, it supports any data/RPC/notifications described by a
  16 YANG model that is implemented by the device.*
  17
  18 TIP: NETCONF southbound can be activated by installing
  19 +odl-netconf-connector-all+ Karaf feature.
  20
  21 ==== Netconf-connector configuration
  22 There are 2 ways for configuring netconf-connector (as is for any
  23 other module) NETCONF or RESTCONF. This guide focuses on using RESTCONF.
  24
  25 ===== Default configuration
  26 The default configuration contains all the necessary dependencies
  27 (file: 01-netconf.xml) and a single instance of netconf-connector
  28 (file: 99-netconf-connector.xml) called *controller-config* which
  29 connects itself to the NETCONF northbound in OpenDaylight in a loopback
  30 fashion. The connector mounts the NETCONF server for config-subsystem
  31 in order to enable RESTCONF protocol for config-subsystem. This
  32 RESTCONF still goes via NETCONF, but using RESTCONF is much more user
  33 friendly than using NETCONF.
  34
  35 ===== Spawning additional netconf-connectors while the controller is running
  36 Preconditions:
  37
  38 . OpenDaylight is running
  39 . In Karaf, you must have the netconf-connector installed (at the
  40   Karaf prompt, type: feature:install odl-netconf-connector-all); the
  41   loopback NETCONF mountpoint will be automatically configured and
  42   activated
  43 . Wait until log displays following entry:
  44   RemoteDevice{controller-config}: NETCONF connector initialized
  45   successfully
  46
  47 To configure a new netconf-connector you need to send following
  48 request to RESTCONF:
  49
  50 POST http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules
  51
  52 *Headers*:
  53 Accept application/xml
  54 Content-Type application/xml
  55
  56 ----
  57 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
  58   <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">prefix:sal-netconf-connector</type>
  59   <name>new-netconf-device</name>
  60   <address xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">127.0.0.1</address>
  61   <port xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">830</port>
  62   <username xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">admin</username>
  63   <password xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">admin</password>
  64   <tcp-only xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">false</tcp-only>
  65   <event-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
  66     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:netty">prefix:netty-event-executor</type>
  67     <name>global-event-executor</name>
  68   </event-executor>
  69   <binding-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
  70     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
  71     <name>binding-osgi-broker</name>
  72   </binding-registry>
  73   <dom-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
  74     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">prefix:dom-broker-osgi-registry</type>
  75     <name>dom-broker</name>
  76   </dom-registry>
  77   <client-dispatcher xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
  78     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:config:netconf">prefix:netconf-client-dispatcher</type>
  79     <name>global-netconf-dispatcher</name>
  80   </client-dispatcher>
  81   <processing-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
  82     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:threadpool</type>
  83     <name>global-netconf-processing-executor</name>
  84   </processing-executor>
  85   <keepalive-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
  86     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:scheduled-threadpool</type>
  87     <name>global-netconf-ssh-scheduled-executor</name>
  88   </keepalive-executor>
  89 </module>
  90 ----
  91
  92 This spawns a new netconf-connector which tries to
  93 connect to (or mount) a NETCONF device at 127.0.0.1 and port 830. You
  94 can check the configuration of config-subsystem's configuration datastore.
  95 The new netconf-connector will now be present there. Just invoke:
  96
  97 GET http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules
  98
  99 The response will contain the module for new-netconf-device.
 100
 101 Right after the new netconf-connector is created, it writes some
 102 useful metadata into the datastore of MD-SAL under the network-topology
 103 subtree. This metadata can be found at:
 104
 105 GET http://localhost:8181/restconf/operational/network-topology:network-topology/
 106
 107 Information about connection status, device capabilities etc. can be
 108 found there.
 109
 110 ===== Connecting to a device not supporting NETCONF monitoring
 111 The netconf-connector in OpenDaylight relies on ietf-netconf-monitoring support
 112 when connecting to remote NETCONF device. The ietf-netconf-monitoring
 113 support allows netconf-connector to list and download all YANG schemas
 114 that are used by the device. NETCONF connector can only communicate
 115 with a device if it knows the set of used schemas (or at least a
 116 subset). However, some devices use YANG models internally but do not
 117 support NETCONF monitoring. Netconf-connector can also communicate
 118 with these devices, but you have to side load the necessary yang
 119 models into OpenDaylight's YANG model cache for netconf-connector. In general
 120 there are 2 situations you might encounter:
 121
 122 *1. NETCONF device does not support ietf-netconf-monitoring but it
 123    does list all its YANG models as capabilities in HELLO message*
 124
 125 This could be a device that internally uses only ietf-inet-types
 126 YANG model with revision 2010-09-24. In the HELLO message that is sent
 127 from this device there is this capability reported:
 128
 129 ----
 130 urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2010-09-24
 131 ----
 132
 133 *For such devices you only need to put the schema into folder
 134 cache/schema inside your Karaf distribution.*
 135
 136 IMPORTANT: The file with YANG schema for ietf-inet-types has to be
 137 called ietf-inet-types@2010-09-24.yang. It is the required naming format
 138 of the cache.
 139
 140 *2. NETCONF device does not support ietf-netconf-monitoring and it
 141    does NOT list its YANG models as capabilities in HELLO message*
 142
 143 Compared to device that lists its YANG models in HELLO message, in
 144 this case there would be no capability with ietf-inet-types in the
 145 HELLO message. This type of device basically provides no information
 146 about the YANG schemas it uses so its up to the user of OpenDaylight to
 147 properly configure netconf-connector for this device.
 148
 149 Netconf-connector has an optional configuration attribute called
 150 yang-module-capabilities and this attribute can contain a list of
 151 "YANG module based" capabilities. So by setting this configuration
 152 attribute, it is possible to override the "yang-module-based"
 153 capabilities reported in HELLO message of the device. To do this, we
 154 need to modify the configuration of netconf-connector by adding this
 155 xml (It needs to be added next to the address, port, username etc.
 156 configuration elements):
 157
 158 ----
 159 <yang-module-capabilities xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 160   <capability xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 161     urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&amp;revision=2010-09-24
 162   </capability>
 163 </yang-module-capabilities>
 164 ----
 165
 166 *Remember to also put the YANG schemas into the cache folder.*
 167
 168 NOTE: For putting multiple capabilities, you just need to replicate
 169 the capability xml element inside yang-module-capability element.
 170 Capability element is modeled as a leaf-list.
 171 With this configuration, we would make the remote device report usage
 172 of ietf-inet-types in the eyes of netconf-connector.
 173
 174 ===== Reconfiguring Netconf-Connector While the Controller is Running
 175 It is possible to change the configuration of a running module while
 176 the whole controller is running. This example will continue where the last left off and
 177 will change the configuration for the brand new netconf-connector
 178 after it was spawned. Using one RESTCONF request, we will change both
 179 username and password for the netconf-connector.
 180
 181 To update an existing netconf-connector you need to send following
 182 request to RESTCONF:
 183
 184 PUT
 185 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-sal-netconf-connector-cfg:sal-netconf-connector/new-netconf-device
 186
 187 ----
 188 <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
 189   <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">prefix:sal-netconf-connector</type>
 190   <name>new-netconf-device</name>
 191   <username xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">bob</username>
 192   <password xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">passwd</password>
 193   <tcp-only xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">false</tcp-only>
 194   <event-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 195     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:netty">prefix:netty-event-executor</type>
 196     <name>global-event-executor</name>
 197   </event-executor>
 198   <binding-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 199     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
 200     <name>binding-osgi-broker</name>
 201   </binding-registry>
 202   <dom-registry xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 203     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:dom">prefix:dom-broker-osgi-registry</type>
 204     <name>dom-broker</name>
 205   </dom-registry>
 206   <client-dispatcher xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 207     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:config:netconf">prefix:netconf-client-dispatcher</type>
 208     <name>global-netconf-dispatcher</name>
 209   </client-dispatcher>
 210   <processing-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 211     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:threadpool</type>
 212     <name>global-netconf-processing-executor</name>
 213   </processing-executor>
 214   <keepalive-executor xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:connector:netconf">
 215     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:threadpool">prefix:scheduled-threadpool</type>
 216     <name>global-netconf-ssh-scheduled-executor</name>
 217   </keepalive-executor>
 218 </module>
 219 ----
 220
 221 Since a PUT is a replace operation, the whole configuration must be
 222 specified along with the new values for username and password. This
 223 should result in a 2xx response and the instance of netconf-connector
 224 called new-netconf-device will be reconfigured to use username bob and
 225 password passwd. New configuration can be verified by executing:
 226
 227 GET http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-sal-netconf-connector-cfg:sal-netconf-connector/new-netconf-device
 228
 229 With new configuration, the old connection will be closed and a new
 230 one established.
 231
 232 ===== Destroying Netconf-Connector While the Controller is Running
 233 Using RESTCONF one can also destroy an instance of a module. In case
 234 of netconf-connector, the module will be destroyed, NETCONF connection
 235 dropped and all resources will be cleaned. To do this, simply issue a
 236 request to following URL:
 237
 238 DELETE http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-sal-netconf-connector-cfg:sal-netconf-connector/new-netconf-device
 239
 240 The last element of the URL is the name of the instance and its
 241 predecessor is the type of that module (In our case the type is
 242 *sal-netconf-connector* and name *new-netconf-device*). The type and name
 243 are actually the keys of the module list.
 244
 245 ==== Netconf-connector utilisation
 246 Once the connector is up and running, users can utilize the new Mount
 247 point instance. By using RESTCONF or from their application code. This
 248 chapter deals with using RESTCONF and more information for app
 249 developers can be found in the developers guide or in the official
 250 tutorial application *ncmount* that can be found in the coretutorials project:
 251
 252 * https://github.com/opendaylight/coretutorials/tree/stable/lithium/ncmount
 253
 254 ===== Reading data from the device
 255 Just invoke (no body needed):
 256
 257 GET http://localhost:8080/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/
 258
 259 This will return the entire content of operation datastore from the
 260 device. To view just the configuration datastore, change *operational* in
 261 this URL to *config*.
 262
 263 ===== Writing configuration data to the device
 264 In general, you cannot simply write any data you want to the device.
 265 The data have to conform to the YANG models implemented by the device.
 266 In this example we are adding a new interface-configuration to the
 267 mounted device (assuming the device supports Cisco-IOS-XR-ifmgr-cfg
 268 YANG model). In fact this request comes from the tutorial dedicated to
 269 the *ncmount* tutorial app.
 270
 271 POST
 272 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/Cisco-IOS-XR-ifmgr-cfg:interface-configurations
 273
 274 ----
 275 <interface-configuration xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg">
 276     <active>act</active>
 277     <interface-name>mpls</interface-name>
 278     <description>Interface description</description>
 279     <bandwidth>32</bandwidth>
 280     <link-status></link-status>
 281 </interface-configuration>
 282 ----
 283
 284 Should return 200 response code with no body.
 285
 286 TIP: This call is transformed into a couple of NETCONF RPCs. Resulting
 287 NETCONF RPCs that go directly to the device can be found in the OpenDaylight
 288 logs after invoking +log:set TRACE
 289 org.opendaylight.controller.sal.connect.netconf+ in the Karaf shell.
 290 Seeing the NETCONF RPCs might help with debugging.
 291
 292 This request is very similar to the one where we spawned a new netconf
 293 device. That's because we used the loopback netconf-connector to write
 294 configuration data into config-subsystem datastore and config-subsystem
 295 picked it up from there.
 296
 297 ===== Invoking custom RPC
 298 Devices can implement any additional RPC and as long as it provides
 299 YANG models for it, it can be invoked from OpenDaylight. Following example shows how
 300 to invoke the get-schema RPC (get-schema is quite common among netconf
 301 devices). Invoke:
 302
 303 POST
 304 http://localhost:8181/restconf/operations/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/ietf-netconf-monitoring:get-schema
 305
 306 ----
 307 <input xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
 308   <identifier>ietf-yang-types</identifier>
 309   <version>2013-07-15</version>
 310 </input>
 311 ----
 312
 313 This call should fetch the source for ietf-yang-types YANG model from
 314 the mounted device.
 315
 316 ==== Netconf-connector + Netopeer
 317 https://github.com/cesnet/netopeer[Netopeer] (an open-source NETCONF server) can be used for
 318 testing/exploring NETCONF southbound in OpenDaylight.
 319
 320 ===== Netopeer installation
 321 https://www.docker.com/[Docker] container with netopeer will be used
 322 in this guid. To install docker and start the
 323 https://index.docker.io/u/dockeruser/netopeer/[netopeer image] perform
 324 following steps:
 325
 326 . Install docker http://docs.docker.com/linux/step_one/
 327 . Start the netopeer image:
 328 +
 329 ----
 330 docker run -rm -t -p 1831:830 dockeruser/netopeer
 331 ----
 332 . Verify netopeer is running by invoking (netopeer should send its
 333   HELLO message right away:
 334 +
 335 ----
 336 ssh root@localhost -p 1831 -s netconf
 337 (password root)
 338 ----
 339
 340 ===== Mounting netopeer NETCONF server
 341 Preconditions:
 342
 343 * OpenDaylight is started with features +odl-restconf-all+ and
 344   +odl-netconf-connector-all+.
 345 * Netopeer is up and running in docker
 346
 347 Now just follow the chapter:
 348 <<_spawning_additional_netconf_connectors_while_the_controller_is_running, Spawning netconf-connector>>. In the payload change the:
 349
 350 * name to e.g. netopeer
 351 * usernam/password to your system credentials
 352 * ip to localhost
 353 * port to 1831.
 354
 355 After netopeer is mounted successfully, its configuration can be read
 356 using RESTCONF by invoking:
 357
 358 GET
 359 http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/netopeer/yang-ext:mount/