User guide still contains references to removed bierman-02 paths:
`/restconf/config`, `/restconf/operational` and `restconf/operations`.
Fix them according to RFC 8040.
Make other small changes in order to make documentation up-to-date
with current state: update RFC-7895 link, update requests, default
ports and the netopeer2 usage.
JIRA: NETCONF-946
Change-Id: I94cd1fdf53ff3038a691f43f615d96645df7f023
Signed-off-by: Yaroslav Lastivka <yaroslav.lastivka@pantheon.tech>
Signed-off-by: Ivan Hrasko <ivan.hrasko@pantheon.tech>
- `RFC-6022 <https://tools.ietf.org/html/rfc6022>`__
- `RFC-6022 <https://tools.ietf.org/html/rfc6022>`__
-- `draft-ietf-netconf-yang-library-06 <https://tools.ietf.org/html/draft-ietf-netconf-yang-library-06>`__
+- `RFC-7895 <https://tools.ietf.org/html/rfc7895>`__
**Netconf-connector is fully model-driven (utilizing the YANG modeling
language) so in addition to the above RFCs, it supports any
**Netconf-connector is fully model-driven (utilizing the YANG modeling
language) so in addition to the above RFCs, it supports any
- There are 2 different endpoints related to RESTCONF protocols:
-
- - | ``http://localhost:8181/restconf`` is related to `draft-bierman-netconf-restconf-02 <https://tools.ietf.org/html/draft-bierman-netconf-restconf-02>`__,
- | can be activated by installing ``odl-restconf-nb-bierman02``
- Karaf feature.
- | This user guide uses this approach.
+ Since 2022.09 Chlorine there is only one RESTCONF endpoint:
- | ``http://localhost:8181/rests`` is related to `RFC-8040 <https://tools.ietf.org/html/rfc8040>`__,
- | ``http://localhost:8181/rests`` is related to `RFC-8040 <https://tools.ietf.org/html/rfc8040>`__,
- | can be activated by installing ``odl-restconf-nb-rfc8040``
+ | can be activated by installing ``odl-restconf-nb``
- | In case of `RFC-8040 <https://tools.ietf.org/html/rfc8040>`__
- resources for configuration and operational datastores start
+ | Resources for configuration and operational datastores start
``/rests/data/``,
| e. g. GET
http://localhost:8181/rests/data/network-topology:network-topology
``/rests/data/``,
| e. g. GET
http://localhost:8181/rests/data/network-topology:network-topology
http://localhost:8181/rests/data/network-topology:network-topology?content=nonconfig
for operational datastore.
http://localhost:8181/rests/data/network-topology:network-topology?content=nonconfig
for operational datastore.
- | Also in case of `RFC-8040 <https://tools.ietf.org/html/rfc8040>`__,
- if a data node in the path expression is a YANG leaf-list or list
+ | Also if a data node in the path expression is a YANG leaf-list or list
node, the path segment has to be constructed by having leaf-list or
list node name, followed by an "=" character, then followed by the
leaf-list or list value. Any reserved characters must be
node, the path segment has to be constructed by having leaf-list or
list node name, followed by an "=" character, then followed by the
leaf-list or list value. Any reserved characters must be
| e. g. GET
http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf?content=config
for retrieving data from configuration datastore for
| e. g. GET
http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf?content=config
for retrieving data from configuration datastore for
- topology-netconf value of topology list is equivalent to the deprecated request
- | |ss| GET |se|
- http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf,
- which is related to `draft-bierman-netconf-restconf-02
- <https://tools.ietf.org/html/draft-bierman-netconf-restconf-02>`__.
-
- Examples in the `Spawning new NETCONF connectors`_ section include both bierman02 and rfc8040
- formats
+ topology-netconf value of topology list.
Preconditions
^^^^^^^^^^^^^
Preconditions
^^^^^^^^^^^^^
2. In Karaf, you must have the ``odl-netconf-topology`` or
``odl-netconf-clustered-topology`` feature installed.
2. In Karaf, you must have the ``odl-netconf-topology`` or
``odl-netconf-clustered-topology`` feature installed.
-3. Feature ``odl-restconf`` must be installed
+3. Feature ``odl-restconf-nb`` must be installed
Spawning new NETCONF connectors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Spawning new NETCONF connectors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:widths: 1 5
.. list-table::
:widths: 1 5
- * - bierman02
- - http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
* - rfc8040
- http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device
* - rfc8040
- http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device
.. list-table::
:widths: 1 5
.. list-table::
:widths: 1 5
- * - bierman02
- - http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf
* - rfc8040
- http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf
* - rfc8040
- http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf
-- Accept: application/yang.patch-status+json
+- Accept: application/yang-data+json
-- Content-Type: application/yang.patch+json
+- Content-Type: application/yang-patch+json
Example JSON payload to modify the password entry:
Example JSON payload to modify the password entry:
.. list-table::
:widths: 1 5
.. list-table::
:widths: 1 5
- * - bierman02
- - http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
* - rfc8040
- http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device
* - rfc8040
- http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device
Just invoke (no body needed):
GET
Just invoke (no body needed):
GET
-http://localhost:8080/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/
+http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device/yang-ext:mount?content=nonconfig
This will return the entire content of operation datastore from the
This will return the entire content of operation datastore from the
-device. To view just the configuration datastore, change **operational**
+device. To view just the configuration datastore, change **nonconfig**
in this URL to **config**.
Writing configuration data to the device
in this URL to **config**.
Writing configuration data to the device
**ncmount** tutorial app.
POST
**ncmount** tutorial app.
POST
-http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/Cisco-IOS-XR-ifmgr-cfg:interface-configurations
+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
netconf devices). Invoke:
POST
netconf devices). Invoke:
POST
-http://localhost:8181/restconf/operations/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/ietf-netconf-monitoring:get-schema
+http://localhost:8181/rests/operations/network-topology:network-topology/topology=topology-netconf/node=new-netconf-device/yang-ext:mount/ietf-netconf-monitoring:get-schema
This call should fetch the source for ietf-yang-types YANG model from
the mounted device.
This call should fetch the source for ietf-yang-types YANG model from
the mounted device.
-Receving Netconf Device Notifications on a http client
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Receiving Netconf Device Notifications on a http client
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Devices emit netconf alarms and notifictions on certain situtations, which can demand
attention from Device Administration. The notifications are received as Netconf messages on an
Devices emit netconf alarms and notifictions on certain situtations, which can demand
attention from Device Administration. The notifications are received as Netconf messages on an
A `Docker <https://www.docker.com/>`__ container with netopeer will be
used in this guide. To install Docker and start the `netopeer
A `Docker <https://www.docker.com/>`__ container with netopeer will be
used in this guide. To install Docker and start the `netopeer
-image <https://index.docker.io/u/dockeruser/netopeer/>`__ perform
+image <https://hub.docker.com/r/sysrepo/sysrepo-netopeer2>`__ perform
following steps:
1. Install docker http://docs.docker.com/linux/step_one/
following steps:
1. Install docker http://docs.docker.com/linux/step_one/
- docker run --rm -t -p 1831:830 dockeruser/netopeer
+ docker run -it --name sysrepo -p 830:830 --rm sysrepo/sysrepo-netopeer2:latest
3. Verify netopeer is running by invoking (netopeer should send its
HELLO message right away:
::
3. Verify netopeer is running by invoking (netopeer should send its
HELLO message right away:
::
- ssh root@localhost -p 1831 -s netconf
+ ssh root@localhost -p 830 -s netconf
(password root)
Mounting netopeer NETCONF server
(password root)
Mounting netopeer NETCONF server
using RESTCONF by invoking:
GET
using RESTCONF by invoking:
GET
-http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/netopeer/yang-ext:mount/
+http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=netopeer/yang-ext:mount?content:config
Northbound (NETCONF servers)
----------------------------
Northbound (NETCONF servers)
----------------------------
- `RFC-6022 <https://tools.ietf.org/html/rfc6022>`__
- `RFC-6022 <https://tools.ietf.org/html/rfc6022>`__
-- `draft-ietf-netconf-yang-library-06 <https://tools.ietf.org/html/draft-ietf-netconf-yang-library-06>`__
+- `RFC-7895 <https://tools.ietf.org/html/rfc7895>`__
Notifications over NETCONF are not supported in the Boron release.
Notifications over NETCONF are not supported in the Boron release.
-http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/node/controller-mdsal/yang-ext:mount
+http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=controller-mdsal/yang-ext:mount?content:nonconfig
::
<yang-library xmlns="urn:opendaylight:netconf-node-topology">
::
<yang-library xmlns="urn:opendaylight:netconf-node-topology">
- <yang-library-url xmlns="urn:opendaylight:netconf-node-topology">http://localhost:8181/restconf/operational/ietf-yang-library:modules-state</yang-library-url>
+ <yang-library-url xmlns="urn:opendaylight:netconf-node-topology">http://localhost:8181/rests/data/ietf-yang-library:modules-state</yang-library-url>
<username xmlns="urn:opendaylight:netconf-node-topology">admin</username>
<password xmlns="urn:opendaylight:netconf-node-topology">admin</password>
</yang-library>
<username xmlns="urn:opendaylight:netconf-node-topology">admin</username>
<password xmlns="urn:opendaylight:netconf-node-topology">admin</password>
</yang-library>
- PUT
- /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/global/credentials HTTP/1.1
+ PUT HTTP/1.1
+ /rests/data/odl-netconf-callhome-server:netconf-callhome-server/global/credentials
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
- POST
- /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/global HTTP/1.1
+ PUT HTTP/1.1
+ /rests/data/odl-netconf-callhome-server:netconf-callhome-server/global/accept-all-ssh-keys
Content-Type: application/json
Accept: application/json
.. code-block:: json
{
Content-Type: application/json
Accept: application/json
.. code-block:: json
{
"accept-all-ssh-keys": "true"
"accept-all-ssh-keys": "true"
}
Device-Specific Configuration
}
Device-Specific Configuration
'''''''''''''''''''''''''''''''''''''''''''''''''''
Adding specific device to the allowed list is done by creating
'''''''''''''''''''''''''''''''''''''''''''''''''''
Adding specific device to the allowed list is done by creating
-``/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/{device}``
+``/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device={device}``
with device-id and connection parameters inside the ssh-client-params container.
*Configuring Device with Credentials*
.. code-block::
with device-id and connection parameters inside the ssh-client-params container.
*Configuring Device with Credentials*
.. code-block::
- PUT
- /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/example HTTP/1.1
+ PUT HTTP/1.1
+ /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
"username": "example",
"passwords": [ "password" ]
},
"username": "example",
"passwords": [ "password" ]
},
- "ssh-host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
+ "host-key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDHoH1jMjltOJnCt999uaSfc48ySutaD3ISJ9fSECe1Spdq9o9mxj0kBTTTq+2V8hPspuW75DNgN+V/rgJeoUewWwCAasRx9X4eTcRrJrwOQKzb5Fk+UKgQmenZ5uhLAefi2qXX/agFCtZi99vw+jHXZStfHm9TZCAf2zi+HIBzoVksSNJD0VvPo66EAvLn5qKWQD4AdpQQbKqXRf5/W8diPySbYdvOP2/7HFhDukW8yV/7ZtcywFUIu3gdXsrzwMnTqnATSLPPuckoi0V2jd8dQvEcu1DY+rRqmqu0tEkFBurlRZDf1yhNzq5xWY3OXcjgDGN+RxwuWQK3cRimcosH"
Configuring Device with Global Credentials
'''''''''''''''''''''''''''''''''''''''''''''''''''
Configuring Device with Global Credentials
'''''''''''''''''''''''''''''''''''''''''''''''''''
-It is possible to omit 'username' and 'password' for ssh-client-params,
+It is possible to omit ``username`` and ``password`` for ssh-client-params,
in such case values from global credentials will be used.
*Example of configuring device*
.. code-block::
in such case values from global credentials will be used.
*Example of configuring device*
.. code-block::
- PUT
- /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/example HTTP/1.1
+ PUT HTTP/1.1
+ /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
- PUT
- /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/example HTTP/1.1
+ PUT HTTP/1.1
+ /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
- PUT
- /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/example HTTP/1.1
+ PUT HTTP/1.1
+ /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
- POST
- /rests/operations/netconf-keystore:add-keystore-entry HTTP/1.1
+ POST HTTP/1.1
+ /rests/operations/netconf-keystore:add-keystore-entry
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
- POST
- /rests/operations/netconf-keystore:add-private-key HTTP/1.1
+ POST HTTP/1.1
+ /rests/operations/netconf-keystore:add-private-key
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
- POST
- /rests/operations/netconf-keystore:add-trusted-certificate HTTP/1.1
+ POST HTTP/1.1
+ /rests/operations/netconf-keystore:add-trusted-certificate
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
- PUT
- /restconf/config/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device/example-device HTTP/1.1
+ PUT HTTP/1.1
+ /rests/data/odl-netconf-callhome-server:netconf-callhome-server/allowed-devices/device=example-device
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
Preparation of data
~~~~~~~~~~~~~~~~~~~
Preparation of data
~~~~~~~~~~~~~~~~~~~
+For demonstration, we will define next YANG model:
+
+::
+
+ module test-module {
+ yang-version 1.1;
+ namespace "urn:opendaylight:test-module";
+ prefix "tm";
+ revision "2023-02-16";
+
+ container root {
+ container simple-root {
+ leaf leaf-a {
+ type string;
+ }
+ leaf leaf-b {
+ type string;
+ }
+ leaf-list ll {
+ type string;
+ }
+ container nested {
+ leaf sample-x {
+ type boolean;
+ }
+ leaf sample-y {
+ type boolean;
+ }
+ }
+ }
+
+ container list-root {
+ leaf branch-ab {
+ type int32;
+ }
+ list top-list {
+ key "key-1 key-2";
+ ordered-by user;
+ leaf key-1 {
+ type string;
+ }
+ leaf key-2 {
+ type string;
+ }
+ container next-data {
+ leaf switch-1 {
+ type empty;
+ }
+ leaf switch-2 {
+ type empty;
+ }
+ }
+ list nested-list {
+ key "identifier";
+ leaf identifier {
+ type string;
+ }
+ leaf foo {
+ type int32;
+ }
+ }
+ }
+ }
+ }
+ }
+
+Follow the :doc:`testtool` instructions to save this schema and run it with testtool.
+
Mounting NETCONF device that runs on NETCONF testtool:
.. code-block:: bash
Mounting NETCONF device that runs on NETCONF testtool:
.. code-block:: bash
{
"node-id": "testtool",
"netconf-node-topology:host": "127.0.0.1",
{
"node-id": "testtool",
"netconf-node-topology:host": "127.0.0.1",
- "netconf-node-topology:port": 36000,
+ "netconf-node-topology:port": 17830,
"netconf-node-topology:keepalive-delay": 100,
"netconf-node-topology:tcp-only": false,
"netconf-node-topology:username": "admin",
"netconf-node-topology:keepalive-delay": 100,
"netconf-node-topology:tcp-only": false,
"netconf-node-topology:username": "admin",