From: Yaroslav Lastivka Date: Wed, 8 Feb 2023 17:46:34 +0000 (+0200) Subject: Update NETCONF user guide X-Git-Tag: v5.0.4~10 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=f6ca808c32a2d66858859074117b7b45a0ec1269;p=netconf.git Update NETCONF user guide 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 Signed-off-by: Ivan Hrasko --- diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 12eea4d956..6902fc746d 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -41,7 +41,7 @@ In terms of RFCs, the connector supports: - `RFC-6022 `__ -- `draft-ietf-netconf-yang-library-06 `__ +- `RFC-7895 `__ **Netconf-connector is fully model-driven (utilizing the YANG modeling language) so in addition to the above RFCs, it supports any @@ -63,19 +63,13 @@ focuses on RESTCONF. .. important:: - There are 2 different endpoints related to RESTCONF protocols: - - - | ``http://localhost:8181/restconf`` is related to `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 `__, - | can be activated by installing ``odl-restconf-nb-rfc8040`` + | can be activated by installing ``odl-restconf-nb`` Karaf feature. - | In case of `RFC-8040 `__ - 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 @@ -88,8 +82,7 @@ focuses on RESTCONF. http://localhost:8181/rests/data/network-topology:network-topology?content=nonconfig for operational datastore. - | Also in case of `RFC-8040 `__, - 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 @@ -97,14 +90,7 @@ focuses on RESTCONF. | 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 - `__. - - Examples in the `Spawning new NETCONF connectors`_ section include both bierman02 and rfc8040 - formats + topology-netconf value of topology list. Preconditions ^^^^^^^^^^^^^ @@ -114,7 +100,7 @@ Preconditions 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -125,8 +111,6 @@ to RESTCONF: .. 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 @@ -136,8 +120,6 @@ without specifying the node in the URL: .. 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 @@ -221,9 +203,9 @@ be: Headers: -- 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: @@ -260,8 +242,6 @@ device: .. 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 @@ -453,10 +433,10 @@ Reading data from the device 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 -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 @@ -470,7 +450,7 @@ In fact this request comes from the tutorial dedicated to the **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 :: @@ -506,7 +486,7 @@ shows how to invoke the get-schema RPC (get-schema is quite common among 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 :: @@ -518,8 +498,8 @@ http://localhost:8181/restconf/operations/network-topology:network-topology/topo 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 @@ -614,7 +594,7 @@ Netopeer installation A `Docker `__ container with netopeer will be used in this guide. To install Docker and start the `netopeer -image `__ perform +image `__ perform following steps: 1. Install docker http://docs.docker.com/linux/step_one/ @@ -623,14 +603,14 @@ following steps: :: - 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: :: - ssh root@localhost -p 1831 -s netconf + ssh root@localhost -p 830 -s netconf (password root) Mounting netopeer NETCONF server @@ -658,7 +638,7 @@ After netopeer is mounted successfully, its configuration can be read 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) ---------------------------- @@ -732,7 +712,7 @@ In terms of RFCs, these are supported: - `RFC-6022 `__ -- `draft-ietf-netconf-yang-library-06 `__ +- `RFC-7895 `__ Notifications over NETCONF are not supported in the Boron release. @@ -780,7 +760,7 @@ Now the MD-SAL’s datastore can be read over RESTCONF via NETCONF by invoking: GET -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 .. note:: @@ -868,7 +848,7 @@ XML :: - http://localhost:8181/restconf/operational/ietf-yang-library:modules-state + http://localhost:8181/rests/data/ietf-yang-library:modules-state admin admin @@ -926,8 +906,8 @@ with username and passwords specified. .. code-block:: - 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 @@ -963,17 +943,15 @@ to the log. .. code-block:: - 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 { - "global": { "accept-all-ssh-keys": "true" - } } Device-Specific Configuration @@ -1001,15 +979,15 @@ Configuring Device with Device-specific Credentials ''''''''''''''''''''''''''''''''''''''''''''''''''' 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:: - 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 @@ -1023,7 +1001,7 @@ with device-id and connection parameters inside the ssh-client-params container. "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" } } } @@ -1031,15 +1009,15 @@ with device-id and connection parameters inside the ssh-client-params container. 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:: - 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 @@ -1068,8 +1046,8 @@ Configuring Device with Global 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 @@ -1093,8 +1071,8 @@ device-specific configuration. Format is same as in global 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 @@ -1126,8 +1104,8 @@ storing them within the netconf-keystore. .. code-block:: - 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 @@ -1149,8 +1127,8 @@ storing them within the netconf-keystore. .. code-block:: - 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 @@ -1174,8 +1152,8 @@ storing them within the netconf-keystore. .. code-block:: - 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 @@ -1205,8 +1183,8 @@ among the allowed devices. .. code-block:: - 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 @@ -1295,6 +1273,74 @@ Next advantages: 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 @@ -1307,7 +1353,7 @@ Mounting NETCONF device that runs on NETCONF testtool: { "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",