diff options
| -rw-r--r-- | docs/README.md | 23 | ||||
| -rw-r--r-- | docs/source/apps.md | 21 | ||||
| -rw-r--r-- | docs/source/control.md | 50 | ||||
| -rw-r--r-- | docs/source/hicn-light.md | 92 | ||||
| -rw-r--r-- | docs/source/index.rst | 3 | ||||
| -rw-r--r-- | docs/source/lib.md | 78 | ||||
| -rw-r--r-- | docs/source/started.md | 72 | ||||
| -rw-r--r-- | docs/source/transport.md | 80 | ||||
| -rw-r--r-- | docs/source/utils.md | 56 | ||||
| -rw-r--r-- | docs/source/vpp-plugin.md | 143 |
10 files changed, 269 insertions, 349 deletions
diff --git a/docs/README.md b/docs/README.md index c99cf879b..d7a6c6cc8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,27 +1,24 @@ -Building Documents +# Building Documents These instructions show how documentation sources are built. To build your files, you can either Create a Virtual Environment using virtualenv, which installs all the required applications for you. -Create a Virtual Environment using virtualenv -============================ +# Create a Virtual Environment using virtualenv For more information on how to use the Python virtual environment check -out https://packaging.python.org/guides/installing-using-pip-and-virtualenv +out <https://packaging.python.org/guides/installing-using-pip-and-virtualenv> -Get the Documents ------------------------------- +# Get the Documents -For example start with a clone of the vpp. +For example start with a clone of the hicn. -$ git clone https://gerrit.fd.io/r/hicn +$ git clone <https://gerrit.fd.io/r/hicn> $ cd hicn -Install the virtual environment ----------------------------------------------- +# Install the virtual environment $ python3 -m pip install --user virtualenv $ python3 -m virtualenv env @@ -33,16 +30,14 @@ Which installs all the required applications into it's own, isolated, virtual environment, so as to not interfere with other builds that may use different versions of software. -Build the html files ----------------------------- +# Build the html files Be sure you are in your hicn/docs directory, since that is where Sphinx will look for your conf.py file, and build the documents into an index.html file $ make html -View the results ------------------------- +# View the results If there are no errors during the build process, you should now have an index.html file in your hicn/docs/build/html directory, which you can diff --git a/docs/source/apps.md b/docs/source/apps.md index eefb68be1..9b2384f29 100644 --- a/docs/source/apps.md +++ b/docs/source/apps.md @@ -10,7 +10,7 @@ higet and hicn-http-proxy are two application examples that use hicn stack. Build dependencies: -- c++14 ( clang++ / g++ ) +- C++14 ( clang++ / g++ ) - CMake 3.5 or higher Basic dependencies: @@ -283,22 +283,3 @@ Retrieve a web page: ```bash client$ /usr/bin/higet -O - http://webserver/index.html -P c001 ``` - -## License - -This software is distributed under the following license: - -```text -Copyright (c) 2017-2019 Cisco and/or its affiliates. -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at: - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -``` diff --git a/docs/source/control.md b/docs/source/control.md index 0940fff67..f94d3f3b9 100644 --- a/docs/source/control.md +++ b/docs/source/control.md @@ -1,23 +1,33 @@ -# Sysrepo plugin for hicn-plugin (2019) +# Sysrepo plugin for hicn-plugin 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. +NETCONF to allow the management of hicn-light, and hicn VPP plugin. ## Software Requirement - VPP +- sysrepo +- hicn-plugin +- hicn-light +- libyang - sysrepo +- libnetconf +- netopeer2 -- hicn-plugin +To install libyang, sysrepo, libnetconf and netopeer2 for Ubuntu18 amd64/arm64 +and ad-hoc repository is available and maintained in bintray. -- hicn-light +```shell +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 You can install the yang model using the following bash script: -``` + +```shell EXIT_CODE=0 command -v sysrepoctl > /dev/null if [ $? != 0 ]; then @@ -27,6 +37,7 @@ 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 @@ -40,7 +51,8 @@ to allow controller to communicate with the hicn-plugin as well as update the st data in hicn-state. To setup the startup configuration you can use the following script: -``` + +```shell EXIT_CODE=0 command -v sysrepocfg > /dev/null if [ $? != 0 ]; then @@ -52,7 +64,8 @@ fi ``` startup.xml is placed in the yang-model. Here you can find the content: -``` + +```shell <hicn-conf xmlns="urn:sysrepo:hicn"> <params> <enable_disable>false</enable_disable> @@ -65,6 +78,7 @@ startup.xml is placed in the yang-model. Here you can find the content: </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 @@ -74,7 +88,8 @@ 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: -``` + +```shell <node-params-get xmlns="urn:sysrepo:hicn"/> <node-stat-get xmlns="urn:sysrepo:hicn"/> @@ -164,8 +179,10 @@ In order to connect through the netopeer client run the netopeer2-cli. Then, fol - 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 -``` + +You can modify the configuration but it needs an xml configuration input + +```shell <hicn-conf xmlns="urn:sysrepo:hicn"> <params> <enable_disable>false</enable_disable> @@ -178,6 +195,7 @@ In order to connect through the netopeer client run the netopeer2-cli. Then, fol </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 @@ -191,10 +209,11 @@ In order to connect through the OpenDaylight follow these procedure: - 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 +PUT <http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/hicn-node> with the following body -``` + +```shell <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> @@ -205,11 +224,12 @@ with the following body <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 +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. @@ -238,4 +258,4 @@ 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 +The current version is compatible with the 20.01 VPP stable and sysrepo devel.
\ No newline at end of file diff --git a/docs/source/hicn-light.md b/docs/source/hicn-light.md index e321b78e5..a68af7f05 100644 --- a/docs/source/hicn-light.md +++ b/docs/source/hicn-light.md @@ -1,5 +1,4 @@ -The Hybrid ICN Portable Forwarder -============================== +# The Hybrid ICN Portable Forwarder ## Introduction @@ -7,24 +6,11 @@ hicn-light is a socket based forwarder ## Using hicn-light -### Platforms - -hicn-light has been tested in: - -- Ubuntu 16.04 / 18.04 (x86_64) -- Debian Testing -- Centos 7 -- MacOSX 10.12 -- Android -- iOS - -Other platforms and architectures may work. - ### Dependencies Build dependencies: -- c99 ( clang / gcc ) +- C99 ( clang / gcc ) - CMake 3.4 Basic dependencies: @@ -49,7 +35,7 @@ Use the `-h` option to display the help messages The command `hicn-light-daemon` runs the hicn-light forwarder. The forwarder can be executed with the following options: -``` +```shell hicn-light-daemon [--port port] [--daemon] [--capacity objectStoreSize] [--log facility=level] [--log-file filename] [--config file] @@ -81,7 +67,7 @@ default port for hicn-light is 9695. Commands are expected on port 2001. `hicn-light-control` can be used to send command to the hicn-light forwarder and configure it. The command can be executed in the following way: -``` +```shell hicn-light-control [commands] Options: @@ -101,7 +87,7 @@ Information about the commands are also available in the `hicn-light-control` he For local connections (application to hicn-light) we expect a TCP listener. The default port for the local listener is 9695. -``` +```shell add listener <protocol> <symbolic> <local_adress> <local_port> <symbolic> :User defined name for listener, must start with alpha and bealphanum @@ -113,7 +99,7 @@ add listener <protocol> <symbolic> <local_adress> <local_port> `add listener hicn`: creates a hicn listener with the specified options on the local forwarder. -``` +```shell add listener hicn <symbolic> <local_adress> <symbolic> :User defined name for listener, must start with alpha and be alphanum @@ -123,7 +109,7 @@ add listener hicn <symbolic> <local_adress> `add connection`: creates a TCP or UDP connection on the local forwarder with the specified options. -``` +```shell add connection <protocol> <symbolic> <remote_ip> <remote_port> <local_ip> <local_port> <protocol> : tcp | udp @@ -134,9 +120,10 @@ add connection <protocol> <symbolic> <remote_ip> <remote_port> <local_ip> <local <local_port> : local TCP/UDP port ``` + `add connection hicn`: creates an hicn connection on the local forwarder with the specified options. -``` +```shell add connection hicn <symbolic> <remote_ip> <local_ip> <symbolic> : symbolic name, e.g. 'conn1' (must be unique, start with alpha) @@ -144,14 +131,17 @@ add connection hicn <symbolic> <remote_ip> <local_ip> <local_ip> : local IP address to bind to ``` + `list`: lists the connections, routes or listeners available on the local hicn-light forwarder -``` + +```shell list <connections | routes | listeners> ``` + `add route`: adds a route to the specified connection -``` +```shell add route <symbolic | connid> <prefix> <cost> <symbolic> :The symbolic name for an exgress (must be unique, start with alpha) @@ -163,7 +153,7 @@ add route <symbolic | connid> <prefix> <cost> `remove connection`: removes the specified connection. At the moment, this commands is available only for UDP connections, TCP is ignored. -``` +```shell remove connection <protocol> <symbolic | connid> <protocol> : tcp | upd. This is the protocol used to create the connection. @@ -174,7 +164,7 @@ remove connection <protocol> <symbolic | connid> `remove route`: remove the specified prefix for a local connection -``` +```shell remove route <symbolic | connid> <prefix> <connid> : the alphanumeric name of a local connection @@ -183,22 +173,24 @@ remove route <symbolic | connid> <prefix> `cache serve`: enables/disables replies from local content store (if available) -``` +```shell cache serve <on|off> ``` + `cache store`: enables/disables the storage of incoming data packets in the local content store (if available) -``` +```shell cache store <on|off> ``` + `cache clear`: removes all the cached data form the local content store (if available) -``` +```shell cache clear - ``` + `set strategy`: sets the forwarding strategy for a give prefix. There are 4 different strategies implemented in hicn-light: @@ -211,12 +203,13 @@ implemented in hicn-light: ICNP 2013. - low_latency: uses the face with the lowest latency. In case more faces have similar latency the strategy uses them in parallel -``` +```shell set strategy <prefix> <strategy> <preifx> : the prefix to which apply the forwarding strategy <strategy> : random | loadbalancer | low_latency ``` + `set wldr`: turns on/off WLDR on the specified connection. WLDR (Wireless Loss Detiection and Recovery) is a protocol that can be used to recover losses generated by unreliable wireless connections, such as WIFI. More information on WLDR are available in: @@ -225,42 +218,46 @@ set strategy <prefix> <strategy> ICN 2016. Notice that WLDR is currently available only for UDP connections. In order to work properly, WLDR needs to be activated on both side of the connection. -``` +```shell set wldr <on|off> <symbolic | connid> <symbolic> :The symbolic name for an exgress (must be unique, start with alpha) <connid>: :The egress connection id (see 'help list connections') ``` + `add punting`: Add punting rules to the forwarders. -``` +```shell add punting <symbolic> <prefix> <symbolic> : listener symbolic name <address> : prefix to add as a punting rule. (example 1234::0/64) ``` + `mapme enable`: enables/disables mapme -``` +```shell mapme enable <on|off> ``` `mapme discovery`: enables/disables mapme discovery -``` +```shell mapme discovery <on|off> ``` `mapme timescale`: set the timescale value expressed in millisencods -``` +```shell mapme timescale <milliseconds> ``` + `mapme retx`: set the retrasmission time value expressed in millisecond -``` +```shell mapme retx <milliseconds> ``` + `quit`: Exits the interactive shell ### hicn-light Configuration File Example @@ -268,7 +265,7 @@ mapme retx <milliseconds> This is an example of a simple configuration file for hicn-light. It can be loaded by running the command `hicn-light-daemon --config configFile.cfg`, assuming the file name is configFile.cfg -``` +```shell #create a local listener on port 9199. This will be used by the applications to talk with the forwarder add listener udp local0 192.168.0.1 9199 @@ -279,22 +276,3 @@ add connection udp conn0 192.168.0.20 12345 192.168.0.1 9199 #add a route toward the remote node add route conn0 c001::/64 1 ``` - -## License - -This software is distributed under the following license: - -``` -Copyright (c) 2017-2019 Cisco and/or its affiliates. -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at: - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -``` diff --git a/docs/source/index.rst b/docs/source/index.rst index 43a380b5f..9123734b4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,7 +2,8 @@ Hybrid ICN software distribution ================================= .. toctree:: - + + started lib vpp-plugin transport diff --git a/docs/source/lib.md b/docs/source/lib.md index 58f23b510..727d496bf 100644 --- a/docs/source/lib.md +++ b/docs/source/lib.md @@ -1,6 +1,5 @@ -The Hybrid ICN Core Library -============================== +# The Hybrid ICN Core Library ## Introduction @@ -16,6 +15,7 @@ userspace according to the available APIs and permissions that each system offers. The library consists in several layers: + - the core library (hicn.h) provides a standard hICN packet format, as well as an API allowing manipulation of packet headers; - an hICN helper, allowing an hICN stack to be built in userspace in a portable @@ -32,54 +32,39 @@ either a consumer, a producer, or a simple forwarder. ## Folder content -CMakeLists.txt CMkake global build file -doc Package documentation -README.md This file -src - base.h Base definitions for hICN implementation - CMakeLists.txt CMake library build file - common.{h,c} Harmonization layer across supported platforms - compat.{h,c} Compatibility layer for former API - error.{h,c} Error management files - header.h hICN header definitions - hicn.h Master include file - mapme.{h,c} MAP-Me : anchorless producer mobility mechanisms - name.{h,c} hICN naming conventions and name processing + IP helpers - ops.{h,c} Protocol-independent hICN operations - protocol/* Protocol headers + protocol-dependent implementations - protocol.h Common file for protocols +```shell +. ++-- CMakeLists.txt CMkake global build file ++-- doc Package documentation ++-- README.md This file ++-- src +| +-- base.h Base definitions for hICN implementation +| +-- CMakeLists.txt CMake library build file +| +-- common.{h,c} Harmonization layer across supported platforms +| +-- compat.{h,c} Compatibility layer for former API +| +-- error.{h,c} Error management files +| +-- header.h hICN header definitions +| +-- hicn.h Master include file +| +-- mapme.{h,c} MAP-Me : anchorless producer mobility mechanisms +| +-- name.{h,c} hICN naming conventions and name processing + IP helpers +| +-- ops.{h,c} Protocol-independent hICN operations +| +-- protocol/* Protocol headers + protocol-dependent implementations +| +-- protocol.h Common file for protocols +``` ## Using libhicn -### Platforms ### - -libhicn has been tested in: - -- Ubuntu 16.04 LTS (x86_64) -- Ubuntu 18.04 LTS (x86_64) -- Debian Stable/Testing -- Red Hat Enterprise Linux 7 -- CentOS 7 -- Android 8 -- iOS 12 -- macOS 10.12 -- Windows 10 - -Other platforms and architectures may work. - ### Dependencies Build dependencies: -- c11 ( clang / gcc ) +- C11 ( clang / gcc ) - CMake 3.4 Basic dependencies: None ## Installation -You can either use released packages, or compile libhicn from sources. - ### Release mode mkdir build @@ -95,22 +80,3 @@ cd debug cmake .. -DCMAKE_BUILD_TYPE=Debug make sudo make install - -## License - -This software is distributed under the following license: - -``` -Copyright (c) 2017-2019 Cisco and/or its affiliates. -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at: - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -``` diff --git a/docs/source/started.md b/docs/source/started.md new file mode 100644 index 000000000..099b5f4d9 --- /dev/null +++ b/docs/source/started.md @@ -0,0 +1,72 @@ +# Getting started + +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. + +The transport stack is a unique library that is used for both the scalable +and portable network stacks. + +## Platforms + +- Ubuntu 18.04 LTS (amd64, arm64) +- Debian Stable/Testing +- Red Hat Enterprise Linux 7 +- CentOS 7 +- Android 10 (amd64, arm64) +- iOS 13 +- macOS 10.15 +- Windows 10 + +Other platforms and architectures may work. +You can either use released packages, or compile hicn from sources. + +### Ubuntu 18.04/16.04 amd64/arm64 + +```shell +curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash +``` + +### CentOS 7 amd64 + +```shell +curl -s https://packagecloud.io/install/repositories/fdio/release/script.rpm.sh | sudo bash +``` + +### macOS + +```shell +brew install hicn +``` + +### Android + +Install the applications via the Google Play Store +<https://play.google.com/store/apps/developer?id=ICN+Team> + +### iOS + +Coming soon. + +### Windows 10 + +Coming soon. + +## License + +This software is distributed under the following license: + +```shell +Copyright (c) 2017-2020 Cisco and/or its affiliates. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at: + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +``` diff --git a/docs/source/transport.md b/docs/source/transport.md index e7fc267ee..7f8293a78 100644 --- a/docs/source/transport.md +++ b/docs/source/transport.md @@ -1,7 +1,6 @@ -Libtransport: data transport library for hICN -==================================================== +# The Transport Library -## Introduction ## +## Introduction This library provides transport services and socket API for applications willing to communicate using the hICN protocol stack. @@ -14,20 +13,12 @@ Overview: - 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) -## Build Dependencies ## +## Build Dependencies - libparc - libmemif (linux only, if compiling with VPP support) - libasio -### Ubuntu 16.04 and Ubuntu 18.04 ### - -```bash - $ echo "deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.master.ubuntu.$(lsb_release -sc).main/ ./" \ - | sudo tee -a /etc/apt/sources.list.d/99fd.io.list - $ sudo apt-get install libparc libasio-dev -``` - If you wish to use the library for connecting to the vpp hicn-plugin, you will need to also install vpp, the vpp libraries and the libmemif libraries: - DEB packages: @@ -39,39 +30,40 @@ You can get them either from from the vpp packages ot the source code. Check the Libmemif is in the vpp-lib and vpp-dev packages. -### Mac OSX ### +### macOS We recommend to use [HomeBrew](https://brew.sh/) for installing the libasio dependency: ```bash - $ brew install asio + brew install asio ``` Download, compile and install libparc: ```bash - $ git clone -b cframework/master https://gerrit.fd.io/r/cicn cframework && cd cframework - $ mkdir -p libparc.build && cd libparc.build - $ cmake ../libparc - $ make - $ make install + git clone -b cframework/master https://gerrit.fd.io/r/cicn cframework && cd cframework + mkdir -p libparc.build && cd libparc.build + cmake ../libparc + make + make install ``` Libparc will be installed by default under `/usr/local/lib` and `/usr/local/include`. -Since VPP does not support MAC OS, the hicn-plugin connector is not built. +Since VPP does not support macOS, the hicn-plugin connector is not built. -## Build The library ## +## Build the library From the project root folder: ```bash - $ cd libtransport - $ mkdir build && cd build - $ cmake .. - $ make + cd libtransport + mkdir build && cd build + cmake .. + make ``` -### Compile options ### + +### Compile options The build process can be customized with the following options: @@ -85,42 +77,10 @@ The build process can be customized with the following options: An option can be set using cmake -D`OPTION`=`VALUE`. -Install the library -------------------- +### Install the library For installing the library, from the cmake build folder: ```bash - $ sudo make install -``` - -## Supported platforms - -- Ubuntu 16.04 LTS (x86_64) -- Ubuntu 18.04 LTS (x86_64) -- Debian Stable/Testing -- Red Hat Enterprise Linux 7 -- CentOS 7 -- Android 8 -- iOS 12 -- macOS 10.12 -- Windows 10 - -## License ## - -This software is distributed under the following license: - -``` -Copyright (c) 2017-2019 Cisco and/or its affiliates. -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at: - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. + sudo make install ```
\ No newline at end of file diff --git a/docs/source/utils.md b/docs/source/utils.md index 0d81ea426..5b9178b56 100644 --- a/docs/source/utils.md +++ b/docs/source/utils.md @@ -6,22 +6,11 @@ hicn-ping-server, hicn-ping-client and hiperf are three utility applications for ## Using hICN Utils applications -### Platforms - -hicn-light has been tested in: - -- Ubuntu 16.04 / 18.04 (x86_64) -- Debian Testing -- Centos 7 -- MacOSX 10.12 -- Android -- iOS - ### Dependencies Build dependencies: -- c++14 ( clang++ / g++ ) +- C++14 ( clang++ / g++ ) - CMake 3.4 Basic dependencies: @@ -41,7 +30,7 @@ The utility applications are a set of binary executables consisting of a client/ The command `hicn-ping-server` runs the server side ping application. hicn-ping-server can be executed with the following options: -``` +```shell usage: hicn-ping-server [options] Options: @@ -66,7 +55,7 @@ hicn-ping-server -n c001::/64 The command `hicn-ping-client` runs the client side ping application. hicn-ping-client can be executed with the following options: -``` +```shell usage: hicn-ping-client [options] Options: @@ -93,7 +82,7 @@ hicn-ping-client -n c001::1 The command `hiperf` is a tool for performing network throughput measurements with hicn. It can be executed as server or client using the following options: -``` +```shell usage: hiperf [-S|-C] [options] [prefix|name] Options: @@ -110,9 +99,9 @@ Server specific: -k <keystore_path> = path of p12 file containing the crypto material used for signing the packets -y <hash_algorithm> = use the selected hash algorithm for calculating manifest digests -p <password> = password for p12 keystore --x = produce a content of <download_size>, then after downloading it produces a new content of - <download_size> without resetting the suffix to 0 --B <bitrate> = bitrate for RTC producer, to be used with the -R option, in kbps (example: 64kbps) +-x = produce a content of <download_size>, then after downloading it produces a new + content of <download_size> without resetting the suffix to 0 +-B <bitrate> = bitrate for RTC producer, to be used with the -R option, in kbps (example: 64kbps) Client specific: -b <beta_parameter> = RAAQM beta parameter @@ -229,7 +218,7 @@ This will run the client with a fixed window of 50 interests. For sending hICN packets directly over the network, using hicn faces, change the configuration of the two forwarders and restart them. -##### Server Configuration +#### Server ```bash server$ mkdir -p ${HICN_ROOT}/etc @@ -241,7 +230,7 @@ add listener hicn list0 ${LOCAL_IP} EOF ``` -#### Client Configuration +#### Client ```bash client$ mkdir -p ${HICN_ROOT}/etc @@ -284,42 +273,23 @@ $ export HICN_ROOT=${PWD}/../hicn-install Make sure vpp is running: ```bash -$ sudo systemctl restart vpp +sudo systemctl restart vpp ``` Run the hicn-plugin: ```bash -$ vppctl hicn control start +vppctl hicn control start ``` Run hiperf server: ```bash -$ hiperf -S b001::/64 +hiperf -S b001::/64 ``` Run hiperf client: ```bash -$ hiperf -C b001::1 -W 300 -``` - -## License - -This software is distributed under the following license: - -``` -Copyright (c) 2017-2019 Cisco and/or its affiliates. -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at: - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +hiperf -C b001::1 -W 300 ``` diff --git a/docs/source/vpp-plugin.md b/docs/source/vpp-plugin.md index ed9d122d6..772f9a730 100644 --- a/docs/source/vpp-plugin.md +++ b/docs/source/vpp-plugin.md @@ -1,21 +1,21 @@ -VPP plugin -============================== +# VPP plugin The hICN-plugin forwarder -## Introduction ## +## Introduction A high-performance Hybrid ICN forwarder as a plugin to VPP. The plugin provides the following functionalities: - - Fast packet processing - - Interest aggregation - - Content caching - - Forwarding strategies +- Fast packet processing +- Interest aggregation +- Content caching +- Forwarding strategies -## Quick Start ## -``` +## Quick Start + +```bash From the code tree root (VPP installed with DEB pkg) @@ -47,42 +47,32 @@ CMAKE variables: - VPP_HOME -- set the directory containing the include and lib directories of vpp. ``` -## Using hICN plugin ## - -### Platforms ### - -hICN-plugin has been tested in: +## Using hICN plugin -- Ubuntu 16.04 LTS (x86_64) -- Ubuntu 18.04 LTS (x86_64) -- Debian Stable/Testing -- Red Hat Enterprise Linux 7 -- CentOS 7 - - -### Dependencies ### +### Dependencies Build dependencies: -- VPP 19.08 - - DEB packages (can be found https://packagecloud.io/fdio/release/install): +- VPP 20.01 + - DEB packages (can be found <https://packagecloud.io/fdio/release/install):> - vpp - libvppinfra-dev - vpp-dev Runtime dependencies: -- VPP 19.08 - - DEB packages (can be found https://packagecloud.io/fdio/release/install): +- VPP 20.01 + - DEB packages (can be found <https://packagecloud.io/fdio/release/install):> - vpp - vpp-plugin-core - vpp-plugin-dpdk (only to use DPDK compatible nics) Hardware support (not mandatory): -- [DPDK](http://DPDK.org/) compatible nics +- [DPDK](http://DPDK.org/) compatible NICs + +## Getting started -## Getting started ## In order to start, the hICN plugin requires a running instance of VPP The steps required to successfully start hICN are: @@ -94,33 +84,36 @@ The steps required to successfully start hICN are: Detailed information for configuring VPP can be found at [https://wiki.fd.io/view/VPP](https://wiki.fd.io/view/VPP). -### Setup the host for VPP ### +### Setup the host for VPP Hugepages must be enabled in the system -``` -$ sudo sysctl -w vm.nr_hugepages=1024 +```shell +sudo sysctl -w vm.nr_hugepages=1024 ``` In order to use a DPDK interface, the `uio` and `uio_pci_generic` or `vfio_pci` modules need to be loaded in the kernel -``` -$ sudo modprobe uio -$ sudo modprobe uio_pci_generic -$ sudo modprobe vfio_pci +```shell +sudo modprobe uio +sudo modprobe uio_pci_generic +sudo modprobe vfio_pci ``` If the DPDK interface we want to assign to VPP is up, we must bring it down +```bash +sudo ifconfig <interface_name> down ``` -$ sudo ifconfig <interface_name> down -``` + or + +```bash +sudo ip link set <interface_name> down ``` -$ sudo ip link set <interface_name> down -``` -### Configure VPP ### +### Configure VPP + The file /etc/VPP/startup.conf contains a set of parameters to setup VPP at startup. The following example sets up VPP to use a DPDK interfaces: @@ -156,9 +149,10 @@ plugins { # plugin acl_plugin.so { disable } } ``` + Where `0000:08:00.0` must be replaced with the actual PCI address of the DPDK interface -### Start VPP ### +### Start VPP VPP can be started as a process or a service: @@ -171,10 +165,11 @@ $ sudo vpp -c /etc/vpp/startup.conf ``` -### Configure hICN plugin ### +### Configure hICN plugin + The hICN plugin can be configured either using the VPP command-line interface (CLI), through a configuration file or through the VPP binary api -#### hICN plugin CLI #### +#### hICN plugin CLI The CLI commands for the hICN plugin start all with the hicn keyword. To see the full list of command available type: @@ -185,9 +180,9 @@ vpp# hicn ? `hicn control param`: configures the internal parameter of the hICN plugin. This command must be run before hicn control start. -``` +```shell hicn control param { pit { size <entries> | { dfltlife | minlife | maxlife } <seconds> } | cs {size <entries> | app <portion to reserved to app>} } - <entries> :set the maximum number of entry in the PIT or CS. Default for PIT is 131072, for CS is 4096. CS size cannot be grater than PIT size. Moreover CS size must be smaller than (# of vlib buffer - 8196). + <entries> :set the maximum number of entry in the PIT or CS. Default for PIT is 131072, for CS is 4096. CS size cannot be grater than PIT size. Moreover CS size must be smaller than (# of vlib buffer - 8196). <seconds> :set the default, maximum or minimum lifetime of pit entries. Default value 2s (default), 0.2s (minumum), 20s (maximum) <portion to reserved to app> :set the portion of CS to reserve to application running locally on the forwarder. Default is 30% of the cs size. ``` @@ -198,7 +193,7 @@ hicn control param { pit { size <entries> | { dfltlife | minlife | maxlife } <se `hicn face app` : manipulates producer and consumer application faces in the forwarder. -``` +```shell hicn face app {add intfc <sw_if> {prod prefix <hicn_prefix> cs_size <size_in_packets>} {cons}} | {del <face_id>} <sw_if> :software interface existing in vpp on top of which to create an application face <hicn_prefix> :prefix to bound to the producer application face. Only content matching the prefix will be allowed through such face. @@ -209,7 +204,7 @@ hicn face app {add intfc <sw_if> {prod prefix <hicn_prefix> cs_size <size_in_pac `hicn face ip`: manipulates ip application faces in the forwarder. -``` +```shell hicn face ip {add [local <src_address>] remote <dst_address> intfc <sw_if>} | {del id <face_id>} <src_address> :the IPv4 or IPv6 local IP address to bind to (not mandatory, if not specified the local address is one of the address assigned to sw_if) <dst_address> :the IPv4 or IPv6 address of the remote system @@ -217,10 +212,9 @@ hicn face ip {add [local <src_address>] remote <dst_address> intfc <sw_if>} | {d <face_id> :id of the face to remove ``` - `hicn face show`: list the available faces in the forwarder. -``` +```shell hicn face show [<face_id>| type <ip/udp>] <face_id> :face id of which we want to display the informations <ip/udp> :shows all the ip or udp faces available @@ -228,7 +222,7 @@ hicn face show [<face_id>| type <ip/udp>] `hicn face udp`: manipulates udp application faces in the forwarder. -``` +```shell hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address> port <dst_port>} intfc <sw_if> | {del id <face_id>} <src_address> :the IPv4 or IPv6 local IP address to bind to <src_port> :the local UDP port @@ -241,7 +235,7 @@ hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address `hicn fib`: manipulates hicn fib entries. -``` +```shell hicn fib {{add | delete } prefix <prefix> face <face_id> } | set strategy <strategy_id> prefix <prefix> <prefix> :prefix to add to the FIB <face_id> :face id to add as nexto hop in the FIB entry @@ -250,7 +244,7 @@ hicn fib {{add | delete } prefix <prefix> face <face_id> } | set strategy <strat `hicn pgen client`: set an vpp forwarder as an hicn packet generator client -``` +```shell hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> lifetime <interest-lifetime> intfc <data in-interface> max_seq <max sequence number> n_flows <number of flows> <ip|hicn> :set if the underlying forwarder is configured as ip or hicn <src_addr> :source address to use in the interests, i.e., the locator for routing the data packet back @@ -264,7 +258,7 @@ hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> life `hicn pgen server`: set an vpp forwarder as an hicn packet generator client -``` +```shell hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size <payload_size> <ip|hicn> :set if the underlying forwarder is configured as ip or hicn <prefix> :prefix to use to reply to interest @@ -274,7 +268,7 @@ hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size `hicn punting`: manipulates punting rules -``` +```shell hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|udp6> src_port <src_port> dst_port <dst_port>} <prefix> :prefix to punt to the hICN plugin <sw_if> :software interface where to apply the punting @@ -284,7 +278,8 @@ hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|ud ``` `hicn show`: show forwarder information. -``` + +```shell hicn show [detail] [strategies] <detail> :shows additional details as pit,cs entries allocation/deallocation <strategies> :shows only the available strategies int he forwarder @@ -292,18 +287,18 @@ hicn show [detail] [strategies] `hicn strategy mw set`: set the weight for a face. -``` +```shell hicn strategy mw set prefix <prefix> face <face_id> weight <weight> <prefix> :prefix to which the strategy applies <face_id> :id of the face to set the weight <weight> :weight ``` -#### hICN plugin configuration file #### +#### hICN plugin configuration file A configuration can be use to setup the hicn plugin when vpp starts. The configuration file is made of a list of CLI commands. In order to set vpp to read the configuration file, the file /etc/vpp/startup.conf needs to be modified as follows: -``` +```shell unix { nodaemon log /tmp/vpp.log @@ -311,15 +306,16 @@ unix { startup-config <path to configuration file> } ``` -#### hICN plugin binary api #### + +#### hICN plugin binary API The binary api, or the vapi, can be used as well to configure the hicn plugin. For each cli command there is a corresponding message in the binary api. The list of messages is available in the file hicn.api (located in hicn/hicn-plugin/src/) -### Example: consumer and producer Ping ### +### Example: consumer and producer Ping In this example, we connect two vpp forwarders, A and B, each of them running the hicn plugin. On top of forwarder A we run the ping_client application, on top of forwarder B we run the ping_server application. Each application connects to the underlying forwarder through a memif-interface. The two forwarders are connected through a dpdk link. -#### Forwarder A #### +#### Forwarder A ```shell $ sudo vppctl @@ -331,7 +327,7 @@ vpp# hicn fib add prefix b002::1/64 face 0 vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/0 type ip ``` -#### Forwarder B #### +#### Forwarder B ```shell $ sudo vppctl @@ -344,30 +340,11 @@ vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/1 type ip Once the two forwarder are started, run the ping_server application on the host where the forwarder B is running ```shell -$ sudo ping_server -n b002::1 +sudo ping_server -n b002::1 ``` and the client on the host where forwarder B is running ```shell -$ sudo ping_client -n b002::1 -``` - -## License ## - -This software is distributed under the following license: - -``` -Copyright (c) 2017-2019 Cisco and/or its affiliates. -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at: - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +sudo ping_client -n b002::1 ``` |