[HICN-512] documentation bundle using sphinx

Change-Id: I1dcbca50f7406ef2714683547b6bb32463e1baf8
Signed-off-by: Luca Muscariello <muscariello@ieee.org>

1 files changed, 241 insertions, 0 deletions

diff --git a/docs/source/control.md b/docs/source/control.md
new file mode 100644
index 000000000..0940fff67
--- /dev/null
+++ b/docs/source/control.md
@@ -0,0 +1,241 @@
+# Sysrepo plugin for hicn-plugin  (2019)
+
+These plugins serve as a data management agent. They provide yang models via
+NETCONF to allow the management of hicn-light, and hicn-plugin which runs in VPP
+instance from out-of-box.
+
+## Software Requirement
+
+- VPP
+
+- sysrepo
+
+- hicn-plugin
+
+- hicn-light
+
+## hICN yang model
+
+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 --yang=path_to_hicn_yang_model
+fi
+```
+hicn.yang can be found in the yang-model. It consists of two container nodes:
+hicn-conf and hicn-state. One is used to hold the configuration data (i.e.,
+hicn-conf) and one for providing the state data (i.e., hicn-state). The
+hicn-conf has one node, params, which contains the hICN configuration
+parameters. A controller can configure these parameters through the edit-config RPC
+call. This node can be used to enable and to initialize the hicn-plugin in VPP
+instance. Hicn-state container is used to provide the state data to the
+controller. It consists of state, strategy, strategies, 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.
+
+To setup the startup configuration you can use the following script:
+```
+EXIT_CODE=0
+command -v sysrepocfg > /dev/null
+if [ $? != 0 ]; then
+    echo "Could not find command \"sysrepocfg\"."
+     exit ${EXIT_CODE}
+else
+sysrepocfg -d startup -i path_to_startup_xml -f xml hicn
+fi
+```
+
+startup.xml is placed in the yang-model. Here you can find the content:
+```
+<hicn-conf  xmlns="urn:sysrepo:hicn">
+<params>
+    <enable_disable>false</enable_disable>
+    <pit_max_size>-1</pit_max_size>
+    <cs_max_size>-1</cs_max_size>
+    <cs_reserved_app>-1</cs_reserved_app>
+    <pit_dflt_lifetime_sec>-1</pit_dflt_lifetime_sec>
+    <pit_max_lifetime_sec>-1</pit_max_lifetime_sec>
+    <pit_min_lifetime_sec>-1</pit_min_lifetime_sec>
+</params>
+</hicn-conf>
+```
+As can be seen, it contains the leaves of the params in hicn-conf node which is
+used as the startup configuration. This configuration can be changed through the
+controller by subscribing which changes the target to the running state. hicn
+yang model provides a list of RPCs which allows controller to communicate
+directly with the hicn-plugin. This RPCs may also cause the modification in
+state data.
+
+In order to run different RPCs from controller you can use the examples in the
+controler_rpcs_instances.xml in the yang-model. Here you can find the content:
+```
+<node-params-get xmlns="urn:sysrepo:hicn"/>
+
+<node-stat-get xmlns="urn:sysrepo:hicn"/>
+
+<strategy-get xmlns="urn:sysrepo:hicn">
+    <strategy_id>0</strategy_id>
+</strategy-get>
+
+<strategies-get xmlns="urn:sysrepo:hicn"/>
+
+<route-get xmlns="urn:sysrepo:hicn">
+    <prefix0>10</prefix0>
+    <prefix1>20</prefix1>
+    <len>30</len>
+</route-get>
+
+<route-del xmlns="urn:sysrepo:hicn">
+    <prefix0>10</prefix0>
+    <prefix1>20</prefix1>
+    <len>30</len>
+</route-del>
+
+<route-nhops-add xmlns="urn:sysrepo:hicn">
+    <prefix0>10</prefix0>
+    <prefix1>20</prefix1>
+    <len>30</len>
+    <face_ids0>40</face_ids0>
+    <face_ids1>50</face_ids1>
+    <face_ids2>60</face_ids2>
+    <face_ids3>70</face_ids3>
+    <face_ids4>80</face_ids4>
+    <face_ids5>90</face_ids5>
+    <face_ids6>100</face_ids6>
+    <n_faces>110</n_faces>
+</route-nhops-add>
+
+<route-nhops-del xmlns="urn:sysrepo:hicn">
+    <prefix0>10</prefix0>
+    <prefix1>20</prefix1>
+    <len>30</len>
+    <faceid>40</faceid>
+</route-nhops-del>
+
+<face-ip-params-get xmlns="urn:sysrepo:hicn">
+    <faceid>10</faceid>
+</face-ip-params-get>
+
+<face-ip-add xmlns="urn:sysrepo:hicn">
+    <nh_addr0>10</nh_addr0>
+    <nh_addr1>20</nh_addr1>
+    <swif>30</swif>
+</face-ip-add>
+
+<face-ip-del xmlns="urn:sysrepo:hicn">
+    <faceid>0</faceid>
+</face-ip-del>
+
+<punting-add xmlns="urn:sysrepo:hicn">
+    <prefix0>10</prefix0>
+    <prefix1>20</prefix1>
+    <len>30</len>
+    <swif>40</swif>
+</punting-add>
+
+<punting-del xmlns="urn:sysrepo:hicn">
+    <prefix0>10</prefix0>
+    <prefix1>20</prefix1>
+    <len>30</len>
+    <swif>40</swif>
+</punting-del>
+```
+
+## Run the plugin
+
+Firstly, verify the plugin and binary libraries are located correctly, then run
+the vpp through (service vpp start). Next, run the sysrepo daemon (sysrepod),
+for debug mode: sysrepo -d -l 4 which runs with high verbosity. Then, run the
+sysrepo plugin (sysrepo-plugind), for debug mode: sysrep-plugind -d -l 4 which
+runs with high verbosity. Now, the hicn sysrepo plugin is loaded. Then, 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)
+- get-config (you can get the configuration data)
+- edit-config --target running --config
+  you can modify the configuration but it needs an xml configuration input
+```
+<hicn-conf  xmlns="urn:sysrepo:hicn">
+<params>
+    <enable_disable>false</enable_disable>
+    <pit_max_size>-1</pit_max_size>
+    <cs_max_size>-1</cs_max_size>
+    <cs_reserved_app>-1</cs_reserved_app>
+    <pit_dflt_lifetime_sec>-1</pit_dflt_lifetime_sec>
+    <pit_max_lifetime_sec>-1</pit_max_lifetime_sec>
+    <pit_min_lifetime_sec>-1</pit_min_lifetime_sec>
+</params>
+</hicn-conf>
+```
+- 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.
+
+## Release note
+
+The current version is compatible with the 19.01 VPP stable and sysrepo 0.7.7.
\ No newline at end of file