diff options
Diffstat (limited to 'ctrl')
| -rw-r--r-- | ctrl/facemgr/doc/interface.md | 358 | ||||
| -rw-r--r-- | ctrl/sysrepo-plugins/README.md | 241 |
2 files changed, 0 insertions, 599 deletions
diff --git a/ctrl/facemgr/doc/interface.md b/ctrl/facemgr/doc/interface.md deleted file mode 100644 index c7168ef23..000000000 --- a/ctrl/facemgr/doc/interface.md +++ /dev/null @@ -1,358 +0,0 @@ -# Face manager : Interfaces - -## Overview - -The architecture of the face manager is built around the concept of interfaces, -which allows for a modular and extensible deployment. - -Interfaces are used to implement in isolation various sources of information -which help with the construction of faces (such as network interface and service -discovery), and with handling the heterogeneity of host platforms. - - -### Platform and supported interfaces - -Currently, Android, Linux and MacOS are supported through the following -interfaces: - -- hicn-light [Linux, Android, MacOS, iOS] - An interface to the hicn-light forwarder, and more specifically to the Face - Table and FIB data structures. This component is responsible to effectively - create, update and delete faces in the forwarder, based on the information - provided by third party interfaces, plus adding default routes for each of - the newly created face. The communication with the forwarder is based on the - hicn control library (`libhicnctrl`). - -- netlink [Linux, Android] - The default interface on Linux systems (including Android) to communicate - with the kernel and receive information from various sources, including link - and address information (both IPv4 and IPv6) about network interfaces. - -- android\_utility [Android only] - Information available through Netlink is limited with respect to cellular - interfaces. This component allows querying the Android layer through SDK - functions to get the type of a given network interface (Wired, WiFi or - Cellular). - -- bonjour [Linux, Android] - This component performs remote service discovery based on the bonjour - protocol to discover a remote hICN forwarder that might be needed to - establish overlay faces. - -- network\_framework [MacOS, iOS] - - This component uses the recommended Network framework on Apple devices, - which provided all required information to query faces in a unified API: - link and address information, interface types, and bonjour service - discovery. - - -### Architectural overview - -#### Facelets - -TODO: -- Key attributes (netdevice and protocol family) -- Facelet API - -#### Events - -TODO - -#### Facelet cache & event scheduling - -TODO: - - Facelet cache - - Joins - - How synchronization work - -### Interface API - -TODO - -## Developing a new interface - -### Dummy template - -The face manager source code includes a template that can be used as a skeleton -to develop new faces. It can be found in `src/interface/dummy/dummy.{h,c}`. Both -include guard and specific interface functions are prefixed by a (short) -identifier which acts as a namespace for interface specific code (in our case -the string 'dummy\_'). - -Registration and instanciation of the different interfaces is currently done at -compile time in the file `src/api.c`, and the appropriate hooks to use the dummy -interface are avaialble in the code between `#if 0/#endif` tags. - -#### Interface template header; configuration parameters - -All interfaces have a standard interface defined in `src/interface.{h,c}`, and -as such the header file is only used to specify the configuration parameters of -the interface, if any. - -In the template, these configuration options are empty: -``` -/* - * Configuration data - */ -typedef struct { - /* ... */ -} dummy_cfg_t; -``` - -#### Overview of the interface template - -The file starts with useful includes: -- the global include `<hicn/facemgr.h>` : this provides public facing elements - of the face manager, such the standard definition of faces (`face_t` from - `libhicnctrl`), helper classes (such as `ip_address_t` from `libhicn`), etc. -- common.h -- facelet.h : facelets are the basic unit of communication between the face -manager and the different interfaces. They are used to construct the faces -incrementally. -- interface.h : the parent class of interfaces, such as the current dummy -interface. - -Each interface can hold a pointer to an internal data structure, which is -declared as follows: -``` -/* - * Internal data - */ -typedef struct { - /* The configuration data will likely be allocated on the stack (or should - * be freed) by the caller, we recommend to make a copy of this data. - * This copy can further be altered with default values. - */ - dummy_cfg_t cfg; - - /* ... */ - - int fd; /* Sample internal data: file descriptor */ -} dummy_data_t; -``` - -We find here a copy of the configuration settings (which allows the called to -instanciate the structure on the stack), as well as a file descriptor -(assuming most interfaces will react on events on a file descriptor). - -The rest of the file consists in the implementation of the interface, in -particular the different function required by the registration of a new -interface to the system. They are grouped as part of the `interface_ops_t` data -structure declared at the end of the file: - -``` -interface\_ops\_t dummy\_ops = { - .type = "dummy", - .initialize = dummy_initialize, - .finalize = dummy_finalize, - .callback = dummy_callback, - .on_event = dummy_on_event, -}; -``` - -The structure itself is declared and documented in `src/interface.h` -``` -/** - * \brief Interface operations - */ -typedef struct { - /** The type given to the interfaces */ - char * type; - /* Constructor */ - int (*initialize)(struct interface\_s * interface, void * cfg); - /* Destructor */ - int (*finalize)(struct interface_s * interface); - /* Callback upon file descriptor event (iif previously registered) */ - int (*callback)(struct interface_s * interface); - /* Callback upon facelet events coming from the face manager */ - int (*on_event)(struct interface_s * interface, const struct facelet_s * facelet); -} interface\_ops\_t; -``` - -Such an interface has to be registered first, then one (or multiple) instance(s) -can be created (see `src/interface.c` for the function prototypes, and -`src/api.c` for their usage). - -- interface registration: - -``` -extern interface\_ops\_t dummy\_ops; - -/* [...] */ - -rc = interface\_register(&dummy\_ops); -if (rc < 0) - goto ERR_REGISTER; -``` - -- interface instanciation: - -``` -#include "interfaces/dummy/dummy.h" - -/* [...] */ - -rc = facemgr_create_interface(facemgr, "dummy0", "dummy", &facemgr->dummy); -if (rc < 0) { - ERROR("Error creating 'Dummy' interface\n"); - goto ERR_DUMMY_CREATE; -} -``` - -#### Implementation of the interface API - -We now quickly go other the different functions, but their usage will be better -understood through the hands-on example treated in the following section. - -In the template, the constructor is the most involved as it need to: - -- initialize the internal data structure: - -``` - dummy_data_t * data = malloc(sizeof(dummy_data_t)); - if (!data) - goto ERR_MALLOC; - interface->data = data; -``` - -- process configuration parameters, eventually setting some default values: - -``` - /* Use default values for unspecified configuration parameters */ - if (cfg) { - data->cfg = *(dummy_cfg_t *)cfg; - } else { - memset(&data->cfg, 0, sizeof(data->cfg)); - } -``` - -- open an eventually required file descriptor - -For the sake of simplicity, the current API only supports a single file -descriptor per-interface, and it has to be created in the constructor, and -set as the return value so as to be registered by the system, and added to the -event loop for read events. A return value of 0 means the interface does not -require any file descriptor. As usual, a negative return value indicates an -error. - -``` - data->fd = 0; - - /* ... */ - - /* - * We should return a negative value in case of error, and a positive value - * otherwise: - * - a file descriptor (>0) will be added to the event loop; or - * - 0 if we don't use any file descriptor - */ - return data->fd; -``` - -While support for multiple file descriptors might be added in the future, an -alternative short-term implementation might consider the instanciation of -multiple interface, as is done for Bonjour in the current codebase, in -`src/api.c`. - -Data reception on the file descriptor will get the callback function called, in -our case `dummy_callback`. Finally, the destructor `dummy_finalize` should close -an eventual open file descriptor. - -In order to retrieve the internal data structure, that should in particular -store such a file descriptor, all other function but the constructor can -dereference it from the interface pointer they receive as parameter: - -``` -dummy\_data\_t * data = (dummy\_data\_t*)interface->data; -``` - -#### Raising and receiving events - -An interface will receive events in the form of a facelet through the `*_on_event` -function. It can then use the facelet API we have describe above to read -information about the face. - -As this information is declared const, the interface can either create a new -facelet (identified by the same netdevice and protocol family), or eventually -clone it. - -The facelet event can then be defined and raised to the face maanger for further -processing through the following code: -``` - facelet_set_event(facelet, EVENT_TYPE_CREATE); - interface_raise_event(interface, facelet); -``` - -Here the event is a facelet creation (`EVENT_TYPE_CREATE`). The full facelet API -and the list of possible event types is available in `src/facelet.h` - - -#### Integration in the build system - -The build system is based on CMake. Each interface should declare its source -files, private and public header files, as well as link dependencies in the -local `CMakeLists.txt` file. - -TODO: detail the structure of the file - - -### Hands-on example - -#### Overview - -In order to better illustrate the development of a new interface, we will -consider the integration of a sample server providing a signal instructing the -face manager to alternatively use either the WiFi or the LTE interface. The code -of this server is available in the folder `examples/updownsrv/`, and the -corresponding client code in `examples/updowncli`. - -Communication between client and server is done through unix sockets over an -abstract namespace (thereby not using the file system, which would cause issues -on Android). The server listens for client connections, and periodically -broadcast a binary information to all connected clients, in the form of one byte -equal to either \0 (which we might interpret as enable LTE, disable WiFi), or \1 -(enable WiFi, disable LTE). - -Our objective is to develop a new face manager interface that would listen to -such event in order to update the administrative status of the current faces. -This would thus alternatively set the different interfaces admnistratively up -and down (which takes precedence over the actual status of the interface when -the forwarder establishes the set of available next hops for a given prefix). -The actual realization of such queries will be ultimately performed by the -hicn-light interface. - -#### Sample server and client - -In the folder containing the source code of hICN, the following commands allow -to run the sample server: - -``` -cd ctrl/facemgr/examples/updownsrv -make -./updownsrv -``` - -The server should display "Waiting for clients..." - -Similar commands allow to run the sample client: -``` -cd ctrl/facemgr/examples/updowncli -make -./updowncli -``` - -The client should display "Waiting for server data...", then every couple of -seconds display either "WiFi" or "LTE". - -#### Facemanager interface - -An example illustrating how to connect to the dummy service from `updownsrv` is -provided as the `updown` interface in the facemgr source code. - -This interface periodically swaps the status of the LTE interface up and down. -It is instanciated as part of the facemgr codebase when the code is compiled -with the ``-DWITH_EXAMPLE_UPDOWN` cmake option. - - - diff --git a/ctrl/sysrepo-plugins/README.md b/ctrl/sysrepo-plugins/README.md deleted file mode 100644 index 0940fff67..000000000 --- a/ctrl/sysrepo-plugins/README.md +++ /dev/null @@ -1,241 +0,0 @@ -# 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 |