From a0f325f0b6ca0129ed339ac4ac94d7159e926977 Mon Sep 17 00:00:00 2001 From: mhemmatp Date: Thu, 12 Dec 2019 16:05:13 +0100 Subject: [HICN-440] Add comments to hicn sysrepo plugin code Signed-off-by: mhemmatp Change-Id: I0ed0c5b0b9cd7714b46867e4d4fe0324945cf418 --- .../hicn-plugin/plugin/mainpage.dox | 245 +++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 ctrl/sysrepo-plugins/hicn-plugin/plugin/mainpage.dox (limited to 'ctrl/sysrepo-plugins/hicn-plugin/plugin/mainpage.dox') diff --git a/ctrl/sysrepo-plugins/hicn-plugin/plugin/mainpage.dox b/ctrl/sysrepo-plugins/hicn-plugin/plugin/mainpage.dox new file mode 100644 index 000000000..dc4289379 --- /dev/null +++ b/ctrl/sysrepo-plugins/hicn-plugin/plugin/mainpage.dox @@ -0,0 +1,245 @@ +/** @mainpage About hICN sysrepo plugin +*This plugin serves as a data management agent. It provides yang models via +*NETCONF to allow the management of hicn-plugin which runs in VPP instance from out-of-box. + +*The following sections contain more details: +*- @subpage subp1 "hICN yang model" +*- @subpage subp2 "User Guide" +*- @subpage subp3 "Developer Guide" +*/ + +/** @page subp1 +*hicn.yang consists of one container for providing the state data (i.e., hicn-state). +*It consists of state, route, and face-ip-params +*nodes with the corresponding leaves. In the hicn model a variety of RPCs are provided +*to allow controller to communicate with the hicn-plugin as well as update the state +*data in hicn-state. You can install the yang model using the following bash script: + +``` +EXIT_CODE=0 +command -v sysrepoctl > /dev/null +if [ $? != 0 ]; then + echo "Could not find command \"sysrepoctl\"." + exit ${EXIT_CODE} +else +sysrepoctl --install path_to_hicn_yang_model +fi +``` + +*Here you can find different examples to run RPC in the yang-model. + +``` + + 192.168.1.10 + -1 + 192.168.1.1 + -1 + 0 + + + + 192.168.1.1 + -1 + 24 + 0 + 0 + 0 + 0 + 0 + 0 + 0 + 1 + + + + 192.168.1.1 + -1 + 24 + 0 + + + + + 0 + + + + + 192.168.0.1 + -1 + 24 + 0 + +``` + */ + +/** @page subp2 + +*Firstly, verify the plugin and binary libraries are located correctly, then run +*the vpp through (service vpp start). Next, run the sysrepo plugin (sysrepo-plugind), +*for debug mode: sysrep-plugind -d -v 4 which +*runs with high verbosity. When the hicn sysrepo plugin is loaded, run the +*netopeer2-server which serves as NETCONF server. + + +*## Connect from netopeer2-cli + +*In order to connect through the netopeer client run the netopeer2-cli. Then, follow these steps: +``` +*- connect --host XXX --login XXX +*- get (you can get the configuration and operational data) +*- user-rpc (you can call one of the rpc proposed by hicn model but it needs an xml input) +``` + +*## Connect from OpenDaylight (ODL) controller + + +*In order to connect through the OpenDaylight follow these procedure: + +*- run karaf distribution (./opendayligh_installation_folder/bin/karaf) +*- install the required feature list in DOL (feature:install odl-netconf-server +* odl-netconf-connector odl-restconf-all odl-netconf-topology or +* odl-netconf-clustered-topology) +*- run a rest client program (e.g., postman or RESTClient) +*- mount the remote netopeer2-server to the OpenDaylight by the following REST API: + +*PUT http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/hicn-node + +* with the following body +``` + + hicn-node + Remote_NETCONF_SERVER_IP + 830 + username + password + false + 1 + +``` +*Note that the header files must be set to Content-Type: application/xml, Accept: application/xml. + +*- send the operation through the following REST API: + +*POST http://localhost:8181/restconf/operations/network-topology:network-topology/topology/topology-netconf/node/hicn-node/yang-ext:mount/ietf-netconf:edit-config + +*The body can be used the same as edit-config in netopeer2-cli. + +*## Connect from Network Services Orchestrator (NSO) + +*To connect NSO to the netopeer2-server, first, you need to write a NED package +*for your device. The procedure to create NED for hicn is explained in the following: + +*Place hicn.yang model in a folder called hicn-yang-model, and follow these steps: + +*- ncs-make-package --netconf-ned ./hicn-yang-model ./hicn-nso +*- cd hicn-nso/src; make +*- ncs-setup --ned-package ./hicn-nso --dest ./hicn-nso-project +*- cd hicn-nso-project +*- ncs +*- ncs_cli -C -u admin +*- configure +*- devices authgroups group authhicn default-map remote-name user_name remote-password password +*- devices device hicn address IP_device port 830 authgroup authhicn device-type netconf +*- state admin-state unlocked +*- commit +*- ssh fetch-host-keys + + +*At this point, we are able to connect to the remote device. + + + */ + + /** @page subp3 + +*This guide contains information intended for developers that need to extend/modify the hICN yang model. + +*# Adding configuration data +*In order to add configuration data, firstly it requires to update yang model and define the configuration paramters +*through a container and define the leaves. Once the yang model is updated in the sysrepo plugin you need to subscribe +*for ```sr_module_change_subscribe``` and provide the appropriate callback. +* +* +*# Adding new RPC +* +*In order to add RPC call, firstly it requires to update the yang model by new ```rpc``` statements and define the input to them. + + +*# Adding new operational data +* +*In order to add operational data, firstly it requires to add operational data in yang model by adding ```confg false``` to the container. +*Then, update the sysrepo plugin by the adding the ```sr_oper_get_items_subscribe```. + + Example: +I have a switch with two ports. I am going to write an RPC call to switch them on/off +, moreover I need to read operational data from each port. So, the following yang model can be proposed: + +``` +module switch { +namespace "urn:sysrepo:switch"; +prefix swtch; + +revision 2019-12-08{ + description "Initial revision."; +} + + +grouping status-reply{ + list port{ + key portid; + leaf portid { + description "the port id."; + type uint32; + } + leaf status { + description "the status of the port."; + type boolean; + } + +} +} + +rpc power { + description "Operation to power on/off switch."; + input { + leaf turned-on { + description "indicating on or off."; + type boolean; + default false; + } + } +} + + +container switch-state { + + config false; + description "operational data container for the switch."; + container status{ + uses status-reply; + } +``` +Afterwards, the following subscribes are required in the sysrepo plugin. + +``` +sr_rpc_subscribe(session, "/switch:power", callback, + session, 100,SR_SUBSCR_CTX_REUSE, subscription); + +``` + +session is the opened session with sysrepo, xpath is the path in the yang model, callback is the function +when RPC arrives, private context passed to the callback function, priprity which is set to 100 here indicates the priority if there re multiple RPCs, +options can alter the normal behaviour, and subscription is the subscribtion when initialize the connection towards the sysrepo + + +``` + rc = sr_oper_get_items_subscribe(session, "switch","/switch:switch-state/status", + callback, NULL, SR_SUBSCR_CTX_REUSE, + subscription); +``` +session is the opened session with sysrepo, xpath is the path in the yang model, callback is the function +when RPC arrives, private context passed to the callback which is NULL here, +options can alter the normal behaviour, and subscription is the subscribtion when initialize the connection towards the sysrepo + +*/ \ No newline at end of file -- cgit 1.2.3-korg