Add doc Entry to read Netconf device events.

[netconf.git] / docs / user-guide.rst

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index d0b8b62a4685de602f6849483e3b8b39428cd988..12eea4d956030d5d481f35ae26f8d4f8d08bfc20 100644 (file)
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -518,6 +518,90 @@ 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+active Netconf session.
+
+Opendaylight provides the way to stream the device notifications over a http session.
+
+- Step 1: Mount the device (assume node name is test_device)
+
+- Step 2: Wait for the device to be connected.
+
+- Step 3: Create the Subscription for notification on the active session.
+
+ .. code-block::
+
+    POST
+    http://localhost:8181/rests/operations/network-topology:network-topology/topology=topology-netconf/node=test_device/yang-ext:mount/notifications:create-subscription
+    Content-Type: application/json
+    Accept: application/json
+
+ .. code-block:: json
+
+    {
+      "input": {
+        "stream": "NETCONF"
+       }
+    }
+
+- Step 4: Create the http Stream for the events.
+
+.. code-block::
+
+    POST
+    http://localhost:8181/rests/operations/odl-device-notification:subscribe-device-notification
+    Content-Type: application/json
+    Accept: application/json
+
+.. code-block:: json
+
+    {
+      "input": {
+         "path":"/network-topology:network-topology/topology[topology-id='topology-netconf']/node[node-id='test_device']"
+      }
+    }
+
+The response suggests the http url for reading the notifications.
+
+.. code-block:: json
+
+    {
+       "odl-device-notification:output": {
+            "stream-path": "http://localhost:8181/rests/notif/test_device?notificationType=test_device"
+        }
+    }
+
+- Step 5: User can access the url in the response and the notifications will be as follows.
+
+.. code-block::
+
+    GET
+    http://localhost:8181/rests/notif/test_device?notificationType=test_device
+    Content-Type: application/xml
+    Accept: application/xml
+
+
+.. code-block:: xml
+
+    : ping
+
+    : ping
+
+    : ping
+
+    : ping
+
+    : ping
+
+    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>
+
+    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>
+
+
 Netconf-connector + Netopeer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -734,12 +818,12 @@ YANGLIB configuration through RESTCONF
 You have to specify what local YANG modules directory you want to provide.
 Then you have to specify address and port whre you want to provide YANG
 sources. For example, we want to serve yang sources from folder /sources
-on localhost:5000 adress. The configuration for this scenario will be
+on localhost:8181 adress. The configuration for this scenario will be
 as follows:
 
 ::
 
-    PUT  http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/controller-config/yang-ext:mount/config:modules/module/yanglib:yanglib/example
+    PUT  http://localhost:8181/rests/data/yanglib:yanglib-config
 
 Headers:
 
@@ -751,17 +835,11 @@ Payload:
 
 ::
 
-   <module xmlns="urn:opendaylight:params:xml:ns:yang:controller:config">
-     <name>example</name>
-     <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">prefix:yanglib</type>
-     <broker xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">
-       <type xmlns:prefix="urn:opendaylight:params:xml:ns:yang:controller:md:sal:binding">prefix:binding-broker-osgi-registry</type>
-       <name>binding-osgi-broker</name>
-     </broker>
-     <cache-folder xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">/sources</cache-folder>
-     <binding-addr xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">localhost</binding-addr>
-     <binding-port xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">5000</binding-port>
-   </module>
+    <yanglib-config xmlns="urn:opendaylight:params:xml:ns:yang:controller:yanglib:impl">
+        <cache-folder>cache/newSchema</cache-folder>
+        <binding-addr>localhost</binding-addr>
+        <binding-port>8181</binding-port>
+    </yanglib-config>
 
 This should result in a 2xx response and new YANGLIB instance should be
 created. This YANGLIB takes all YANG sources from /sources folder and
@@ -769,7 +847,7 @@ for each generates URL in form:
 
 ::
 
-    http://localhost:5000/schemas/{modelName}/{revision}
+    http://localhost:8181/yanglib/schemas/{modelName}/{revision}
 
 On this URL will be hosted YANG source for particular module.