diff options
Diffstat (limited to 'ctrl/sysrepo-plugins/hicn-plugin/plugin/mainpage.dox')
| -rw-r--r-- | ctrl/sysrepo-plugins/hicn-plugin/plugin/mainpage.dox | 245 |
1 files changed, 245 insertions, 0 deletions
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. + +``` +<face-ip-add xmlns="urn:sysrepo:hicn"> + <lip4>192.168.1.10</lip4> + <lip6>-1</lip6> + <rip4>192.168.1.1</rip4> + <rip6>-1</rip6> + <swif>0</swif> +</face-ip-add> + +<route-nhops-add xmlns="urn:sysrepo:hicn"> + <ip4>192.168.1.1</ip4> + <ip6>-1</ip6> + <len>24</len> + <face_ids0>0</face_ids0> + <face_ids1>0</face_ids1> + <face_ids2>0</face_ids2> + <face_ids3>0</face_ids3> + <face_ids4>0</face_ids4> + <face_ids5>0</face_ids5> + <face_ids6>0</face_ids6> + <n_faces>1</n_faces> +</route-nhops-add> + +<route-nhops-del xmlns="urn:sysrepo:hicn"> + <ip4>192.168.1.1</ip4> + <ip6>-1</ip6> + <len>24</len> + <faceid>0</faceid> +</route-nhops-del> + + +<face-ip-del xmlns="urn:sysrepo:hicn"> + <faceid>0</faceid> +</face-ip-del> + + +<punting-del-ip xmlns="urn:sysrepo:hicn"> + <ip4>192.168.0.1</ip4> + <ip6>-1</ip6> + <len>24</len> + <swif>0</swif> +</punting-del-ip> +``` + */ + +/** @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 +``` + <node xmlns="urn:TBD:params:xml:ns:yang:network-topology"> + <node-id>hicn-node</node-id> + <host xmlns="urn:opendaylight:netconf-node-topology">Remote_NETCONF_SERVER_IP</host> + <port xmlns="urn:opendaylight:netconf-node-topology">830</port> + <username xmlns="urn:opendaylight:netconf-node-topology">username</username> + <password xmlns="urn:opendaylight:netconf-node-topology">password</password> + <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only> + <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">1</keepalive-delay> + </node> +``` +*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 |