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