docs/user-guide.rst

   1 .. _netconf-user-guide:
   2
   3 .. |ss| raw:: html
   4
   5    <strike>
   6
   7 .. |se| raw:: html
   8
   9    </strike>
  10
  11 NETCONF User Guide
  12 ==================
  13
  14 Overview
  15 --------
  16
  17 NETCONF is an XML-based protocol used for configuration and monitoring
  18 devices in the network. The base NETCONF protocol is described in
  19 `RFC-6241 <https://www.rfc-editor.org/rfc/rfc6241>`__.
  20
  21 **NETCONF in OpenDaylight:.**
  22
  23 OpenDaylight supports the NETCONF protocol as a northbound server as
  24 well as a southbound plugin. It also includes a set of test tools for
  25 simulating NETCONF devices and clients.
  26
  27 Southbound (netconf-connector)
  28 ------------------------------
  29
  30 The NETCONF southbound plugin is capable of connecting to remote NETCONF
  31 devices and exposing their configuration/operational datastores, RPCs
  32 and notifications as MD-SAL mount points. These mount points allow
  33 applications and remote users (over RESTCONF) to interact with the
  34 mounted devices.
  35
  36 In terms of RFCs, the connector supports:
  37
  38 -  `RFC-6241 <https://www.rfc-editor.org/rfc/rfc6241>`__
  39
  40 -  `RFC-5277 <https://www.rfc-editor.org/rfc/rfc5277>`__
  41
  42 -  `RFC-6022 <https://www.rfc-editor.org/rfc/rfc6022>`__
  43
  44 -  `RFC-7895 <https://www.rfc-editor.org/rfc/rfc7895>`__
  45
  46 **Netconf-connector is fully model-driven (utilizing the YANG modeling
  47 language) so in addition to the above RFCs, it supports any
  48 data/RPC/notifications described by a YANG model that is implemented by
  49 the device.**
  50
  51 .. tip::
  52
  53     NETCONF southbound can be activated by installing
  54     ``odl-netconf-connector-all`` Karaf feature.
  55
  56 .. _netconf-connector:
  57
  58 Netconf-connector configuration
  59 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  60
  61 NETCONF connectors are configured directly through the usage of the
  62 network-topology model. You can configure new NETCONF connectors both
  63 through the NETCONF server for MD-SAL (port 2830) or RESTCONF. This guide
  64 focuses on RESTCONF.
  65
  66 .. important::
  67
  68     Since 2022.09 Chlorine there is only one RESTCONF endpoint:
  69
  70     - | ``http://localhost:8181/rests`` is related to `RFC-8040 <https://www.rfc-editor.org/rfc/rfc8040>`__,
  71       | can be activated by installing ``odl-restconf-nb``
  72        Karaf feature.
  73
  74     | Resources for configuration and operational datastores start
  75      ``/rests/data/``,
  76     | e. g. GET
  77      http://localhost:8181/rests/data/network-topology:network-topology
  78      with response of both datastores. It's allowed to use query
  79      parameters to distinguish between them.
  80     | e. g. GET
  81      http://localhost:8181/rests/data/network-topology:network-topology?content=config
  82      for configuration datastore
  83     | and GET
  84      http://localhost:8181/rests/data/network-topology:network-topology?content=nonconfig
  85      for operational datastore.
  86
  87     | Also if a data node in the path expression is a YANG leaf-list or list
  88      node, the path segment has to be constructed by having leaf-list or
  89      list node name, followed by an "=" character, then followed by the
  90      leaf-list or list value. Any reserved characters must be
  91      percent-encoded.
  92     | e. g. GET
  93      http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf?content=config
  94      for retrieving data from configuration datastore for
  95      topology-netconf value of topology list.
  96
  97 Preconditions
  98 ^^^^^^^^^^^^^
  99
 100 1. OpenDaylight is running
 101
 102 2. In Karaf, you must have the ``odl-netconf-topology`` or
 103    ``odl-netconf-clustered-topology`` feature installed.
 104
 105 3. Feature ``odl-restconf-nb`` must be installed
 106
 107 Spawning new NETCONF connectors
 108 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 109
 110 To create a new NETCONF connector you need to send the following PUT request
 111 to RESTCONF:
 112
 113 .. list-table::
 114    :widths: 1 5
 115
 116    * - rfc8040
 117      - http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device
 118
 119 You could use the same body to create the new  NETCONF connector with a POST
 120 without specifying the node in the URL:
 121
 122 .. list-table::
 123    :widths: 1 5
 124
 125    * - rfc8040
 126      - http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf
 127
 128 Payload:
 129
 130 .. tabs::
 131
 132    .. tab:: XML
 133
 134       **Content-type:** ``application/xml``
 135
 136       **Accept:** ``application/xml``
 137
 138       **Authentication:** ``admin:admin``
 139
 140       .. code-block:: xml
 141
 142          <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
 143            <node-id>new-netconf-device</node-id>
 144            <host xmlns="urn:opendaylight:netconf-node-topology">127.0.0.1</host>
 145            <port xmlns="urn:opendaylight:netconf-node-topology">17830</port>
 146            <username xmlns="urn:opendaylight:netconf-node-topology">admin</username>
 147            <password xmlns="urn:opendaylight:netconf-node-topology">admin</password>
 148            <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
 149            <!-- non-mandatory fields with default values, you can safely remove these if you do not wish to override any of these values-->
 150            <reconnect-on-changed-schema xmlns="urn:opendaylight:netconf-node-topology">false</reconnect-on-changed-schema>
 151            <connection-timeout-millis xmlns="urn:opendaylight:netconf-node-topology">20000</connection-timeout-millis>
 152            <max-connection-attempts xmlns="urn:opendaylight:netconf-node-topology">0</max-connection-attempts>
 153            <between-attempts-timeout-millis xmlns="urn:opendaylight:netconf-node-topology">2000</between-attempts-timeout-millis>
 154            <sleep-factor xmlns="urn:opendaylight:netconf-node-topology">1.5</sleep-factor>
 155            <!-- keepalive-delay set to 0 turns off keepalives-->
 156            <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">120</keepalive-delay>
 157          </node>
 158
 159    .. tab:: JSON
 160
 161       **Content-type:** ``application/json``
 162
 163       **Accept:** ``application/json``
 164
 165       **Authentication:** ``admin:admin``
 166
 167       .. code-block:: json
 168
 169          {
 170              "node": [
 171                  {
 172                      "node-id": "new-netconf-device",
 173                      "netconf-node-topology:port": 17830,
 174                      "netconf-node-topology:reconnect-on-changed-schema": false,
 175                      "netconf-node-topology:connection-timeout-millis": 20000,
 176                      "netconf-node-topology:tcp-only": false,
 177                      "netconf-node-topology:max-connection-attempts": 0,
 178                      "netconf-node-topology:username": "admin",
 179                      "netconf-node-topology:password": "admin",
 180                      "netconf-node-topology:sleep-factor": 1.5,
 181                      "netconf-node-topology:host": "127.0.0.1",
 182                      "netconf-node-topology:between-attempts-timeout-millis": 2000,
 183                      "netconf-node-topology:keepalive-delay": 120
 184                  }
 185              ]
 186          }
 187
 188 Note that the device name in <node-id> element must match the last
 189 element of the restconf URL.
 190
 191 Reconfiguring an existing connector
 192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 193
 194 The steps to reconfigure an existing connector are exactly the same as
 195 when spawning a new connector. The old connection will be disconnected
 196 and a new connector with the new configuration will be created. This needs
 197 to be done with a PUT request because the node already exists. A POST
 198 request will fail for that reason.
 199
 200 Additionally, a PATCH request can be used to modify an existing
 201 configuration. Currently, only yang-patch (`RFC-8072 <https://www.rfc-editor.org/rfc/rfc8072>`__)
 202 is supported. The URL would be the same as the above PUT examples.
 203 Using JSON for the body, the headers needed for the request would
 204 be:
 205
 206 Headers:
 207
 208 -  Accept: application/yang-data+json
 209
 210 -  Content-Type: application/yang-patch+json
 211
 212 Example JSON payload to modify the password entry:
 213
 214 ::
 215
 216     {
 217       "ietf-restconf:yang-patch" : {
 218         "patch-id" : "0",
 219         "edit" : [
 220           {
 221             "edit-id" : "edit1",
 222             "operation" : "merge",
 223             "target" : "",
 224             "value" : {
 225              "node": [
 226                 {
 227                  "node-id": "new-netconf-device",
 228                  "netconf-node-topology:password" : "newpassword"
 229                 }
 230              ]
 231             }
 232          }
 233         ]
 234       }
 235     }
 236
 237 Deleting an existing connector
 238 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 239
 240 To remove an already configured NETCONF connector you need to send a
 241 DELETE request to the same PUT request URL that was used to create the
 242 device:
 243
 244 .. list-table::
 245    :widths: 1 5
 246
 247    * - rfc8040
 248      - http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device
 249
 250 .. note::
 251
 252     No body is needed to delete the node/device
 253
 254 Connecting to a device not supporting NETCONF monitoring
 255 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 256
 257 The netconf-connector in OpenDaylight relies on ietf-netconf-monitoring
 258 support when connecting to remote NETCONF device. The
 259 ietf-netconf-monitoring support allows netconf-connector to list and
 260 download all YANG schemas that are used by the device. NETCONF connector
 261 can only communicate with a device if it knows the set of used schemas
 262 (or at least a subset). However, some devices use YANG models internally
 263 but do not support NETCONF monitoring. Netconf-connector can also
 264 communicate with these devices, but you have to side load the necessary
 265 yang models into OpenDaylight’s YANG model cache for netconf-connector.
 266 In general there are 2 situations you might encounter:
 267
 268 **1. NETCONF device does not support ietf-netconf-monitoring but it does
 269 list all its YANG models as capabilities in HELLO message**
 270
 271 This could be a device that internally uses only ietf-inet-types YANG
 272 model with revision 2010-09-24. In the HELLO message that is sent from
 273 this device there is this capability reported:
 274
 275 ::
 276
 277     urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2010-09-24
 278
 279 **For such devices you only need to put the schema into folder
 280 cache/schema inside your Karaf distribution.**
 281
 282 .. important::
 283
 284     The file with YANG schema for ietf-inet-types has to be called
 285     ietf-inet-types@2010-09-24.yang. It is the required naming format of
 286     the cache.
 287
 288 **2. NETCONF device does not support ietf-netconf-monitoring and it does
 289 NOT list its YANG models as capabilities in HELLO message**
 290
 291 Compared to device that lists its YANG models in HELLO message, in this
 292 case there would be no capability with ietf-inet-types in the HELLO
 293 message. This type of device basically provides no information about the
 294 YANG schemas it uses so its up to the user of OpenDaylight to properly
 295 configure netconf-connector for this device.
 296
 297 Netconf-connector has an optional configuration attribute called
 298 yang-module-capabilities and this attribute can contain a list of "YANG
 299 module based" capabilities. So by setting this configuration attribute,
 300 it is possible to override the "yang-module-based" capabilities reported
 301 in HELLO message of the device. To do this, we need to modify the
 302 configuration of netconf-connector like in the example below:
 303
 304 .. tabs::
 305
 306    .. tab:: XML
 307
 308       **Content-type:** ``application/xml``
 309
 310       **Accept:** ``application/xml``
 311
 312       **Authentication:** ``admin:admin``
 313
 314       .. code-block:: xml
 315
 316          <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
 317            <node-id>r5</node-id>
 318            <host xmlns="urn:opendaylight:netconf-node-topology">127.0.0.1</host>
 319            <port xmlns="urn:opendaylight:netconf-node-topology">8305</port>
 320            <username xmlns="urn:opendaylight:netconf-node-topology">root</username>
 321            <password xmlns="urn:opendaylight:netconf-node-topology">root</password>
 322            <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
 323            <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">30</keepalive-delay>
 324            <yang-module-capabilities xmlns="urn:opendaylight:netconf-node-topology">
 325              <override>true</override>
 326              <capability xmlns="urn:opendaylight:netconf-node-topology">
 327                urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&amp;revision=2013-07-15
 328              </capability>
 329            </yang-module-capabilities>
 330          </node>
 331
 332    .. tab:: JSON
 333
 334       **Content-type:** ``application/json``
 335
 336       **Accept:** ``application/json``
 337
 338       **Authentication:** ``admin:admin``
 339
 340       .. code-block:: json
 341
 342          {
 343              "node": [
 344                  {
 345                      "node-id": "device",
 346                      "netconf-node-topology:host": "127.0.0.1",
 347                      "netconf-node-topology:password": "root",
 348                      "netconf-node-topology:username": "root",
 349                      "netconf-node-topology:yang-module-capabilities": {
 350                          "override": true,
 351                          "capability": [
 352                              "urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15"
 353                          ]
 354                      },
 355                      "netconf-node-topology:port": 8305,
 356                      "netconf-node-topology:tcp-only": false,
 357                      "netconf-node-topology:keepalive-delay": 30
 358                  }
 359              ]
 360          }
 361
 362 **Remember to also put the YANG schemas into the cache folder.**
 363
 364 .. note::
 365
 366     For putting multiple capabilities, you just need to replicate the
 367     capability element inside yang-module-capability element.
 368     Capability element is modeled as a leaf-list. With this
 369     configuration, we would make the remote device report usage of
 370     ietf-inet-types in the eyes of netconf-connector.
 371
 372 Connecting to a device supporting only NETCONF 1.0
 373 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 374
 375 OpenDaylight is schema-based distribution and heavily depends on YANG
 376 models. However some legacy NETCONF devices are not schema-based and
 377 implement just RFC 4741. This type of device does not utilize YANG
 378 models internally and OpenDaylight does not know how to communicate
 379 with such devices, how to validate data, or what the semantics of data
 380 are.
 381
 382 NETCONF connector can communicate also with these devices, but the
 383 trade-offs are worsened possibilities in utilization of NETCONF
 384 mountpoints. Using RESTCONF with such devices is not supported. Also
 385 communicating with schemaless devices from application code is slightly
 386 different.
 387
 388 To connect to schemaless device, there is a optional configuration option
 389 in netconf-node-topology model called schemaless. You have to set this
 390 option to true.
 391
 392 Clustered NETCONF connector
 393 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 394
 395 To spawn NETCONF connectors that are cluster-aware you need to install
 396 the ``odl-netconf-clustered-topology`` karaf feature.
 397
 398 .. warning::
 399
 400     The ``odl-netconf-topology`` and ``odl-netconf-clustered-topology``
 401     features are considered **INCOMPATIBLE**. They both manage the same
 402     space in the datastore and would issue conflicting writes if
 403     installed together.
 404
 405 Configuration of clustered NETCONF connectors works the same as the
 406 configuration through the topology model in the previous section.
 407
 408 When a new clustered connector is configured the configuration gets
 409 distributed among the member nodes and a NETCONF connector is spawned on
 410 each node. From these nodes a master is chosen which handles the schema
 411 download from the device and all the communication with the device. You
 412 will be able to read/write to/from the device from all slave nodes due
 413 to the proxy data brokers implemented.
 414
 415 You can use the ``odl-netconf-clustered-topology`` feature in a single
 416 node scenario as well but the code that uses akka will be used, so for a
 417 scenario where only a single node is used, ``odl-netconf-topology``
 418 might be preferred.
 419
 420 Netconf-connector utilization
 421 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 422
 423 Once the connector is up and running, users can utilize the new mount
 424 point instance. By using RESTCONF or from their application code. This
 425 chapter deals with using RESTCONF and more information for app
 426 developers can be found in the developers guide or in the official
 427 tutorial application **ncmount** that can be found in the coretutorials
 428 project:
 429
 430 -  https://github.com/opendaylight/coretutorials/tree/master/ncmount
 431
 432 Reading data from the device
 433 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 434
 435 Just invoke (no body needed):
 436
 437 GET
 438 http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device/yang-ext:mount?content=nonconfig
 439
 440 This will return the entire content of operation datastore from the
 441 device. To view just the configuration datastore, change **nonconfig**
 442 in this URL to **config**.
 443
 444 Writing configuration data to the device
 445 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 446
 447 In general, you cannot simply write any data you want to the device. The
 448 data have to conform to the YANG models implemented by the device. In
 449 this example we are adding a new interface-configuration to the mounted
 450 device (assuming the device supports Cisco-IOS-XR-ifmgr-cfg YANG model).
 451 In fact this request comes from the tutorial dedicated to the
 452 **ncmount** tutorial app.
 453
 454 POST
 455 http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device/yang-ext:mount/Cisco-IOS-XR-ifmgr-cfg:interface-configurations
 456
 457 ::
 458
 459     <interface-configuration xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ifmgr-cfg">
 460         <active>act</active>
 461         <interface-name>mpls</interface-name>
 462         <description>Interface description</description>
 463         <bandwidth>32</bandwidth>
 464         <link-status></link-status>
 465     </interface-configuration>
 466
 467 Should return 200 response code with no body.
 468
 469 .. tip::
 470
 471     This call is transformed into a couple of NETCONF RPCs. Resulting
 472     NETCONF RPCs that go directly to the device can be found in the
 473     OpenDaylight logs after invoking ``log:set TRACE
 474     org.opendaylight.controller.sal.connect.netconf`` in the Karaf
 475     shell. Seeing the NETCONF RPCs might help with debugging.
 476
 477 This request is very similar to the one where we spawned a new netconf
 478 device. That’s because we used the loopback netconf-connector to write
 479 configuration data into config-subsystem datastore and config-subsystem
 480 picked it up from there.
 481
 482 Invoking custom RPC
 483 ^^^^^^^^^^^^^^^^^^^
 484
 485 Devices can implement any additional RPC and as long as it provides YANG
 486 models for it, it can be invoked from OpenDaylight. Following example
 487 shows how to invoke the get-schema RPC (get-schema is quite common among
 488 netconf devices). Invoke:
 489
 490 POST
 491 http://localhost:8181/rests/operations/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device/yang-ext:mount/ietf-netconf-monitoring:get-schema
 492
 493 ::
 494
 495     <input xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
 496       <identifier>ietf-yang-types</identifier>
 497       <version>2013-07-15</version>
 498     </input>
 499
 500 This call should fetch the source for ietf-yang-types YANG model from
 501 the mounted device.
 502
 503 Receiving Netconf Device Notifications on a http client
 504 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 505
 506 Devices emit netconf alarms and notifications in certain situations, which can demand
 507 attention from Device Administration. The notifications are received as Netconf messages on an
 508 active Netconf session.
 509
 510 Opendaylight provides the way to stream the device notifications over a http session.
 511
 512 - Step 1: Mount the device (assume node name is test_device)
 513
 514 - Step 2: Wait for the device to be connected.
 515
 516 - Step 3: Create the Subscription for notification on the active session.
 517
 518  .. code-block::
 519
 520     POST
 521     http://localhost:8181/rests/operations/network-topology:network-topology/topology=topology-netconf/node=test_device/yang-ext:mount/notifications:create-subscription
 522     Content-Type: application/json
 523     Accept: application/json
 524
 525  .. code-block:: json
 526
 527     {
 528       "input": {
 529         "stream": "NETCONF"
 530        }
 531     }
 532
 533 - Step 4: Create the http Stream for the events.
 534
 535 .. code-block::
 536
 537     POST
 538     http://localhost:8181/rests/operations/odl-device-notification:subscribe-device-notification
 539     Content-Type: application/json
 540     Accept: application/json
 541
 542 .. code-block:: json
 543
 544     {
 545       "input": {
 546          "path":"/network-topology:network-topology/topology[topology-id='topology-netconf']/node[node-id='test_device']"
 547       }
 548     }
 549
 550 The response suggests the http url for reading the notifications.
 551
 552 .. code-block:: json
 553
 554     {
 555        "odl-device-notification:output": {
 556             "stream-path": "http://localhost:8181/rests/notif/test_device?notificationType=test_device"
 557         }
 558     }
 559
 560 - Step 5: User can access the url in the response and the notifications will be as follows.
 561
 562 .. code-block::
 563
 564     GET
 565     http://localhost:8181/rests/notif/test_device?notificationType=test_device
 566     Content-Type: application/xml
 567     Accept: application/xml
 568
 569
 570 .. code-block:: xml
 571
 572     : ping
 573
 574     : ping
 575
 576     : ping
 577
 578     : ping
 579
 580     : ping
 581
 582     data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"><eventTime>2022-06-17T07:01:08.60228Z</eventTime><netconf-session-start xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"><username>root</username><source-host>127.0.0.1</source-host><session-id>2</session-id></netconf-session-start></notification>
 583
 584     data: <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"><eventTime>2022-06-17T07:01:12.458258Z</eventTime><netconf-session-end xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"><username>root</username><source-host>127.0.0.1</source-host><termination-reason>closed</termination-reason><session-id>2</session-id></netconf-session-end></notification>
 585
 586 Change event notification subscription tutorial
 587 -----------------------------------------------
 588
 589 Subscribing to data change notifications makes it possible to obtain
 590 notifications about data manipulation (insert, change, delete) which are
 591 done on any specified **path** of any specified **datastore** with
 592 specific **scope**. In following examples *{odlAddress}* is address of
 593 server where ODL is running and *{odlPort}* is port on which
 594 OpenDaylight is running. OpenDaylight offers two methods for receiving notifications:
 595 Server-Sent Events (SSE) and WebSocket. SSE is the default notification mechanism used in OpenDaylight.
 596
 597 SSE notifications subscription process
 598 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 599
 600 In this section we will learn what steps need to be taken in order to
 601 successfully subscribe to data change event notifications.
 602
 603 Create stream
 604 ^^^^^^^^^^^^^
 605
 606 In order to use event notifications you first need to call RPC that
 607 creates notification stream that you can later listen to. You need to
 608 provide three parameters to this RPC:
 609
 610 -  **path**: data store path that you plan to listen to. You can
 611    register listener on containers, lists and leaves.
 612
 613 -  **datastore**: data store type. *OPERATIONAL* or *CONFIGURATION*.
 614
 615 -  **scope**: Represents scope of data change. Possible options are:
 616
 617    -  BASE: only changes directly to the data tree node specified in the
 618       path will be reported
 619
 620    -  ONE: changes to the node and to direct child nodes will be
 621       reported
 622
 623    -  SUBTREE: changes anywhere in the subtree starting at the node will
 624       be reported
 625
 626 The RPC to create the stream can be invoked via RESTCONF like this:
 627
 628 ::
 629
 630     OPERATION: POST
 631     URI:  http://{odlAddress}:{odlPort}/rests/operations/sal-remote:create-data-change-event-subscription
 632     HEADER: Content-Type=application/json
 633             Accept=application/json
 634
 635 .. code-block:: json
 636
 637        {
 638            "input": {
 639                "path": "/toaster:toaster/toaster:toasterStatus",
 640                "sal-remote-augment:datastore": "OPERATIONAL",
 641                "sal-remote-augment:scope": "ONE"
 642            }
 643        }
 644
 645 The response should look something like this:
 646
 647 .. code-block:: json
 648
 649     {
 650         "sal-remote:output": {
 651             "stream-name": "data-change-event-subscription/toaster:toaster/toaster:toasterStatus/datastore=CONFIGURATION/scope=SUBTREE"
 652         }
 653     }
 654
 655 **stream-name** is important because you will need to use it when you
 656 subscribe to the stream in the next step.
 657
 658 .. note::
 659
 660     Internally, this will create a new listener for *stream-name* if it
 661     did not already exist.
 662
 663 Subscribe to stream
 664 ^^^^^^^^^^^^^^^^^^^
 665
 666 In order to subscribe to stream and obtain SSE location you need
 667 to call *GET* on your stream path. The URI should generally be
 668 `http://{odlAddress}:{odlPort}/rests/data/ietf-restconf-monitoring:restconf-state/streams/stream/{streamName}`,
 669 where *{streamName}* is the *stream-name* parameter contained in
 670 response from *create-data-change-event-subscription* RPC from the
 671 previous step.
 672
 673 ::
 674
 675    OPERATION: GET
 676    URI: http://{odlAddress}:{odlPort}/rests/data/ietf-restconf-monitoring:restconf-state/streams/stream/data-change-event-subscription/toaster:toaster/datastore=CONFIGURATION/scope=SUBTREE
 677
 678 The subscription call may be modified with the following query parameters defined in the RESTCONF RFC:
 679
 680 -  `filter <https://www.rfc-editor.org/rfc/rfc8040#section-4.8.4>`__
 681
 682 -  `start-time <https://www.rfc-editor.org/rfc/rfc8040#section-4.8.7>`__
 683
 684 -  `end-time <https://www.rfc-editor.org/rfc/rfc8040#section-4.8.8>`__
 685
 686 In addition, the following ODL extension query parameter is supported:
 687
 688 :odl-leaf-nodes-only:
 689   If this parameter is set to "true", create and update notifications will only
 690   contain the leaf nodes modified instead of the entire subscription subtree.
 691   This can help in reducing the size of the notifications.
 692
 693 :odl-skip-notification-data:
 694   If this parameter is set to "true", create and update notifications will only
 695   contain modified leaf nodes without data.
 696   This can help in reducing the size of the notifications.
 697
 698 The response should look something like this:
 699
 700 .. code-block:: json
 701
 702     {
 703         "subscribe-to-notification:location": "http://localhost:8181/rests/notif/data-change-event-subscription/network-topology:network-topology/datastore=CONFIGURATION/scope=SUBTREE"
 704     }
 705
 706 .. note::
 707
 708     During this phase there is an internal check for to see if a
 709     listener for the *stream-name* from the URI exists. If not, new a
 710     new listener is registered with the DOM data broker.
 711
 712 Receive notifications
 713 ^^^^^^^^^^^^^^^^^^^^^
 714
 715 Once you got SSE location you can now connect to it and
 716 start receiving data change events. The request should look something like this:
 717
 718 ::
 719
 720     curl -v -X GET  http://localhost:8181/rests/notif/data-change-event-subscription/toaster:toaster/toasterStatus/datastore=OPERATIONAL/scope=ONE  -H "Content-Type: text/event-stream" -H "Authorization: Basic YWRtaW46YWRtaW4="
 721
 722
 723 WebSocket notifications subscription process
 724 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 725
 726 Enabling WebSocket notifications in OpenDaylight requires a manual setup before starting the application.
 727 The following steps can be followed to enable WebSocket notifications in OpenDaylight:
 728
 729 1. Open the file `restconf8040.cfg`, at `etc/` folder inside your Karaf distribution.
 730 2. Locate the `use-sse` configuration parameter and change its value from `true` to `false`.
 731 3. Uncomment the `use-sse` parameter if it is commented out.
 732 4. Save the changes made to the `restconf8040.cfg` file.
 733 5. Restart OpenDaylight if it is already running.
 734
 735 Once these steps are completed, WebSocket notifications will be enabled in OpenDaylight,
 736 and they can be used for receiving notifications instead of SSE.
 737
 738 WebSocket Notifications subscription process is the same as SSE until you receive a location of WebSocket.
 739 You can follow steps given above and after subscribing to a notification stream over WebSocket,
 740 you will receive a response indicating that the subscription was successful:
 741
 742 .. code-block:: json
 743
 744     {
 745         "subscribe-to-notification:location": "ws://localhost:8181/rests/notif/data-change-event-subscription/network-topology:network-topology/datastore=CONFIGURATION/scope=SUBTREE"
 746     }
 747
 748 You can use this WebSocket to listen to data
 749 change notifications. To listen to notifications you can use a
 750 JavaScript client or if you are using chrome browser you can use the
 751 `Simple WebSocket
 752 Client <https://chrome.google.com/webstore/detail/simple-websocket-client/pfdhoblngboilpfeibdedpjgfnlcodoo>`__.
 753
 754 Also, for testing purposes, there is simple Java application named
 755 WebSocketClient. The application is placed in the
 756 */restconf/websocket-client* project. It accepts a WebSocket URI
 757 as an input parameter. After starting the utility (WebSocketClient
 758 class directly in Eclipse/InteliJ Idea) received notifications should be
 759 displayed in console.
 760
 761 Notifications are always in XML format and look like this:
 762
 763 .. code-block:: xml
 764
 765     <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 766         <eventTime>2014-09-11T09:58:23+02:00</eventTime>
 767         <data-changed-notification xmlns="urn:opendaylight:params:xml:ns:yang:controller:md:sal:remote">
 768             <data-change-event>
 769                 <path xmlns:meae="http://netconfcentral.org/ns/toaster">/meae:toaster</path>
 770                 <operation>updated</operation>
 771                 <data>
 772                    <!-- updated data -->
 773                 </data>
 774             </data-change-event>
 775         </data-changed-notification>
 776     </notification>
 777
 778 Example use case
 779 ~~~~~~~~~~~~~~~~
 780
 781 The typical use case is listening to data change events to update web
 782 page data in real time. In this tutorial we will be using toaster as the
 783 base.
 784
 785 When you call *make-toast* RPC, it sets *toasterStatus* to "down" to
 786 reflect that the toaster is busy making toast. When it finishes,
 787 *toasterStatus* is set to "up" again. We will listen to these toaster
 788 status changes in data store and will reflect it on our web page in
 789 real-time thanks to WebSocket data change notification.
 790
 791 Simple javascript client implementation
 792 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 793
 794 We will create a simple JavaScript web application that will listen for
 795 updates on *toasterStatus* leaf and update some elements of our web page
 796 according to the new toaster status state.
 797
 798 Create stream
 799 ^^^^^^^^^^^^^
 800
 801 First you need to create stream that you are planning to subscribe to.
 802 This can be achieved by invoking "create-data-change-event-subscription"
 803 RPC on RESTCONF via AJAX request. You need to provide data store
 804 **path** that you plan to listen on, **data store type** and **scope**.
 805 If the request is successful you can extract the **stream-name** from
 806 the response and use that to subscribe to the newly created stream. The
 807 *{username}* and *{password}* fields represent the credentials that you
 808 use to connect to OpenDaylight via RESTCONF:
 809
 810 .. note::
 811
 812     The default user name and password are "admin".
 813
 814 .. code-block:: javascript
 815
 816     function createStream() {
 817         $.ajax(
 818             {
 819                 url: 'http://{odlAddress}:{odlPort}/rests/operations/sal-remote:create-data-change-event-subscription',
 820                 type: 'POST',
 821                 headers: {
 822                   'Authorization': 'Basic ' + btoa('{username}:{password}'),
 823                   'Content-Type': 'application/json'
 824                 },
 825                 data: JSON.stringify(
 826                     {
 827                         'input': {
 828                             'path': '/toaster:toaster/toaster:toasterStatus',
 829                             'sal-remote-augment:datastore': 'OPERATIONAL',
 830                             'sal-remote-augment:scope': 'ONE'
 831                         }
 832                     }
 833                 )
 834             }).done(function (data) {
 835                 // this function will be called when ajax call is executed successfully
 836                 subscribeToStream(data.output['stream-name']);
 837             }).fail(function (data) {
 838                 // this function will be called when ajax call fails
 839                 console.log("Create stream call unsuccessful");
 840             })
 841     }
 842
 843 Subscribe to stream
 844 ^^^^^^^^^^^^^^^^^^^
 845
 846 The Next step is to subscribe to the stream. To subscribe to the stream
 847 you need to call *GET* on
 848 *http://{odlAddress}:{odlPort}/rests/data/ietf-restconf-monitoring:restconf-state/streams/stream/{stream-name}*.
 849 If the call is successful, you get WebSocket address for this stream in
 850 **Location** parameter inside response header. You can get response
 851 header by calling *getResponseHeader(\ *Location*)* on HttpRequest
 852 object inside *done()* function call:
 853
 854 .. code-block:: javascript
 855
 856     function subscribeToStream(streamName) {
 857         $.ajax(
 858             {
 859                 url: 'http://{odlAddress}:{odlPort}/rests/data/ietf-restconf-monitoring:restconf-state/streams/stream/' + streamName;
 860                 type: 'GET',
 861                 headers: {
 862                   'Authorization': 'Basic ' + btoa('{username}:{password}'),
 863                 }
 864             }
 865         ).done(function (data, textStatus, httpReq) {
 866             // we need function that has http request object parameter in order to access response headers.
 867             listenToNotifications(httpReq.getResponseHeader('Location'));
 868         }).fail(function (data) {
 869             console.log("Subscribe to stream call unsuccessful");
 870         });
 871     }
 872
 873 Receive notifications
 874 ^^^^^^^^^^^^^^^^^^^^^
 875
 876 Once you have WebSocket server location you can now connect to it and
 877 start receiving data change events. You need to define functions that
 878 will handle events on WebSocket. In order to process incoming events
 879 from OpenDaylight you need to provide a function that will handle
 880 *onmessage* events. The function must have one parameter that represents
 881 the received event object. The event data will be stored in
 882 *event.data*. The data will be in an XML format that you can then easily
 883 parse using jQuery.
 884
 885 .. code-block:: javascript
 886
 887     function listenToNotifications(socketLocation) {
 888         try {
 889             var notificatinSocket = new WebSocket(socketLocation);
 890
 891             notificatinSocket.onmessage = function (event) {
 892                 // we process our received event here
 893                 console.log('Received toaster data change event.');
 894                 $($.parseXML(event.data)).find('data-change-event').each(
 895                     function (index) {
 896                         var operation = $(this).find('operation').text();
 897                         if (operation == 'updated') {
 898                             // toaster status was updated so we call function that gets the value of toasterStatus leaf
 899                             updateToasterStatus();
 900                             return false;
 901                         }
 902                     }
 903                 );
 904             }
 905             notificatinSocket.onerror = function (error) {
 906                 console.log("Socket error: " + error);
 907             }
 908             notificatinSocket.onopen = function (event) {
 909                 console.log("Socket connection opened.");
 910             }
 911             notificatinSocket.onclose = function (event) {
 912                 console.log("Socket connection closed.");
 913             }
 914             // if there is a problem on socket creation we get exception (i.e. when socket address is incorrect)
 915         } catch(e) {
 916             alert("Error when creating WebSocket" + e );
 917         }
 918     }
 919
 920 The *updateToasterStatus()* function represents function that calls
 921 *GET* on the path that was modified and sets toaster status in some web
 922 page element according to received data. After the WebSocket connection
 923 has been established you can test events by calling make-toast RPC via
 924 RESTCONF.
 925
 926 .. note::
 927
 928     for more information about WebSockets in JavaScript visit `Writing
 929     WebSocket client
 930     applications <https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications>`__
 931
 932 Netconf-connector + Netopeer
 933 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 934
 935 `Netopeer <https://github.com/cesnet/netopeer>`__ (an open-source
 936 NETCONF server) can be used for testing/exploring NETCONF southbound in
 937 OpenDaylight.
 938
 939 Netopeer installation
 940 ^^^^^^^^^^^^^^^^^^^^^
 941
 942 A `Docker <https://www.docker.com/>`__ container with netopeer will be
 943 used in this guide. To install Docker and start the `netopeer
 944 image <https://hub.docker.com/r/sysrepo/sysrepo-netopeer2>`__ perform
 945 following steps:
 946
 947 1. Install docker https://docs.docker.com/get-started/
 948
 949 2. Start the netopeer image:
 950
 951    ::
 952
 953        docker run -it --name sysrepo -p 830:830 --rm sysrepo/sysrepo-netopeer2:latest
 954
 955 3. Verify netopeer is running by invoking (netopeer should send its
 956    HELLO message right away:
 957
 958    ::
 959
 960        ssh root@localhost -p 830 -s netconf
 961        (password root)
 962
 963 Mounting netopeer NETCONF server
 964 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 965
 966 Preconditions:
 967
 968 -  OpenDaylight is started with features ``odl-restconf-all`` and
 969    ``odl-netconf-connector-all``.
 970
 971 -  Netopeer is up and running in docker
 972
 973 Now just follow the section: `Spawning new NETCONF connectors`_.
 974 In the payload change the:
 975
 976 -  name, e.g., to netopeer
 977
 978 -  username/password to your system credentials
 979
 980 -  ip to localhost
 981
 982 -  port to 1831.
 983
 984 After netopeer is mounted successfully, its configuration can be read
 985 using RESTCONF by invoking:
 986
 987 GET
 988 http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=netopeer/yang-ext:mount?content:config
 989
 990 Northbound (NETCONF servers)
 991 ----------------------------
 992
 993 OpenDaylight provides 2 types of NETCONF servers:
 994
 995 -  **NETCONF server for config-subsystem (listening by default on port
 996    1830)**
 997
 998    -  Serves as a default interface for config-subsystem and allows
 999       users to spawn/reconfigure/destroy modules (or applications) in
1000       OpenDaylight
1001
1002 -  **NETCONF server for MD-SAL (listening by default on port 2830)**
1003
1004    -  Serves as an alternative interface for MD-SAL (besides RESTCONF)
1005       and allows users to read/write data from MD-SAL’s datastore and to
1006       invoke its rpcs (NETCONF notifications are not available in the
1007       Boron release of OpenDaylight)
1008
1009 .. note::
1010
1011     The reason for having 2 NETCONF servers is that config-subsystem and
1012     MD-SAL are 2 different components of OpenDaylight and require
1013     different approaches for NETCONF message handling and data
1014     translation. These 2 components will probably merge in the future.
1015
1016 .. note::
1017
1018     Since Nitrogen release, there has been performance regression in NETCONF
1019     servers accepting SSH connections. While opening a connection takes
1020     less than 10 seconds on Carbon, on Nitrogen time can increase up to
1021     60 seconds. Please see https://jira.opendaylight.org/browse/ODLPARENT-112
1022
1023 NETCONF server for config-subsystem
1024 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1025
1026 This NETCONF server is the primary interface for config-subsystem. It
1027 allows the users to interact with config-subsystem in a standardized
1028 NETCONF manner.
1029
1030 In terms of RFCs, these are supported:
1031
1032 -  `RFC-6241 <https://www.rfc-editor.org/rfc/rfc6241>`__
1033
1034 -  `RFC-5277 <https://www.rfc-editor.org/rfc/rfc5277>`__
1035
1036 -  `RFC-6470 <https://www.rfc-editor.org/rfc/rfc6470>`__
1037
1038    -  (partially, only the schema-change notification is available in
1039       Boron release)
1040
1041 -  `RFC-6022 <https://www.rfc-editor.org/rfc/rfc6022>`__
1042
1043 For regular users it is recommended to use RESTCONF + the
1044 controller-config loopback mountpoint instead of using pure NETCONF. How
1045 to do that is specific for each component/module/application in
1046 OpenDaylight and can be found in their dedicated user guides.
1047
1048 NETCONF server for MD-SAL
1049 ~~~~~~~~~~~~~~~~~~~~~~~~~
1050
1051 This NETCONF server is just a generic interface to MD-SAL in
1052 OpenDaylight. It uses the standard MD-SAL APIs and serves as an
1053 alternative to RESTCONF. It is fully model-driven and supports any data
1054 and rpcs that are supported by MD-SAL.
1055
1056 In terms of RFCs, these are supported:
1057
1058 -  `RFC-6241 <https://www.rfc-editor.org/rfc/rfc6241>`__
1059
1060 -  `RFC-6022 <https://www.rfc-editor.org/rfc/rfc6022>`__
1061
1062 -  `RFC-7895 <https://www.rfc-editor.org/rfc/rfc7895>`__
1063
1064 Notifications over NETCONF are not supported in the Boron release.
1065
1066 .. tip::
1067
1068     Install NETCONF northbound for MD-SAL by installing feature:
1069     ``odl-netconf-mdsal`` in karaf. Default binding port is **2830**.
1070
1071 Configuration
1072 ^^^^^^^^^^^^^
1073
1074 The default configuration can be found in file: *08-netconf-mdsal.xml*.
1075 The file contains the configuration for all necessary dependencies and a
1076 single SSH endpoint starting on port 2830. There is also a (by default
1077 disabled) TCP endpoint. It is possible to start multiple endpoints at
1078 the same time either in the initial configuration file or while
1079 OpenDaylight is running.
1080
1081 The credentials for SSH endpoint can also be configured here, the
1082 defaults are admin/admin. Credentials in the SSH endpoint are not yet
1083 managed by the centralized AAA component and have to be configured
1084 separately.
1085
1086 Verifying MD-SAL’s NETCONF server
1087 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1088
1089 After the NETCONF server is available it can be examined by a command
1090 line ssh tool:
1091
1092 ::
1093
1094     ssh admin@localhost -p 2830 -s netconf
1095
1096 The server will respond by sending its HELLO message and can be used as
1097 a regular NETCONF server from then on.
1098
1099 Mounting the MD-SAL’s NETCONF server
1100 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1101
1102 To perform this operation, just spawn a new netconf-connector as
1103 described in `Spawning new NETCONF connectors`_. Just change the ip to
1104 "127.0.0.1" port to "2830" and its name to "controller-mdsal".
1105
1106 Now the MD-SAL’s datastore can be read over RESTCONF via NETCONF by
1107 invoking:
1108
1109 GET
1110 http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=controller-mdsal/yang-ext:mount?content:nonconfig
1111
1112 .. note::
1113
1114     This might not seem very useful, since MD-SAL can be accessed
1115     directly from RESTCONF or from Application code, but the same method
1116     can be used to mount and control other OpenDaylight instances by the
1117     "master OpenDaylight".
1118
1119 NETCONF stress/performance measuring tool
1120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1121
1122 This is basically a NETCONF client that puts NETCONF servers under heavy
1123 load of NETCONF RPCs and measures the time until a configurable amount
1124 of them is processed.
1125
1126 RESTCONF stress-performance measuring tool
1127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1128
1129 Very similar to NETCONF stress tool with the difference of using
1130 RESTCONF protocol instead of NETCONF.
1131
1132 YANGLIB remote repository
1133 -------------------------
1134
1135 There are scenarios in NETCONF deployment, that require for a centralized
1136 YANG models repository. YANGLIB plugin provides such remote repository.
1137
1138 To start this plugin, you have to install odl-yanglib feature. Then you
1139 have to configure YANGLIB either through RESTCONF or NETCONF. We will
1140 show how to configure YANGLIB through RESTCONF.
1141
1142 YANGLIB configuration
1143 ~~~~~~~~~~~~~~~~~~~~~
1144 YANGLIB configuration works through OSGi Configuration Admin interface, in the
1145 ``org.opendaylight.netconf.yanglib`` configuration PID. There are three tuneables you can
1146 set:
1147
1148 * ``cache-folder``, which defaults to ``cache/schema``
1149 * ``binding-address``, which defaults to ``localhost``
1150 * ``binding-port``, which defaults to ``8181``
1151
1152 In order to change these settings, you can either modify the corresponding configuration
1153 file, ``etc/org.opendaylight.netconf.yanglib.cfg``, for example:
1154
1155 ::
1156     cache-folder = cache/newSchema
1157     binding-address = localhost
1158     binding-port = 8181
1159
1160 Or use Karaf CLI:
1161
1162 ::
1163     opendaylight-user@root>config:edit org.opendaylight.netconf.yanglib
1164     opendaylight-user@root>config:property-set cache-folder cache/newSchema
1165     opendaylight-user@root>config:property-set binding-address localhost
1166     opendaylight-user@root>config:property-set binding-port 8181
1167     opendaylight-user@root>config:update
1168
1169 This YANGLIB takes all YANG sources from the configured sources folder and
1170 for each generates URL in form:
1171
1172 ::
1173
1174     http://localhost:8181/yanglib/schemas/{modelName}/{revision}
1175
1176 On this URL will be hosted YANG source for particular module.
1177
1178 YANGLIB instance also writes this URL along with source identifier to
1179 ietf-netconf-yang-library/modules-state/module list.
1180
1181 Netconf-connector with YANG library as fallback
1182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1183
1184 There is an optional configuration in netconf-connector called
1185 yang-library. You can specify YANG library to be plugged as additional
1186 source provider into the mount's schema repository. Since YANGLIB
1187 plugin is advertising provided modules through yang-library model, we
1188 can use it in mount point's configuration as YANG library.  To do this,
1189 we need to modify the configuration of netconf-connector by adding this
1190 XML
1191
1192 ::
1193
1194     <yang-library xmlns="urn:opendaylight:netconf-node-topology">
1195       <yang-library-url xmlns="urn:opendaylight:netconf-node-topology">http://localhost:8181/rests/data/ietf-yang-library:modules-state</yang-library-url>
1196       <username xmlns="urn:opendaylight:netconf-node-topology">admin</username>
1197       <password xmlns="urn:opendaylight:netconf-node-topology">admin</password>
1198     </yang-library>
1199
1200 This will register YANGLIB provided sources as a fallback schemas for
1201 particular mount point.
1202
1203 NETCONF Call Home
1204 -----------------
1205
1206 Call Home Installation
1207 ~~~~~~~~~~~~~~~~~~~~~~
1208
1209 ODL Call-Home server is installed in Karaf by installing karaf feature
1210 ``odl-netconf-callhome-ssh``. RESTCONF feature is recommended for
1211 configuring Call Home & testing its functionality.
1212
1213 ::
1214
1215   feature:install odl-netconf-callhome-ssh
1216
1217
1218 .. note::
1219
1220     In order to test Call Home functionality we recommend Netopeer or
1221     Netopeer2. See `Netopeer Call Home <https://github.com/CESNET/netopeer/wiki/CallHome>`__
1222     or `Netopeer2 <https://github.com/CESNET/netopeer2>`__ to learn how to
1223     enable call-home on Netopeer.
1224
1225 Northbound Call-Home API
1226 ~~~~~~~~~~~~~~~~~~~~~~~~
1227
1228 The northbound Call Home API is used for administering the Call-Home Server. The
1229 following describes this configuration.
1230
1231 Global Configuration
1232 ^^^^^^^^^^^^^^^^^^^^
1233
1234 .. important::
1235   The global configuration is not a part of the `RFC 8071
1236   <https://www.rfc-editor.org/rfc/rfc8071>`__ and, therefore, subject to change.
1237
1238 Configuring global credentials
1239 ''''''''''''''''''''''''''''''
1240
1241 The ODL Call-Home server allows user to configure global credentials, which will be
1242 used for devices connecting over SSH transport protocol that do not have
1243 device-specific credentials configured.
1244
1245 This is done by creating
1246 ``/odl-netconf-callhome-server:netconf-callhome-server/global/credentials``
1247 with username and passwords specified.
1248
1249 *Configuring global username & passwords to try*
1250
1251 .. code-block::
1252
1253     PUT HTTP/1.1
1254     /rests/data/odl-netconf-callhome-server:netconf-callhome-server/global/credentials
1255     Content-Type: application/json
1256     Accept: application/json
1257
1258 .. code-block:: json
1259
1260     {
1261       "credentials":
1262       {
1263         "username": "example",
1264         "passwords": [ "first-password-to-try", "second-password-to-try" ]
1265       }
1266     }
1267
1268 Configuring to accept any ssh server key using global credentials
1269 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1270
1271 By default Netconf Call-Home Server accepts only incoming connections
1272 from allowed devices
1273 ``/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices``,
1274 if user desires to allow all incoming connections, it is possible to set
1275 ``accept-all-ssh-keys`` to ``true`` in
1276 ``/odl-netconf-callhome-server:netconf-callhome-server/global``.
1277
1278 The name of these devices in ``netconf-topology`` will be in format
1279 ``ip-address:port``. For naming devices see Device-Specific
1280 Configuration.
1281
1282 *Allowing unknown devices to connect*
1283
1284 This is a debug feature and should not be used in production. Besides being an obvious
1285 security issue, this also causes the Call-Home Server to drastically increase its output
1286 to the log.
1287
1288 .. code-block::
1289
1290     PUT HTTP/1.1
1291     /rests/data/odl-netconf-callhome-server:netconf-callhome-server/global/accept-all-ssh-keys
1292     Content-Type: application/json
1293     Accept: application/json
1294
1295 .. code-block:: json
1296
1297     {
1298         "accept-all-ssh-keys": "true"
1299     }
1300
1301 Device-Specific Configuration
1302 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1303
1304 Netconf Call Home server supports both of the secure transports used
1305 by the Network Configuration Protocol (NETCONF) - Secure Shell (SSH),
1306 and Transport Layer Security (TLS).
1307
1308 Configure device to connect over SSH protocol
1309 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1310
1311 Netconf Call Home Server uses device provided SSH server key (host key)
1312 to identify device. The pairing of name and server key is configured in
1313 ``/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices``.
1314 This list is colloquially called a allowlist.
1315
1316 If the Call-Home Server finds the SSH host key in the allowlist, it continues
1317 to negotiate a NETCONF connection over an SSH session. If the SSH host key is
1318 not found, the connection between the Call Home server and the device is dropped
1319 immediately. In either case, the device that connects to the Call home server
1320 leaves a record of its presence in the operational store.
1321
1322 Configuring Device with Device-specific Credentials
1323 '''''''''''''''''''''''''''''''''''''''''''''''''''
1324
1325 Adding specific device to the allowed list is done by creating
1326 ``/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device={device}``
1327 with device-id and connection parameters inside the ssh-client-params container.
1328
1329 *Configuring Device with Credentials*
1330
1331 .. code-block::
1332
1333     PUT HTTP/1.1
1334     /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
1335     Content-Type: application/json
1336     Accept: application/json
1337
1338 .. code-block:: json
1339
1340     {
1341       "device": {
1342         "unique-id": "example",
1343         "ssh-client-params": {
1344           "credentials": {
1345             "username": "example",
1346             "passwords": [ "password" ]
1347           },
1348           "host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
1349         }
1350       }
1351     }
1352
1353 Configuring Device with Global Credentials
1354 '''''''''''''''''''''''''''''''''''''''''''''''''''
1355
1356 It is possible to omit ``username`` and ``password`` for ssh-client-params,
1357 in such case values from global credentials will be used.
1358
1359 *Example of configuring device*
1360
1361 .. code-block::
1362
1363     PUT HTTP/1.1
1364     /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
1365     Content-Type: application/json
1366     Accept: application/json
1367
1368 .. code-block:: json
1369
1370     {
1371       "device": {
1372         "unique-id": "example",
1373         "ssh-client-params": {
1374           "host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
1375         }
1376       }
1377     }
1378
1379 Deprecated configuration models for devices accessed with SSH protocol
1380 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1381
1382 With `RFC 8071 <https://www.rfc-editor.org/rfc/rfc8071>`__ alignment and adding
1383 support for TLS transport following configuration models have been marked
1384 deprecated.
1385
1386 Configuring Device with Global Credentials
1387 '''''''''''''''''''''''''''''''''''''''''''''''''''
1388
1389 *Example of configuring device*
1390
1391 .. code-block::
1392
1393     PUT HTTP/1.1
1394     /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
1395     Content-Type: application/json
1396     Accept: application/json
1397
1398 .. code-block:: json
1399
1400     {
1401       "device": {
1402         "unique-id": "example",
1403         "ssh-host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
1404       }
1405     }
1406
1407 Configuring Device with Device-specific Credentials
1408 '''''''''''''''''''''''''''''''''''''''''''''''''''
1409
1410 Call Home Server also allows the configuration of credentials per device basis.
1411 This is done by introducing ``credentials`` container into the
1412 device-specific configuration. Format is same as in global credentials.
1413
1414 *Configuring Device with Credentials*
1415
1416 .. code-block::
1417
1418     PUT HTTP/1.1
1419     /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
1420     Content-Type: application/json
1421     Accept: application/json
1422
1423 .. code-block:: json
1424
1425     {
1426       "device": {
1427         "unique-id": "example",
1428         "credentials": {
1429           "username": "example",
1430           "passwords": [ "password" ]
1431         },
1432         "ssh-host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
1433       }
1434     }
1435
1436 Configure device to connect over TLS protocol
1437 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1438
1439 Netconf Call Home Server allows devices to use TLS transport protocol to
1440 establish a connection towards the NETCONF device. This communication
1441 requires proper setup to make two-way TLS authentication possible for client
1442 and server.
1443
1444 The initial step is to configure certificates and keys for two-way TLS by
1445 storing them within the netconf-keystore.
1446
1447 *Adding a client private key credential to the netconf-keystore*
1448
1449 .. code-block::
1450
1451     POST HTTP/1.1
1452     /rests/operations/netconf-keystore:add-keystore-entry
1453     Content-Type: application/json
1454     Accept: application/json
1455
1456 .. code-block:: json
1457
1458   {
1459     "input": {
1460       "key-credential": [
1461         {
1462           "key-id": "example-client-key-id",
1463           "private-key": "base64encoded-private-key",
1464           "passphrase": "passphrase"
1465         }
1466       ]
1467     }
1468   }
1469
1470 *Associate a private key with a client and CA certificates chain*
1471
1472 .. code-block::
1473
1474     POST HTTP/1.1
1475     /rests/operations/netconf-keystore:add-private-key
1476     Content-Type: application/json
1477     Accept: application/json
1478
1479 .. code-block:: json
1480
1481   {
1482     "input": {
1483       "private-key": [
1484         {
1485           "name": "example-client-key-id",
1486           "data": "key-data",
1487           "certificate-chain": [
1488             "certificate-data"
1489           ]
1490         }
1491       ]
1492     }
1493   }
1494
1495 *Add a list of trusted CA and server certificates*
1496
1497 .. code-block::
1498
1499     POST HTTP/1.1
1500     /rests/operations/netconf-keystore:add-trusted-certificate
1501     Content-Type: application/json
1502     Accept: application/json
1503
1504 .. code-block:: json
1505
1506   {
1507     "input": {
1508       "trusted-certificate": [
1509         {
1510           "name": "example-ca-certificate",
1511           "certificate": "ca-certificate-data"
1512         },
1513         {
1514           "name": "example-server-certificate",
1515           "certificate": "server-certificate-data"
1516         }
1517       ]
1518     }
1519   }
1520
1521 In a second step, it is required to create an allowed device associated with
1522 a server certificate and client key. The server certificate will be used to
1523 identify and pin the NETCONF device during SSL handshake and should be unique
1524 among the allowed devices.
1525
1526 *Add device configuration for TLS protocol to allowed devices list*
1527
1528 .. code-block::
1529
1530     PUT HTTP/1.1
1531     /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example-device
1532     Content-Type: application/json
1533     Accept: application/json
1534
1535 .. code-block:: json
1536
1537   {
1538     "device": {
1539       "unique-id": "example-device",
1540       "tls-client-params": {
1541         "key-id": "example-client-key-id",
1542         "certificate-id": "example-server-certificate"
1543       }
1544     }
1545   }
1546
1547 Operational Status
1548 ^^^^^^^^^^^^^^^^^^
1549
1550 Once an entry is made on the config side of "allowed-devices", the Call-Home Server will
1551 populate a corresponding operational device that is the same as the config device but
1552 has an additional status. By default, this status is *DISCONNECTED*. Once a device calls
1553 home, this status will change to one of:
1554
1555 *CONNECTED* — The device is currently connected and the NETCONF mount is available for network
1556 management.
1557
1558 *FAILED_AUTH_FAILURE* — The last attempted connection was unsuccessful because the Call-Home
1559 Server was unable to provide the acceptable credentials of the device. The device is also
1560 disconnected and not available for network management.
1561
1562 *FAILED_NOT_ALLOWED* — The last attempted connection was unsuccessful because the device was
1563 not recognized as an acceptable device. The device is also disconnected and not available for
1564 network management.
1565
1566 *FAILED* — The last attempted connection was unsuccessful for a reason other than not
1567 allowed to connect or incorrect client credentials. The device is also disconnected and not
1568 available for network management.
1569
1570 *DISCONNECTED* — The device is currently disconnected.
1571
1572 Rogue Devices
1573 '''''''''''''
1574
1575 Devices that are not on the allowlist might try to connect to the Call-Home Server. In
1576 these cases, the server will keep a record by instantiating an operational device. There
1577 will be no corresponding config device for these rogues. They can be identified readily
1578 because their device id, rather than being user-supplied, will be of the form
1579 "address:port". Note that if a device calls back multiple times, there will only be
1580 a single operatinal entry (even if the port changes); these devices are recognized by
1581 their unique host key.
1582
1583 Southbound Call-Home API
1584 ~~~~~~~~~~~~~~~~~~~~~~~~
1585
1586 The Call-Home Server listens for incoming TCP connections and assumes that the other side of
1587 the connection is a device calling home via a NETCONF connection with SSH for
1588 management. The server uses port 4334 by default and this can be configured via a
1589 blueprint configuration file.
1590
1591 The device **must** initiate the connection and the server will not try to re-establish the
1592 connection in case of a drop. By requirement, the server cannot assume it has connectivity
1593 to the device due to NAT or firewalls among others.
1594
1595 Reading data with selected fields
1596 ---------------------------------
1597
1598 Overview
1599 ~~~~~~~~
1600
1601 If user would like to read only selected fields from a NETCONF device, it is possible to use
1602 the fields query parameter that is described by RFC-8040. RESTCONF parses content of query
1603 parameter into format that is accepted by NETCONF subtree filtering - filtering of data is done
1604 on NETCONF server, not on NETCONF client side. This approach optimizes network traffic load,
1605 because data in which user doesn't have interest, is not transferred over network.
1606
1607 Next advantages:
1608
1609 * using single RESTCONF request and single NETCONF RPC for reading multiple subtrees
1610 * possibility to read only selected fields under list node across multiple hierarchies
1611   (it cannot be done without proper selection API)
1612
1613 .. note::
1614
1615   More information about fields query parameter: `RFC 8071 <https://www.rfc-editor.org/rfc/rfc8040#section-4.8.3>`__
1616
1617 Preparation of data
1618 ~~~~~~~~~~~~~~~~~~~
1619
1620 For demonstration, we will define next YANG model:
1621
1622 ::
1623
1624     module test-module {
1625         yang-version 1.1;
1626         namespace "urn:opendaylight:test-module";
1627         prefix "tm";
1628         revision "2023-02-16";
1629
1630         container root {
1631             container simple-root {
1632                 leaf leaf-a {
1633                     type string;
1634                 }
1635                 leaf leaf-b {
1636                     type string;
1637                 }
1638                 leaf-list ll {
1639                     type string;
1640                 }
1641                 container nested {
1642                     leaf sample-x {
1643                         type boolean;
1644                     }
1645                     leaf sample-y {
1646                         type boolean;
1647                     }
1648                 }
1649             }
1650
1651             container list-root {
1652                 leaf branch-ab {
1653                     type int32;
1654                 }
1655                 list top-list {
1656                     key "key-1 key-2";
1657                     ordered-by user;
1658                     leaf key-1 {
1659                         type string;
1660                     }
1661                     leaf key-2 {
1662                         type string;
1663                     }
1664                     container next-data {
1665                         leaf switch-1 {
1666                             type empty;
1667                         }
1668                         leaf switch-2 {
1669                             type empty;
1670                         }
1671                     }
1672                     list nested-list {
1673                         key "identifier";
1674                         leaf identifier {
1675                             type string;
1676                         }
1677                         leaf foo {
1678                             type int32;
1679                         }
1680                     }
1681                 }
1682             }
1683         }
1684     }
1685
1686 Follow the :doc:`testtool` instructions to save this schema and run it with testtool.
1687
1688 Mounting NETCONF device that runs on NETCONF testtool:
1689
1690 .. code-block:: bash
1691
1692   curl --location --request PUT 'http://127.0.0.1:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=testtool' \
1693   --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
1694   --header 'Content-Type: application/json' \
1695   --data-raw '{
1696       "node": [
1697           {
1698               "node-id": "testtool",
1699               "netconf-node-topology:host": "127.0.0.1",
1700               "netconf-node-topology:port": 17830,
1701               "netconf-node-topology:keepalive-delay": 100,
1702               "netconf-node-topology:tcp-only": false,
1703               "netconf-node-topology:username": "admin",
1704               "netconf-node-topology:password": "admin"
1705           }
1706       ]
1707   }'
1708
1709 Setting initial configuration on NETCONF device:
1710
1711 .. code-block:: bash
1712
1713   curl --location --request PUT 'http://127.0.0.1:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=testtool/yang-ext:mount/test-module:root' \
1714   --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
1715   --header 'Content-Type: application/json' \
1716   --data-raw '{
1717       "root": {
1718           "simple-root": {
1719               "leaf-a": "asddhg",
1720               "leaf-b": "ffffff",
1721               "ll": [
1722                   "str1",
1723                   "str2",
1724                   "str3"
1725               ],
1726               "nested": {
1727                   "sample-x": true,
1728                   "sample-y": false
1729               }
1730           },
1731           "list-root": {
1732               "branch-ab": 5,
1733               "top-list": [
1734                   {
1735                       "key-1": "ka",
1736                       "key-2": "kb",
1737                       "next-data": {
1738                           "switch-1": [
1739                               null
1740                           ],
1741                           "switch-2": [
1742                               null
1743                           ]
1744                       },
1745                       "nested-list": [
1746                           {
1747                               "identifier": "f1",
1748                               "foo": 1
1749                           },
1750                           {
1751                               "identifier": "f2",
1752                               "foo": 10
1753                           },
1754                           {
1755                               "identifier": "f3",
1756                               "foo": 20
1757                           }
1758                       ]
1759                   },
1760                   {
1761                       "key-1": "kb",
1762                       "key-2": "ka",
1763                       "next-data": {
1764                           "switch-1": [
1765                               null
1766                           ]
1767                       },
1768                       "nested-list": [
1769                           {
1770                               "identifier": "e1",
1771                               "foo": 1
1772                           },
1773                           {
1774                               "identifier": "e2",
1775                               "foo": 2
1776                           },
1777                           {
1778                               "identifier": "e3",
1779                               "foo": 3
1780                           }
1781                       ]
1782                   },
1783                   {
1784                       "key-1": "kc",
1785                       "key-2": "ke",
1786                       "next-data": {
1787                           "switch-2": [
1788                               null
1789                           ]
1790                       },
1791                       "nested-list": [
1792                           {
1793                               "identifier": "q1",
1794                               "foo": 13
1795                           },
1796                           {
1797                               "identifier": "q2",
1798                               "foo": 14
1799                           },
1800                           {
1801                               "identifier": "q3",
1802                               "foo": 15
1803                           }
1804                       ]
1805                   }
1806               ]
1807           }
1808       }
1809   }'
1810
1811 Examples
1812 --------
1813
1814 1. Reading whole leaf-list 'll' and leaf 'nested/sample-x' under 'simple-root' container.
1815
1816 RESTCONF request:
1817
1818 .. code-block:: bash
1819
1820     curl --location --request GET 'http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=testtool/yang-ext:mount/test-module:root/simple-root?content=config&fields=ll;nested/sample-x' \
1821     --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
1822     --header 'Cookie: JSESSIONID=node01h4w82eorc1k61866b71qjgj503.node0'
1823
1824 Generated NETCONF RPC request:
1825
1826 .. code-block:: xml
1827
1828     <rpc message-id="m-18" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
1829         <get-config>
1830             <source>
1831                 <running/>
1832             </source>
1833             <filter xmlns:ns0="urn:ietf:params:xml:ns:netconf:base:1.0" ns0:type="subtree">
1834                 <root xmlns="urn:ietf:params:xml:ns:yang:test-model">
1835                     <simple-root>
1836                         <ll/>
1837                         <nested>
1838                             <sample-x/>
1839                         </nested>
1840                     </simple-root>
1841                 </root>
1842             </filter>
1843         </get-config>
1844     </rpc>
1845
1846 .. note::
1847
1848     Using fields query parameter it is also possible to read whole leaf-list or list without
1849     necessity to specify value / key predicate (without reading parent entity). Such scenario
1850     is not permitted in RFC-8040 paths alone - fields query parameter can be used as
1851     workaround for this case.
1852
1853 RESTCONF response:
1854
1855 .. code-block:: json
1856
1857     {
1858         "test-module:simple-root": {
1859             "ll": [
1860                 "str3",
1861                 "str1",
1862                 "str2"
1863             ],
1864             "nested": {
1865                 "sample-x": true
1866             }
1867         }
1868     }
1869
1870 2. Reading all identifiers of 'nested-list' under all elements of 'top-list'.
1871
1872 RESTCONF request:
1873
1874 .. code-block:: bash
1875
1876     curl --location --request GET 'http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=testtool/yang-ext:mount/test-module:root/list-root?content=config&fields=top-list(nested-list/identifier)' \
1877     --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
1878     --header 'Cookie: JSESSIONID=node01h4w82eorc1k61866b71qjgj503.node0'
1879
1880 Generated NETCONF RPC request:
1881
1882 .. code-block:: xml
1883
1884     <rpc message-id="m-27" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
1885         <get-config>
1886             <source>
1887                 <running/>
1888             </source>
1889             <filter xmlns:ns0="urn:ietf:params:xml:ns:netconf:base:1.0" ns0:type="subtree">
1890                 <root xmlns="urn:ietf:params:xml:ns:yang:test-model">
1891                     <list-root>
1892                         <top-list>
1893                             <nested-list>
1894                                 <identifier/>
1895                             </nested-list>
1896                             <key-1/>
1897                             <key-2/>
1898                         </top-list>
1899                     </list-root>
1900                 </root>
1901             </filter>
1902         </get-config>
1903     </rpc>
1904
1905 .. note::
1906
1907     NETCONF client automatically fetches values of list keys since they are required for correct
1908     deserialization of NETCONF response and at the end serialization of response to RESTCONF
1909     response (JSON/XML).
1910
1911 RESTCONF response:
1912
1913 .. code-block:: json
1914
1915     {
1916         "test-module:list-root": {
1917             "top-list": [
1918                 {
1919                     "key-1": "ka",
1920                     "key-2": "kb",
1921                     "nested-list": [
1922                         {
1923                             "identifier": "f3"
1924                         },
1925                         {
1926                             "identifier": "f2"
1927                         },
1928                         {
1929                             "identifier": "f1"
1930                         }
1931                     ]
1932                 },
1933                 {
1934                     "key-1": "kb",
1935                     "key-2": "ka",
1936                     "nested-list": [
1937                         {
1938                             "identifier": "e3"
1939                         },
1940                         {
1941                             "identifier": "e2"
1942                         },
1943                         {
1944                             "identifier": "e1"
1945                         }
1946                     ]
1947                 },
1948                 {
1949                     "key-1": "kc",
1950                     "key-2": "ke",
1951                     "nested-list": [
1952                         {
1953                             "identifier": "q3"
1954                         },
1955                         {
1956                             "identifier": "q2"
1957                         },
1958                         {
1959                             "identifier": "q1"
1960                         }
1961                     ]
1962                 }
1963             ]
1964         }
1965     }
1966
1967 3. Reading value of leaf 'branch-ab' and all values of leaves 'switch-1' that are placed
1968    under 'top-list' list elements.
1969
1970 RESTCONF request:
1971
1972 .. code-block:: bash
1973
1974     curl --location --request GET 'http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=testtool/yang-ext:mount/test-module:root/list-root?content=config&fields=branch-ab;top-list/next-data/switch-1' \
1975     --header 'Authorization: Basic YWRtaW46YWRtaW4=' \
1976     --header 'Cookie: JSESSIONID=node01jx6o5thwae9t1ft7c2zau5zbz4.node0'
1977
1978 Generated NETCONF RPC request:
1979
1980 .. code-block:: xml
1981
1982     <rpc message-id="m-42" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
1983         <get-config>
1984             <source>
1985                 <running/>
1986             </source>
1987             <filter xmlns:ns0="urn:ietf:params:xml:ns:netconf:base:1.0" ns0:type="subtree">
1988                 <root xmlns="urn:ietf:params:xml:ns:yang:test-model">
1989                     <list-root>
1990                         <branch-ab/>
1991                         <top-list>
1992                             <next-data>
1993                                 <switch-1/>
1994                             </next-data>
1995                             <key-1/>
1996                             <key-2/>
1997                         </top-list>
1998                     </list-root>
1999                 </root>
2000             </filter>
2001         </get-config>
2002     </rpc>
2003
2004 RESTCONF response:
2005
2006 .. code-block:: json
2007
2008     {
2009         "test-module:list-root": {
2010             "branch-ab": 5,
2011             "top-list": [
2012                 {
2013                     "key-1": "ka",
2014                     "key-2": "kb",
2015                     "next-data": {
2016                         "switch-1": [
2017                             null
2018                         ]
2019                     }
2020                 },
2021                 {
2022                     "key-1": "kb",
2023                     "key-2": "ka",
2024                     "next-data": {
2025                         "switch-1": [
2026                             null
2027                         ]
2028                     }
2029                 },
2030                 {
2031                     "key-1": "kc",
2032                     "key-2": "ke"
2033                 }
2034             ]
2035         }
2036     }
2037
2038 RESTCONF OpenAPI
2039 ----------------
2040
2041 Overview
2042 ~~~~~~~~
2043
2044 The OpenAPI provides full API for configurational data which can be edited (by POST, PUT, PATCH and DELETE).
2045 For operational data we only provide GET API. For the majority of requests you can see only config data in examples.
2046 That’s because we can show only one example per request. The exception when you can see operational data in an
2047 example is when data are representing an operational (config false) container with no config data in it.
2048
2049
2050 Using the OpenAPI Explorer through HTTP
2051 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2052
2053 1. Install OpenApi into Karaf by installing karaf feature:
2054
2055 ::
2056
2057     $ feature:install odl-restconf-openapi
2058
2059 2.  Navigate to OpenAPI in your web browser which is available at URLs:
2060
2061 -  http://localhost:8181/openapi/explorer/index.html for general overview
2062
2063 -  http://localhost:8181/openapi/api/v3/single for JSON data
2064
2065 .. note::
2066
2067     In the URL links for OpenAPI, change *localhost* to the IP/Host name of your actual server.
2068
2069 3.  Enter the username and password.
2070     By default the credentials are  *admin/admin*.
2071
2072 4.  Select any model to try out.
2073
2074 5.  Select any available request to try out.
2075
2076 6.  Click on the **Try it out** button.
2077
2078 7.  Provide any required parameters or edit request body.
2079
2080 8.  Click the **Execute** button.
2081
2082 9.  You can see responses to the given request.
2083
2084
2085 OpenAPI Explorer can also be used for connected device. How to connect a device can be found :ref:`here <netconf-connector>`.
2086
2087 OpenAPI URLs in that case would look like this:
2088
2089 -  `http://localhost:8181/openapi/explorer/index.html?urls.primaryName=17830-sim-device resources - RestConf RFC 8040 <http://localhost:8181/openapi/explorer/index.html?urls.primaryName=17830-sim-device%20resources%20-%20RestConf%20RFC%208040>`_ for device overview
2090
2091 -  http://localhost:8181/openapi/api/v3/mounts/1 for JSON data
2092
2093 -  `http://localhost:8181/openapi/api/v3/mounts/1/toaster(2009-11-20) <http://localhost:8181/openapi/api/v3/mounts/1/toaster(2009-11-20)>`__ JSON data for given model
2094
2095 .. note::
2096
2097     The URL links for OpenAPI are made for device with name *17830-sim-device* and model toaster
2098     with *2009-11-20* revision and need to be changed accordingly to connected device.