diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/apps.md | 38 | ||||
-rw-r--r-- | docs/source/control.md | 159 | ||||
-rw-r--r-- | docs/source/hicn-light.md | 5 | ||||
-rw-r--r-- | docs/source/index.rst | 4 | ||||
-rw-r--r-- | docs/source/interface.md | 63 | ||||
-rw-r--r-- | docs/source/lib.md | 4 | ||||
-rw-r--r-- | docs/source/started.md | 54 | ||||
-rw-r--r-- | docs/source/transport.md | 11 | ||||
-rw-r--r-- | docs/source/utils.md | 8 |
9 files changed, 245 insertions, 101 deletions
diff --git a/docs/source/apps.md b/docs/source/apps.md index 9b2384f29..1c44a8ca9 100644 --- a/docs/source/apps.md +++ b/docs/source/apps.md @@ -1,12 +1,12 @@ -# Application examples using hICN stack +# Applications -## Introduction +The open source distribution provides a few application examples: +one MPEG-DASH video player, and an HTTP reverse proxy a command line +HTTP GET client. +hICN sockets have been succesfully used to serve HTTP, RTP and +RSockets application protocols. -higet and hicn-http-proxy are two application examples that use hicn stack. - -## Using hICN Application Examples - -### Dependencies +## Dependencies Build dependencies: @@ -73,7 +73,7 @@ Example: The hICN names used by higet for naming the HTTP requests are composed the same way as described in [hicn-http-proxy](#hicn-http-proxy). -### How To Setup A Simple HTTP Client-Server Scenario using the hicn-http-proxy +## HTTP Client-Server with hicn-http-proxy We consider the following topology, consisting on two linux VM which are able to communicate through an IP network (you can also use containers or physical machines): @@ -94,29 +94,15 @@ For running the hicn-plugin at the server there are two main alternatives: - Use a docker container - Run the hicn-plugin directly in a VM or Bare Metal Server -#### Docker +### Docker Install docker in the server VM: ```bash -server$ sudo apt-get update -server$ sudo apt-get install \ - apt-transport-https \ - ca-certificates \ - curl \ - gnupg-agent \ - software-properties-common - -server$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - -server$ sudo add-apt-repository \ - "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ - $(lsb_release -cs) \ - stable" -server$ sudo apt-get update -server$ sudo apt-get install docker-ce docker-ce-cli containerd.io +server$ curl get.docker.com | bash ``` -Run the hicn-http-proxy container. Here we use a public server [example.com](example.com) as origin: +Run the hicn-http-proxy container. Here we use a public server "example.com" as origin: ```bash server$ docker run -e ORIGIN_ADDRESS=example.com \ @@ -204,7 +190,7 @@ Run the http client [higet](#higet) and print the http response on stdout: client$ /usr/bin/higet -O - http://webserver/index.html -P c001 ``` -#### Host/VM +### Host/VM You can install the hicn-plugin of vpp on your VM and directly use DPDK compatible nics, forwarding hicn packets directly over the network. DPDK compatible nics can be used inside a container as well. diff --git a/docs/source/control.md b/docs/source/control.md index f94d3f3b9..e8d42bffa 100644 --- a/docs/source/control.md +++ b/docs/source/control.md @@ -1,31 +1,57 @@ -# Sysrepo plugin for hicn-plugin +# Control Plane Support -These plugins serve as a data management agent. They provide yang models via -NETCONF to allow the management of hicn-light, and hicn VPP plugin. +Control plane functionalities are provides via SDN controllers or via standard +IP routing protocols. SDN support is provided by using the NETCONF/YANG protocol +for network management, control and telemetry. -## Software Requirement +Routing is supported via synchronization of the IP FIB and the IP RIB as implemented +by one of the routng protocols in FRR. Without loss of generality we have reported +below one example of IGP routing via OSPF for IPv6. +The VPP IP FIB can be controlled and updated by one FRR routing protocol which +is used for routing over locators and also over hICN name prefixes. -- VPP -- sysrepo -- hicn-plugin -- hicn-light +## NETCONF/YANG -- libyang -- sysrepo -- libnetconf -- netopeer2 +### Getting started + +NETCONF/YANG support is provided via several external components such as +libyang, sysrepo, libnetconf and netopeer. +The hicn project provides a sysrepo plugin and a YANG model for two devices: +the VPP based hicn virtual switch and the portable forwarder. +The YANG model for the VPP based hICN vSwitch is based the full hICN C API +exported by the VPP plugin with the addition of some VPP APIs such as +interface and FIB management which are required by the hICN plugin. To install libyang, sysrepo, libnetconf and netopeer2 for Ubuntu18 amd64/arm64 -and ad-hoc repository is available and maintained in bintray. +or CentOS 7 and ad-hoc repository is available and maintained in bintray +at <https://dl.bintray.com/icn-team/apt-hicn-extras>. + +For instance in Ubuntu 18 LTS: + +Install the sysrepo YANG data store and a NETCONF server. ```shell -echo "deb [trusted=yes] https://dl.bintray.com/icn-team/apt-hicn-extras bionic main" | tee -a /etc/apt/sources.list +echo "deb [trusted=yes] https://dl.bintray.com/icn-team/apt-hicn-extras bionic main" \ + | tee -a /etc/apt/sources.list apt-get update && apt-get install -y libyang sysrepo libnetconf2 netopeer2-server ``` -## hICN yang model +Install the VPP based hICN virtual switch. -You can install the yang model using the following bash script: +```shell +curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | bash +apt-get update && apt-get install -y hicn-plugin vpp-plugin-dpdk hicn-sysrepo-plugin +``` +The hICN YANG models are install under '/usr/lib/$(uname -m)-linux-gnu/modules_yang'. +Configure the NETCONF/YANG components + +```shell +bash /usr/bin/setup.sh sysrepoctl /usr/lib/$(uname -m)-linux-gnu/modules_yang root +bash /usr/bin/merge_hostkey.sh sysrepocfg openssl +bash /usr/bin/merge_config.sh sysrepocfg genkey +``` + +You can manually install the yang model using the following bash script: ```shell EXIT_CODE=0 @@ -38,18 +64,32 @@ sysrepoctl --install --yang=path_to_hicn_yang_model fi ``` +### YANG model + 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 + +```text +|--+ hicn-conf: holds the configuration data; +| |--+ params: contains all configuration parameters; +|--+ hicn-state: provides the state data +| |--+ state, +| |--+ strategy, +| |--+ strategies, +| |--+ route, +| |--+ face-ip-params +and corresponding leaves. +``` + +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 +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. +### Example + To setup the startup configuration you can use the following script: ```shell @@ -79,7 +119,7 @@ startup.xml is placed in the yang-model. Here you can find the content: </hicn-conf> ``` -As can be seen, it contains the leaves of the params in hicn-conf node which is +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 @@ -162,7 +202,7 @@ controler_rpcs_instances.xml in the yang-model. Here you can find the content: </punting-del> ``` -## Run the plugin +#### 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), @@ -171,7 +211,7 @@ 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 +#### Connect from netopeer2-cli In order to connect through the netopeer client run the netopeer2-cli. Then, follow these steps: @@ -198,7 +238,7 @@ You can modify the configuration but it needs an xml configuration input - user-rpc (you can call one of the rpc proposed by hicn model but it needs an xml input) -## Connect from OpenDaylight (ODL) controller +#### Connect from OpenDaylight (ODL) controller In order to connect through the OpenDaylight follow these procedure: @@ -233,7 +273,7 @@ POST <http://localhost:8181/restconf/operations/network-topology:network-topolog The body can be used the same as edit-config in netopeer2-cli. -## Connect from Network Services Orchestrator (NSO) +#### Connect from Cisco 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 @@ -258,4 +298,69 @@ At this point, we are able to connect to the remote device. ## Release note -The current version is compatible with the 20.01 VPP stable and sysrepo devel.
\ No newline at end of file +The current version is compatible with the 20.01 VPP stable and sysrepo devel. + +## Routing plugin for VPP and FRRouting for OSPF6 + +This document describes how to configure the VPP with hicn_router +plugin and FRR to enable the OSPF protocol. The VPP and FRR +are configured in a docker file. + +### DPDK configuration on host machine + +```text +- Install and configure DPDK +- make install T=x86_64-native-linux-gcc && cd x86_64-native-linux-gcc && sudo make install + - modprobe uio + - modprobe uio_pci_generic + - dpdk-devbind --status + - the PCIe number of the desired device can be observed ("xxx") + - sudo dpdk-devbind -b uio_pci_generic "xxx" +``` + +### VPP configuration + +```text +- Run and configure the VPP (hICN router plugin is required to be installed in VPP) + - set int state TenGigabitEtherneta/0/0 up + - set int ip address TenGigabitEtherneta/0/0 a001::1/24 + - create loopback interface + - set interface state loop0 up + - set interface ip address loop0 b001::1/128 + - enable tap-inject # This creates the taps by router plugin + - show tap-inject # This shows the created taps + - ip mroute add ff02::/64 via local Forward # ff02:: is multicast ip address + - ip mroute add ff02::/64 via TenGigabitEtherneta/0/0 Accept + - ip mroute add ff02::/64 via loop0 Accept +``` + +```text +- Setup the tap interface + - ip addr add a001::1/24 dev vpp0 + - ip addr add b001::1/128 dev vpp1 + - ip link set dev vpp0 up + - ip link set dev vpp1 up +``` + +### FRR configuration + +Install FRR in Ubuntu 18 LTS: +<http://docs.frrouting.org/projects/dev-guide/en/latest/building-frr-for-ubuntu1804.html> + +```text +- Run and configure FRRouting (ospf) + - /usr/lib/frr/frrinit.sh start & + - vtysh + - configure terminal + - router ospf6 + - area 0.0.0.0 range a001::1/24 + - area 0.0.0.0 range b001::1/128 + - interface vpp0 area 0.0.0.0 + - interface vpp1 area 0.0.0.0 + - end + - wr + - add "no ipv6 nd suppress-ra" to the first configurtion part of the /etc/frr/frr.conf +``` + +After the following configuration, the traffic over tap interface can be observered through "tcpdump- i vpp1". +The neighborhood and route can be seen by the "show ipv6 ospf6 neighbor/route". diff --git a/docs/source/hicn-light.md b/docs/source/hicn-light.md index a68af7f05..cee76940b 100644 --- a/docs/source/hicn-light.md +++ b/docs/source/hicn-light.md @@ -1,8 +1,9 @@ -# The Hybrid ICN Portable Forwarder +# Portable Forwarder ## Introduction -hicn-light is a socket based forwarder +hicn-light is a portable forwarder that makes use of IPC and standard sockets +to communicate. ## Using hicn-light diff --git a/docs/source/index.rst b/docs/source/index.rst index 9123734b4..af8818388 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,5 @@ -Hybrid ICN software distribution -================================= +Hybrid Information-Centric Networking +===================================== .. toctree:: diff --git a/docs/source/interface.md b/docs/source/interface.md index c7168ef23..13f1007a3 100644 --- a/docs/source/interface.md +++ b/docs/source/interface.md @@ -1,4 +1,4 @@ -# Face manager : Interfaces +# Face Manager ## Overview @@ -9,7 +9,6 @@ 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 @@ -46,14 +45,16 @@ interfaces: link and address information, interface types, and bonjour service discovery. - ### Architectural overview #### Facelets TODO: + +```text - Key attributes (netdevice and protocol family) - Facelet API +``` #### Events @@ -62,9 +63,12 @@ TODO #### Facelet cache & event scheduling TODO: + +```text - Facelet cache - Joins - How synchronization work +``` ### Interface API @@ -91,7 +95,8 @@ 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: -``` + +```C# /* * Configuration data */ @@ -103,6 +108,8 @@ typedef struct { #### Overview of the interface template The file starts with useful includes: + +```text - 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. @@ -112,10 +119,12 @@ 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: -``` + +```C# /* * Internal data */ @@ -141,7 +150,7 @@ 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: -``` +```C# interface\_ops\_t dummy\_ops = { .type = "dummy", .initialize = dummy_initialize, @@ -152,7 +161,8 @@ interface\_ops\_t dummy\_ops = { ``` The structure itself is declared and documented in `src/interface.h` -``` + +```C /** * \brief Interface operations */ @@ -176,7 +186,7 @@ can be created (see `src/interface.c` for the function prototypes, and - interface registration: -``` +```text extern interface\_ops\_t dummy\_ops; /* [...] */ @@ -188,7 +198,7 @@ if (rc < 0) - interface instanciation: -``` +```C++ #include "interfaces/dummy/dummy.h" /* [...] */ @@ -200,7 +210,7 @@ if (rc < 0) { } ``` -#### Implementation of the interface API +#### 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. @@ -209,7 +219,7 @@ In the template, the constructor is the most involved as it need to: - initialize the internal data structure: -``` +```C# dummy_data_t * data = malloc(sizeof(dummy_data_t)); if (!data) goto ERR_MALLOC; @@ -218,7 +228,7 @@ In the template, the constructor is the most involved as it need to: - process configuration parameters, eventually setting some default values: -``` +```C# /* Use default values for unspecified configuration parameters */ if (cfg) { data->cfg = *(dummy_cfg_t *)cfg; @@ -236,7 +246,7 @@ 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. -``` +```C# data->fd = 0; /* ... */ @@ -263,11 +273,11 @@ 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: -``` +```C++ dummy\_data\_t * data = (dummy\_data\_t*)interface->data; ``` -#### Raising and receiving events +#### 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 @@ -279,7 +289,8 @@ clone it. The facelet event can then be defined and raised to the face maanger for further processing through the following code: -``` + +```C++ facelet_set_event(facelet, EVENT_TYPE_CREATE); interface_raise_event(interface, facelet); ``` @@ -287,8 +298,7 @@ processing through the following code: 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 +#### 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 @@ -296,10 +306,9 @@ local `CMakeLists.txt` file. TODO: detail the structure of the file +### Hands-On -### Hands-on example - -#### Overview +#### Architecture 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 @@ -322,12 +331,12 @@ 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 +#### Sample Server and Client In the folder containing the source code of hICN, the following commands allow to run the sample server: -``` +```shell cd ctrl/facemgr/examples/updownsrv make ./updownsrv @@ -336,7 +345,8 @@ make The server should display "Waiting for clients..." Similar commands allow to run the sample client: -``` + +```shell cd ctrl/facemgr/examples/updowncli make ./updowncli @@ -345,7 +355,7 @@ make The client should display "Waiting for server data...", then every couple of seconds display either "WiFi" or "LTE". -#### Facemanager interface +#### Face Manager Interface An example illustrating how to connect to the dummy service from `updownsrv` is provided as the `updown` interface in the facemgr source code. @@ -353,6 +363,3 @@ 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/docs/source/lib.md b/docs/source/lib.md index 727d496bf..1e7d09e7a 100644 --- a/docs/source/lib.md +++ b/docs/source/lib.md @@ -1,5 +1,5 @@ -# The Hybrid ICN Core Library +# Core Library ## Introduction @@ -30,7 +30,7 @@ A commandline interface (hicnc) is also provided that uses the library and can for instance be used as a test traffic generator. This interface can be run as either a consumer, a producer, or a simple forwarder. -## Folder content +## Directory Layout ```shell . diff --git a/docs/source/started.md b/docs/source/started.md index 099b5f4d9..168ce1272 100644 --- a/docs/source/started.md +++ b/docs/source/started.md @@ -1,5 +1,41 @@ # Getting started +## Introduction + +hicn is an open source implementation of Cisco's hICN. It includes a network stack, that implements +ICN forwarding path in IPv6, and a transport stack that implements two main transport protocols and +a socket API. The transport protocols provide one reliable transport service implementaton and a +real-time transport service for audio/video media. + +## Directory Layout + +```text +| Directory name | Description | +| -------------- | --------------------------------------------------------- | +| lib | Core support library | +| hicn-plugin | VPP plugin | +| hicn-light | Lightweight packet forwarder | +| libtransport | Support library with transport layer and API | +| utils | Tools for testing | +| apps | Application examples using hicn stack | +| ctrl | Tools and libraries for network management and control | +``` + +hicn plugin is a VPP plugin that implement hicn packet processing as specified in +<https://datatracker.ietf.org/doc/draft-muscariello-intarea-hicn/.> The transport library is used to +implement the hicn host stack and makes use of libmemif as high performance connector between +transport and the network stack. The transport library makes use of VPP binary API to configure the +local namespace (local face management). + +## Release note + +The current master branch provides the latest release which is compatible with the lates VPP stable. +No other VPP releases are supported nor maintained. At every new VPP release distribution hicn +master branch is updated to work with the latest stable release. All previous stable releases +are discontinued and not maintained. The user who is interested in a specific release can always +checkout the rigth code tree by searching the latest commit under a given git tag carrying the +release version. + The Hybrid ICN software distribution can be installed for several platforms. The network stack comes in two different implementations: one scalable based on VPP and one portable based on IPC and sockets. @@ -7,7 +43,7 @@ on VPP and one portable based on IPC and sockets. The transport stack is a unique library that is used for both the scalable and portable network stacks. -## Platforms +## Supported Platforms - Ubuntu 18.04 LTS (amd64, arm64) - Debian Stable/Testing @@ -21,13 +57,13 @@ and portable network stacks. Other platforms and architectures may work. You can either use released packages, or compile hicn from sources. -### Ubuntu 18.04/16.04 amd64/arm64 +### Ubuntu ```shell curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash ``` -### CentOS 7 amd64 +### CentOS ```shell curl -s https://packagecloud.io/install/repositories/fdio/release/script.rpm.sh | sudo bash @@ -48,10 +84,20 @@ Install the applications via the Google Play Store Coming soon. -### Windows 10 +### Windows Coming soon. +### Docker + +Several docker images are nightly built with the latest software for Ubuntu 18 LTS (amd64/arm64), and available on docker hub +at <https://hub.docker.com/u/icnteam>. + +### Vagrant + +Vagrant boxes for a virtual switch are available at <https://app.vagrantup.com/icnteam/boxes/vswitch>. +Supported providers are kvm, vmware and virtualbox. + ## License This software is distributed under the following license: diff --git a/docs/source/transport.md b/docs/source/transport.md index 7f8293a78..4719d7227 100644 --- a/docs/source/transport.md +++ b/docs/source/transport.md @@ -9,12 +9,14 @@ Overview: - Implementation of the hICN core objects (interest, data, name..) exploiting the API provided by [libhicn](../lib). - Connectors for connecting the application to either the hicn-plugin or the hicn-light forwarder. -- Transport protocols (RAAQM, CBR, RTP) +- Transport protocols (RAAQM, CBR, RTC) - Transport services (authentication, integrity, segmentation, reassembly, naming) -- Interfaces for Applications (from low-level interfaces for interest-data interaction to high level interfaces for Application Data Unit interaction) +- Interfaces for applications (from low-level interfaces for interest-data interaction to high level interfaces for Application Data Unit interaction) ## Build Dependencies +### Ubuntu + - libparc - libmemif (linux only, if compiling with VPP support) - libasio @@ -28,8 +30,6 @@ If you wish to use the library for connecting to the vpp hicn-plugin, you will n You can get them either from from the vpp packages ot the source code. Check the [VPP wiki](https://wiki.fd.io/view/VPP) for instructions. -Libmemif is in the vpp-lib and vpp-dev packages. - ### macOS We recommend to use [HomeBrew](https://brew.sh/) for installing the libasio dependency: @@ -49,7 +49,6 @@ Download, compile and install libparc: ``` Libparc will be installed by default under `/usr/local/lib` and `/usr/local/include`. - Since VPP does not support macOS, the hicn-plugin connector is not built. ## Build the library @@ -83,4 +82,4 @@ For installing the library, from the cmake build folder: ```bash sudo make install -```
\ No newline at end of file +``` diff --git a/docs/source/utils.md b/docs/source/utils.md index 5b9178b56..57104e12a 100644 --- a/docs/source/utils.md +++ b/docs/source/utils.md @@ -116,7 +116,7 @@ Example: hiperf -S c001::/64 ``` -## How To Benchmark Client-Server Throughput using hiperf +## Client-Server Benchmarking using hiperf ### hicn-light-daemon @@ -151,7 +151,7 @@ $ export HICN_ROOT=${PWD}/../hicn-install It should install the hICN suite under hicn-install. -#### hICN stack based on hicn-light forwarder with UDP faces +#### hicn-light forwarder with UDP faces ##### Server Configuration @@ -214,7 +214,7 @@ EOF This will run the client with a fixed window of 50 interests. -#### Using hicn-light forwarder with hICN faces +#### hicn-light forwarder with hICN faces For sending hICN packets directly over the network, using hicn faces, change the configuration of the two forwarders and restart them. @@ -245,7 +245,7 @@ add route conn0 b001::/16 1 EOF ``` -### vpp based hicn-plugin +### VPP based hicn-plugin Compile the hicn stack enabling the [vpp](https://github.com/FDio/vpp) support. |