From: Luis Gomez Date: Mon, 12 Oct 2020 01:19:54 +0000 (-0700) Subject: Update NETCONF user documentation X-Git-Tag: v1.13.0~98 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=e830e5b76ec00fd4b5a5553caa560b5f1c485111;p=netconf.git Update NETCONF user documentation - Remove old CSS configuration - Add JSON payloads Change-Id: I8eddf4f4cc505d9c3f872cdadacc9fc5a972380d Signed-off-by: Luis Gomez --- diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 08d93e1352..0c34d8a063 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -56,8 +56,10 @@ the device.** Netconf-connector configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are 2 ways for configuring netconf-connector: NETCONF or RESTCONF. -This guide focuses on using RESTCONF. +NETCONF connectors are configured directly through the usage of the +network-topology model. You can configure new NETCONF connectors both +through the NETCONF server for MD-SAL (port 2830) or RESTCONF. This guide +focuses on RESTCONF. .. important:: @@ -104,264 +106,6 @@ This guide focuses on using RESTCONF. Examples in the `Spawning new NETCONF connectors`_ section include both bierman02 and rfc8040 formats - -Default configuration -^^^^^^^^^^^^^^^^^^^^^ - -The default configuration contains all the necessary dependencies (file: -01-netconf.xml) and a single instance of netconf-connector (file: -99-netconf-connector.xml) called **controller-config** which connects -itself to the NETCONF northbound in OpenDaylight in a loopback fashion. -The connector mounts the NETCONF server for config-subsystem in order to -enable RESTCONF protocol for config-subsystem. This RESTCONF still goes -via NETCONF, but using RESTCONF is much more user friendly than using -NETCONF. - -Spawning additional netconf-connectors while the controller is running -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Preconditions: - -1. OpenDaylight is running - -2. In Karaf, you must have the netconf-connector installed (at the Karaf - prompt, type: ``feature:install odl-netconf-connector-all``); the - loopback NETCONF mountpoint will be automatically configured and - activated - -3. Wait until log displays following entry: - RemoteDevice{controller-config}: NETCONF connector initialized - successfully - -To configure a new netconf-connector you need to send following request -to RESTCONF: - -POST -http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules - -Headers: - -- Accept application/xml - -- Content-Type application/xml - -:: - - - prefix:sal-netconf-connector - new-netconf-device -
127.0.0.1
- 830 - admin - admin - false - - prefix:netty-event-executor - global-event-executor - - - prefix:binding-broker-osgi-registry - binding-osgi-broker - - - prefix:dom-broker-osgi-registry - dom-broker - - - prefix:netconf-client-dispatcher - global-netconf-dispatcher - - - prefix:threadpool - global-netconf-processing-executor - - - prefix:scheduled-threadpool - global-netconf-ssh-scheduled-executor - - - -This spawns a new netconf-connector which tries to connect to (or mount) -a NETCONF device at 127.0.0.1 and port 830. You can check the -configuration of config-subsystem’s configuration datastore. The new -netconf-connector will now be present there. Just invoke: - -GET -http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules - -The response will contain the module for new-netconf-device. - -Right after the new netconf-connector is created, it writes some useful -metadata into the datastore of MD-SAL under the network-topology -subtree. This metadata can be found at: - -GET -http://localhost:8181/restconf/operational/network-topology:network-topology/ - -Information about connection status, device capabilities, etc. can be -found there. - -Connecting to a device not supporting NETCONF monitoring -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The netconf-connector in OpenDaylight relies on ietf-netconf-monitoring -support when connecting to remote NETCONF device. The -ietf-netconf-monitoring support allows netconf-connector to list and -download all YANG schemas that are used by the device. NETCONF connector -can only communicate with a device if it knows the set of used schemas -(or at least a subset). However, some devices use YANG models internally -but do not support NETCONF monitoring. Netconf-connector can also -communicate with these devices, but you have to side load the necessary -yang models into OpenDaylight’s YANG model cache for netconf-connector. -In general there are 2 situations you might encounter: - -**1. NETCONF device does not support ietf-netconf-monitoring but it does -list all its YANG models as capabilities in HELLO message** - -This could be a device that internally uses only ietf-inet-types YANG -model with revision 2010-09-24. In the HELLO message that is sent from -this device there is this capability reported: - -:: - - urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2010-09-24 - -**For such devices you only need to put the schema into folder -cache/schema inside your Karaf distribution.** - -.. important:: - - The file with YANG schema for ietf-inet-types has to be called - ietf-inet-types@2010-09-24.yang. It is the required naming format of - the cache. - -**2. NETCONF device does not support ietf-netconf-monitoring and it does -NOT list its YANG models as capabilities in HELLO message** - -Compared to device that lists its YANG models in HELLO message, in this -case there would be no capability with ietf-inet-types in the HELLO -message. This type of device basically provides no information about the -YANG schemas it uses so its up to the user of OpenDaylight to properly -configure netconf-connector for this device. - -Netconf-connector has an optional configuration attribute called -yang-module-capabilities and this attribute can contain a list of "YANG -module based" capabilities. So by setting this configuration attribute, -it is possible to override the "yang-module-based" capabilities reported -in HELLO message of the device. To do this, we need to modify the -configuration of netconf-connector by adding this XML (It needs to be -added next to the address, port, username etc. configuration elements): - -:: - - - - urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2010-09-24 - - - -**Remember to also put the YANG schemas into the cache folder.** - -.. note:: - - For putting multiple capabilities, you just need to replicate the - capability xml element inside yang-module-capability element. - Capability element is modeled as a leaf-list. With this - configuration, we would make the remote device report usage of - ietf-inet-types in the eyes of netconf-connector. - -Reconfiguring Netconf-Connector While the Controller is Running -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It is possible to change the configuration of a running module while the -whole controller is running. This example will continue where the last -left off and will change the configuration for the brand new -netconf-connector after it was spawned. Using one RESTCONF request, we -will change both username and password for the netconf-connector. - -To update an existing netconf-connector you need to send following -request to RESTCONF: - -PUT -http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-sal-netconf-connector-cfg:sal-netconf-connector/new-netconf-device - -:: - - - prefix:sal-netconf-connector - new-netconf-device - bob - passwd - false - - prefix:netty-event-executor - global-event-executor - - - prefix:binding-broker-osgi-registry - binding-osgi-broker - - - prefix:dom-broker-osgi-registry - dom-broker - - - prefix:netconf-client-dispatcher - global-netconf-dispatcher - - - prefix:threadpool - global-netconf-processing-executor - - - prefix:scheduled-threadpool - global-netconf-ssh-scheduled-executor - - - -Since a PUT is a replace operation, the whole configuration must be -specified along with the new values for username and password. This -should result in a 2xx response and the instance of netconf-connector -called new-netconf-device will be reconfigured to use username bob and -password passwd. New configuration can be verified by executing: - -GET -http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-sal-netconf-connector-cfg:sal-netconf-connector/new-netconf-device - -With new configuration, the old connection will be closed and a new one -established. - -Destroying Netconf-Connector While the Controller is Running -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Using RESTCONF one can also destroy an instance of a module. In case of -netconf-connector, the module will be destroyed, NETCONF connection -dropped and all resources will be cleaned. To do this, simply issue a -request to following URL: - -DELETE -http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/odl-sal-netconf-connector-cfg:sal-netconf-connector/new-netconf-device - -The last element of the URL is the name of the instance and its -predecessor is the type of that module (In our case the type is -**sal-netconf-connector** and name **new-netconf-device**). The type and -name are actually the keys of the module list. - -Netconf-connector configuration with MD-SAL -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is also possible to configure new NETCONF connectors directly through -MD-SAL with the usage of the network-topology model. You can configure -new NETCONF connectors both through the NETCONF server for MD-SAL (port -2830) or RESTCONF. This guide focuses on RESTCONF. - -.. tip:: - - To enable NETCONF connector configuration through MD-SAL install - either the ``odl-netconf-topology`` or - ``odl-netconf-clustered-topology`` feature. We will explain the - difference between these features later. - Preconditions ^^^^^^^^^^^^^ @@ -372,26 +116,6 @@ Preconditions 3. Feature ``odl-restconf`` must be installed -4. Wait until log displays following entry: - - :: - - Successfully pushed configuration snapshot 02-netconf-topology.xml(odl-netconf-topology,odl-netconf-topology) - - or until - - :: - - GET http://localhost:8181/restconf/operational/network-topology:network-topology/topology/topology-netconf/ - - returns a non-empty response, for example: - - :: - - - topology-netconf - - Spawning new NETCONF connectors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -417,32 +141,65 @@ without specifying the node in the URL: * - rfc8040 - http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf -Headers: +Payload: -- Accept: application/xml +.. tabs:: -- Content-Type: application/xml + .. tab:: XML -Payload: + **Content-type:** ``application/xml`` -:: + **Accept:** ``application/xml`` - - new-netconf-device - 127.0.0.1 - 17830 - admin - admin - false - - false - 20000 - 0 - 2000 - 1.5 - - 120 - + **Authentication:** ``admin:admin`` + + .. code-block:: xml + + + new-netconf-device + 127.0.0.1 + 17830 + admin + admin + false + + false + 20000 + 0 + 2000 + 1.5 + + 120 + + + .. tab:: JSON + + **Content-type:** ``application/json`` + + **Accept:** ``application/json`` + + **Authentication:** ``admin:admin`` + + .. code-block:: json + + { + "node": [ + { + "node-id": "new-netconf-device", + "netconf-node-topology:port": 17830, + "netconf-node-topology:reconnect-on-changed-schema": false, + "netconf-node-topology:connection-timeout-millis": 20000, + "netconf-node-topology:tcp-only": false, + "netconf-node-topology:max-connection-attempts": 0, + "netconf-node-topology:username": "admin", + "netconf-node-topology:password": "admin", + "netconf-node-topology:sleep-factor": 1.5, + "netconf-node-topology:host": "127.0.0.1", + "netconf-node-topology:between-attempts-timeout-millis": 2000, + "netconf-node-topology:keepalive-delay": 120 + } + ] + } Note that the device name in element must match the last element of the restconf URL. @@ -493,7 +250,6 @@ Example JSON payload to modify the password entry: } } - Deleting an existing connector ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -513,6 +269,124 @@ device: No body is needed to delete the node/device +Connecting to a device not supporting NETCONF monitoring +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The netconf-connector in OpenDaylight relies on ietf-netconf-monitoring +support when connecting to remote NETCONF device. The +ietf-netconf-monitoring support allows netconf-connector to list and +download all YANG schemas that are used by the device. NETCONF connector +can only communicate with a device if it knows the set of used schemas +(or at least a subset). However, some devices use YANG models internally +but do not support NETCONF monitoring. Netconf-connector can also +communicate with these devices, but you have to side load the necessary +yang models into OpenDaylight’s YANG model cache for netconf-connector. +In general there are 2 situations you might encounter: + +**1. NETCONF device does not support ietf-netconf-monitoring but it does +list all its YANG models as capabilities in HELLO message** + +This could be a device that internally uses only ietf-inet-types YANG +model with revision 2010-09-24. In the HELLO message that is sent from +this device there is this capability reported: + +:: + + urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2010-09-24 + +**For such devices you only need to put the schema into folder +cache/schema inside your Karaf distribution.** + +.. important:: + + The file with YANG schema for ietf-inet-types has to be called + ietf-inet-types@2010-09-24.yang. It is the required naming format of + the cache. + +**2. NETCONF device does not support ietf-netconf-monitoring and it does +NOT list its YANG models as capabilities in HELLO message** + +Compared to device that lists its YANG models in HELLO message, in this +case there would be no capability with ietf-inet-types in the HELLO +message. This type of device basically provides no information about the +YANG schemas it uses so its up to the user of OpenDaylight to properly +configure netconf-connector for this device. + +Netconf-connector has an optional configuration attribute called +yang-module-capabilities and this attribute can contain a list of "YANG +module based" capabilities. So by setting this configuration attribute, +it is possible to override the "yang-module-based" capabilities reported +in HELLO message of the device. To do this, we need to modify the +configuration of netconf-connector like in the example below: + +.. tabs:: + + .. tab:: XML + + **Content-type:** ``application/xml`` + + **Accept:** ``application/xml`` + + **Authentication:** ``admin:admin`` + + .. code-block:: xml + + + r5 + 127.0.0.1 + 8305 + root + root + false + 30 + + true + + urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15 + + + + + .. tab:: JSON + + **Content-type:** ``application/json`` + + **Accept:** ``application/json`` + + **Authentication:** ``admin:admin`` + + .. code-block:: json + + { + "node": [ + { + "node-id": "device", + "netconf-node-topology:host": "127.0.0.1", + "netconf-node-topology:password": "root", + "netconf-node-topology:username": "root", + "netconf-node-topology:yang-module-capabilities": { + "override": true, + "capability": [ + "urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15" + ] + }, + "netconf-node-topology:port": 8305, + "netconf-node-topology:tcp-only": false, + "netconf-node-topology:keepalive-delay": 30 + } + ] + } + +**Remember to also put the YANG schemas into the cache folder.** + +.. note:: + + For putting multiple capabilities, you just need to replicate the + capability element inside yang-module-capability element. + Capability element is modeled as a leaf-list. With this + configuration, we would make the remote device report usage of + ietf-inet-types in the eyes of netconf-connector. + Connecting to a device supporting only NETCONF 1.0 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^