summaryrefslogtreecommitdiffstats
path: root/docs/source
diff options
context:
space:
mode:
authorLuca Muscariello <lumuscar@cisco.com>2022-03-30 22:29:28 +0200
committerMauro Sardara <msardara@cisco.com>2022-03-31 19:51:47 +0200
commitc46e5df56b67bb8ea7a068d39324c640084ead2b (patch)
treeeddeb17785938e09bc42eec98ee09b8a28846de6 /docs/source
parent18fa668f25d3cc5463417ce7df6637e31578e898 (diff)
feat: boostrap hicn 22.02
The current patch provides several new features, improvements, bug fixes and also complete rewrite of entire components. - lib The hicn packet parser has been improved with a new packet format fully based on UDP. The TCP header is still temporarily supported but the UDP header will replace completely the new hicn packet format. Improvements have been made to make sure every packet parsing operation is made via this library. The current new header can be used as header between the payload and the UDP header or as trailer in the UDP surplus area to be tested when UDP options will start to be used. - hicn-light The portable packet forwarder has been completely rewritten from scratch with the twofold objective to improve performance and code size but also to drop dependencies such as libparc which is now removed by the current implementation. - hicn control the control library is the agent that is used to program the packet forwarders via their binary API. This component has benefited from significant improvements in terms of interaction model which is now event driven and more robust to failures. - VPP plugin has been updated to support VPP 22.02 - transport Major improvement have been made to the RTC protocol, to the support of IO modules and to the security sub system. Signed manifests are the default data authenticity and integrity framework. Confidentiality can be enabled by sharing the encryption key to the prod/cons layer. The library has been tested with group key based applications such as broadcast/multicast and real-time on-line meetings with trusted server keys or MLS. - testing Unit testing has been introduced using GoogleTest. One third of the code base is covered by unit testing with priority on critical features. Functional testing has also been introduce using Docker, linux bridging and Robot Framework to define test with Less Code techniques to facilitate the extension of the coverage. Co-authored-by: Mauro Sardara <msardara@cisco.com> Co-authored-by: Jordan Augé <jordan.auge+fdio@cisco.com> Co-authored-by: Michele Papalini <micpapal@cisco.com> Co-authored-by: Angelo Mantellini <manangel@cisco.com> Co-authored-by: Jacques Samain <jsamain@cisco.com> Co-authored-by: Olivier Roques <oroques+fdio@cisco.com> Co-authored-by: Enrico Loparco <eloparco@cisco.com> Co-authored-by: Giulio Grassi <gigrassi@cisco.com> Change-Id: I75d0ef70f86d921e3ef503c99271216ff583c215 Signed-off-by: Luca Muscariello <muscariello@ieee.org> Signed-off-by: Mauro Sardara <msardara@cisco.com>
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/1-architecture.md42
-rw-r--r--docs/source/apps.md1
-rw-r--r--docs/source/conf.py10
-rw-r--r--docs/source/control.md22
-rw-r--r--docs/source/hicn-light.md127
-rw-r--r--docs/source/index.rst71
-rw-r--r--docs/source/interface.md33
-rw-r--r--docs/source/packethicn.md36
-rw-r--r--docs/source/started.md143
-rw-r--r--docs/source/telemetry.md23
-rw-r--r--docs/source/transport.md315
-rw-r--r--docs/source/utils.md77
-rw-r--r--docs/source/vpp-plugin.md26
13 files changed, 615 insertions, 311 deletions
diff --git a/docs/source/1-architecture.md b/docs/source/1-architecture.md
new file mode 100644
index 000000000..8f3cfc78a
--- /dev/null
+++ b/docs/source/1-architecture.md
@@ -0,0 +1,42 @@
+# Data identifiers and locators
+
+Hybrid ICN makes use of data identifiers to name the data produced by an end
+host. Data identifiers are encoded using a routable name prefix and a non
+routable name suffix to provide the ability to index a single IP packet in an
+prefix is unambigous manner. A full data name is composed of 160 bits. A
+routable name prefix in IPv4 network is 32 bits long while in IPv6 is 128 bits
+long. A name prefix is a valid IPv4 or IPv6 address. The 32 rightmost bits are
+used by the applications to index data within the same stream.
+
+A data source that is using the hicn stack is reacheable through IP routing
+where a producer socket is listening as the producer name prefix is IP routable.
+
+Locators are IP interface identifiers and are IPv4 or IPv6 addresses. Data
+consumers are reacheable through IP routing over their locators.
+
+For requests, the name prefix is stored in the destination address field of the
+IP header while the source address field stored the locator of the consumer.
+
+
+# Producer/Consumer Architecture
+Applications make use of the hicn network architecture by using a Prod/Cons API.
+Each communication socket is connection-less as a data producer makes data
+available to data consumer by pushing data into a named buffer. Consumers are
+responsible for pulling data from data producers by sending requests indexing
+the full data name which index a single MTU sized data packet. The core
+
+# Packet forwarding
+Packet forwarding leverages IP routing as requests are forwarded using name
+prefixes and replies using locators.
+
+# Relay nodes
+A relay node is implemented by using a packet cache which is used to temporarily
+store requests and replies. The relay node acts as a virtual proxy for the data
+producers as it caches data packets which can be sent back to data consumer by
+using the full name as an index. Requests must be cached and forwarded upstream
+towards data producers which will be able reach back the relay nodes by using
+the IP locators of the relays. Cached requests store all locators as currently
+written in the source address field of the request while requests forwarded
+upstream will get the source address rewritten with the relay node locator. Data
+packets can reach the original consumers via the relay nodes by using the
+requence of cached locators.
diff --git a/docs/source/apps.md b/docs/source/apps.md
index 64c3d9a68..4131eba82 100644
--- a/docs/source/apps.md
+++ b/docs/source/apps.md
@@ -18,7 +18,6 @@ Basic dependencies:
- OpenSSL
- pthreads
- libevent
-- libparc
- libcurl
- libhicntransport
diff --git a/docs/source/conf.py b/docs/source/conf.py
index bb6715564..d00e821ab 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -19,13 +19,13 @@
# -- Project information -----------------------------------------------------
project = u'Hybrid ICN'
-copyright = u'(c) 2017-2020 Cisco and/or its affiliates.'
-author = u'Luca Muscariello'
+copyright = u'(c) 2018-2022 Cisco and/or its affiliates.'
+author = u'HICN Team Members'
# The short X.Y version
version = u''
# The full version, including alpha/beta/rc tags
-release = u'20.01'
+release = u'22.02'
# -- General configuration ---------------------------------------------------
@@ -37,7 +37,7 @@ release = u'20.01'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['recommonmark']
+extensions = ['recommonmark', 'sphinx_markdown_tables']
# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
# rather than 'path/to/file:heading'
@@ -88,7 +88,7 @@ html_theme = "sphinx_rtd_theme"
html_static_path = ['_static']
def setup(app):
- app.add_stylesheet('css/rules.css')
+ app.add_css_file('css/rules.css')
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
diff --git a/docs/source/control.md b/docs/source/control.md
index 9564a23af..f4dc4f22b 100644
--- a/docs/source/control.md
+++ b/docs/source/control.md
@@ -23,26 +23,12 @@ 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
-or CentOS 7 and ad-hoc repository is available and maintained in bintray
-at <https://dl.bintray.com/icn-team/apt-hicn-extras>.
+The dependencies libyang, sysrepo, libnetconf and netopeer2 for Ubuntu20.04
+amd64/arm64 are built from sources. See the following Dockerfile for
+reference:
-For instance in Ubuntu 18 LTS:
+<https://github.com/icn-team/vSwitch/blob/master/Dockerfile>
-Install the sysrepo YANG data store and a NETCONF server:
-
-```bash
-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
-```
-
-Install the VPP based hICN virtual switch:
-
-```bash
-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 installed under `/usr/lib/$(uname -m)-linux-gnu/modules_yang`.
diff --git a/docs/source/hicn-light.md b/docs/source/hicn-light.md
index 90e0afc91..f5012f8e9 100644
--- a/docs/source/hicn-light.md
+++ b/docs/source/hicn-light.md
@@ -11,15 +11,14 @@ to communicate.
Build dependencies:
-- C99 ( clang / gcc )
-- CMake 3.4
+- C11 ( clang / gcc )
+- CMake 3.10
Basic dependencies:
- OpenSSL
- pthreads
- libevent
-- libparc
## hicn-light executables
@@ -37,31 +36,27 @@ The command `hicn-light-daemon` runs the hicn-light forwarder. The forwarder can
with the following options:
```bash
-hicn-light-daemon [--port port] [--daemon] [--capacity objectStoreSize] [--log facility=level]
+hicn-light-daemon [--port port] [--daemon] [--capacity objectStoreSize] [--log level]
[--log-file filename] [--config file]
Options:
---port <tcp_port> = tcp port for local in-bound connections
---daemon = start as daemon process
---capacity <capacity> = maximum number of content objects to cache. To disable the cache
- objectStoreSize must be 0.
- Default vaule for objectStoreSize is 100000
---log <log_granularity> = sets a facility to a given log level. You can have multiple of these.
- facilities: all, config, core, io, message, processor
- levels: debug, info, notice, warning, error, critical, alert, off
- example: hicn-light-daemon --log io=debug --log core=off
---log-file <output_logfile> = file to write log messages to (required in daemon mode)
---config <config_path> = configuration filename
+--port <tcp_port> = tcp port for local in-bound connections
+--daemon = start as daemon process
+--capacity <objectStoreSize> = maximum number of content objects to cache. To disable the cache
+ objectStoreSize must be 0.
+ Default vaule for objectStoreSize is 100000
+--log <log_granularity> = sets the log level. Available levels: trace, debug, info, warn, error, fatal
+--log-file <output_logfile> = file to write log messages to (required in daemon mode)
+--config <config_path> = configuration filename
```
The configuration file contains configuration lines as per hicn-light-control (see below for all
the available commands). If logging level or content store capacity is set in the configuration
-file, it overrides the command_line. When a configuration file is specified, no default listeners
-are setup. Only 'add listener' lines in the configuration file matter.
+file, it overrides the command_line.
-If no configuration file is specified, hicn-light-daemon will listen on TCP and UDP ports specified
-by the --port flag (or default port). It will listen on both IPv4 and IPv6 if available. The
-default port for hicn-light is 9695. Commands are expected on port 2001.
+In addition to the listeners setup in the configuration file, hicn-light-daemon will listen
+on TCP and UDP ports specified by the --port flag (or default port).
+It will listen on both IPv4 and IPv6 if available. The default port for hicn-light is 9695.
### hicn-light-control
@@ -82,28 +77,20 @@ This is the full list of available commands in `hicn-light-control`. This comman
from the command line running `hicn-light-control` as explained before, or listing them in a
configuration file.
-Information about the commands are also available in the `hicn-light-control` help message.
+The list of commands can be navigated using `hicn-light-control help`, `hicn-light-control help <object>`, `hicn-light-control help <object> <action>`.
`add listener`: creates a TCP or UDP listener with the specified options on the local forwarder.
For local connections (application to hicn-light) we expect a TCP listener. The default port for
the local listener is 9695.
```bash
-add listener <protocol> <symbolic> <local_adress> <local_port>
+add listener <protocol> <symbolic> <local_address> <local_port> <interface>
<symbolic> :User defined name for listener, must start with alpha and bealphanum
<protocol> :tcp | udp
<localAddress> :IPv4 or IPv6 address
<local_port> :TCP/UDP port
-```
-
-`add listener hicn`: creates a hicn listener with the specified options on the local forwarder.
-
-```bash
-add listener hicn <symbolic> <local_adress>
-
- <symbolic> :User defined name for listener, must start with alpha and be alphanum
- <localAddress> :IPv4 or IPv6 address
+ <interface> :interface on which to bind
```
`add connection`: creates a TCP or UDP connection on the local forwarder with the specified options.
@@ -119,17 +106,6 @@ 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.
-
-```bash
-add connection hicn <symbolic> <remote_ip> <local_ip>
-
- <symbolic> : symbolic name, e.g. 'conn1' (must be unique, start with alpha)
- <remote_ip> : the IPv4 or IPv6 of the remote system
- <local_ip> : local IP address to bind to
-
-```
-
`list`: lists the connections, routes or listeners available on the local hicn-light forwarder.
```bash
@@ -142,7 +118,7 @@ list <connections | routes | listeners>
add route <symbolic | connid> <prefix> <cost>
<symbolic> :The symbolic name for an exgress (must be unique, start with alpha)
- <connid>: :The egress connection id (see 'help list connections')
+ <connid>: :The egress connection id (see 'list connection' command)
<prefix>: :ipAddress/netmask
<cost>: :positive integer representing cost
```
@@ -151,11 +127,10 @@ add route <symbolic | connid> <prefix> <cost>
only for UDP connections, TCP is ignored.
```bash
-remove connection <protocol> <symbolic | connid>
+remove connection <symbolic | connid>
- <protocol> : tcp | upd. This is the protocol used to create the connection.
<symbolic> :The symbolic name for an exgress (must be unique, start with alpha)
- <connid>: :The egress connection id (see 'help list connections')
+ <connid>: :The egress connection id (see 'list connection' command)
```
@@ -168,24 +143,24 @@ remove route <symbolic | connid> <prefix>
<prefix> : the prefix (ipAddress/netmask) to remove
```
-`cache serve`: enables/disables replies from local content store (if available).
+`serve cache`: enables/disables replies from local content store (if available).
```bash
-cache serve <on|off>
+serve cache <on|off>
```
-`cache store`: enables/disables the storage of incoming data packets in the local content store
+`store cache`: enables/disables the storage of incoming data packets in the local content store
(if available).
```bash
-cache store <on|off>
+store cache <on|off>
```
-`cache clear`: removes all the cached data form the local content store (if available).
+`clear cache`: removes all the cached data form the local content store (if available).
```bash
-cache clear
+clear cache
```
`set strategy`: sets the forwarding strategy for a give prefix. There are 4 different strategies
@@ -200,12 +175,14 @@ 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.
+- **replication**
+- **bastpath**
```bash
set strategy <prefix> <strategy>
<preifx> : the prefix to which apply the forwarding strategy
- <strategy> : random | loadbalancer | low_latency
+ <strategy> : random | loadbalancer | low_latency | replication | bestpath
```
`set wldr`: turns on/off WLDR on the specified connection. WLDR (Wireless Loss Detiection and
@@ -224,36 +201,13 @@ set wldr <on|off> <symbolic | connid>
```
-`add punting`: add punting rules to the forwarders.
-
-```bash
-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.
-
-```bash
-mapme enable <on|off>
-```
-`mapme discovery`: enables/disables mapme discovery.
-
-```bash
-mapme discovery <on|off>
-```
-
-`mapme timescale`: set the timescale value expressed in milliseconds.
-
-```bash
-mapme timescale <milliseconds>
-```
-
-`mapme retx`: set the retransmission time value expressed in millisecond.
+`set mapme`: enables/disables mapme, enables/disables mapme discovery, set the timescale value (expressed in milliseconds), set the retransmission time value (expressed in milliseconds).
```bash
-mapme retx <milliseconds>
+mapme set enable <on|off>
+mapme set discovery <on|off>
+mapme set timescale <milliseconds>
+mapme set retx <milliseconds>
```
`quit`: exits the interactive bash.
@@ -264,13 +218,12 @@ This is an example of a simple configuration file for hicn-light. It can be load
the command `hicn-light-daemon --config configFile.cfg`, assuming the file name is `configFile.cfg`.
```bash
-#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
+# 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 eth0
-#create a connection with a remote hicn-light-daemon, with a listener on 192.168.0.20 12345
-add connection udp conn0 192.168.0.20 12345 192.168.0.1 9199
+# Create a connection with a remote hicn-light-daemon, with a listener on 192.168.0.20 12345
+add connection udp conn0 192.168.0.20 12345 192.168.0.1 9199 eth0
-#add a route toward the remote node
+# Add a route toward the remote node
add route conn0 c001::/64 1
```
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 99ea39afa..c41df95ca 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,27 +1,76 @@
Hybrid Information-Centric Networking
=====================================
-Hybrid Information-Centric Networking (hICN) is a network architecture that makes
-use of IPv6 or IPv4 to realize location-independent communications. It is largely
-inspired by the pioneer work of Van Jacobson on Content-Centric Networking, that was
-a clean-slate architecture whereas hICN is based on the Internet protocol and easy to
-deploy in today networks and applications. hICN brings many-to-many communications,
-multi-homing, multi-path, multi-source, group communications to the Internet protocol
-without replicated unicast. The project implements novel transport protocols, with a socket API,
-for real-time and capacity seeking applications. A scalable stack is available based
-on VPP and a client stack is provided to support any mobile and desktop operating system.
+Hybrid Information-Centric Networking (hICN) is a network architecture that
+makes use of IPv6 or IPv4 to implement location-independent communications. It
+is largely inspired by the pioneer work of Van Jacobson on Content-Centric
+Networking (RFC 8569, RFC 8609) that is a clean-slate architecture. hICN is
+based on the Internet protocol and easyier to deploy in today networks and
+applications. hICN brings many-to-many communications, multi-homing, multi-path,
+multi-source, group communications to the Internet protocol. The current code
+implements also transport protocols, with a socket API, for real-time and
+capacity seeking applications. A scalable stack is available based on VPP and a
+client stack is provided to support mobile and desktop operating systems.
+
+A detailed description of the architecture is described in the paper
+
+Giovanna Carofiglio, Luca Muscariello, Jordan Augé, Michele Papalini, Mauro
+Sardara, and Alberto Compagno. 2019. Enabling ICN in the Internet Protocol:
+Analysis and Evaluation of the Hybrid-ICN Architecture. In Proceedings of the
+6th ACM SIGCOMM Conference on Information-Centric Networking (ICN '19).
+Association for Computing Machinery, New York, NY, USA, 55–66. DOI:
+https://doi.org/10.1145/3357150.3357394
+
+The project wiki page is full of resources https://wiki.fd.io/view/HICN
+
+.. toctree::
+ :caption: Architecture
+
+ 1-architecture
+
.. toctree::
+ :caption: Getting started
+ :maxdepth: 1
started
+
+.. toctree::
+ :caption: Core library
+ :maxdepth: 1
+
lib
+
+.. toctree::
+ :caption: The VPP Plugin
+ :maxdepth: 1
+
vpp-plugin
+
+.. toctree::
+ :caption: The Transport Library
+ :maxdepth: 1
+
transport
+
+.. toctree::
+ :caption: The Portable Forwarder
+ :maxdepth: 1
+
hicn-light
+
+.. toctree::
+ :caption: Network Control and Management
+ :maxdepth: 1
+
interface
control
telemetry
- utils
- apps
+.. toctree::
+ :caption: Applications and Tools
+ :maxdepth: 1
+ utils
+ apps
+ packethicn \ No newline at end of file
diff --git a/docs/source/interface.md b/docs/source/interface.md
index cf05a5c7b..909f60bfa 100644
--- a/docs/source/interface.md
+++ b/docs/source/interface.md
@@ -45,35 +45,6 @@ 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
-
-TODO
-
-#### Facelet cache & event scheduling
-
-TODO:
-
-```text
- - Facelet cache
- - Joins
- - How synchronization work
-```
-
-### Interface API
-
-TODO
-
## Developing a new interface
### Dummy template
@@ -261,7 +232,7 @@ error.
```
While support for multiple file descriptors might be added in the future, an
-alternative short-term implementation might consider the instanciation of
+alternative short-term implementation might consider the instantiation of
multiple interface, as is done for Bonjour in the current codebase, in
`src/api.c`.
@@ -304,8 +275,6 @@ 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
#### Architecture
diff --git a/docs/source/packethicn.md b/docs/source/packethicn.md
index cf4976837..acf2d7cc9 100644
--- a/docs/source/packethicn.md
+++ b/docs/source/packethicn.md
@@ -1,11 +1,13 @@
HICN Plugin for Wireshark
===================
-The `packethicn` plugin adds support to Wireshark to parse and dissect HICN traffic.
+The `packethicn` plugin adds support to Wireshark to parse and dissect HICN
+traffic.
`packethicn` can be compiled and installed in two ways:
-1. Alongside HICN, from the HICN root dir (see [Build with HICN](#Build-with-HICN))
+1. Alongside HICN, from the HICN root dir (see [Build with
+ HICN](#Build-with-HICN))
2. As a standalone component (see [Standalone build](#Standalone-build))
@@ -14,13 +16,12 @@ The second one is preferred if HICN is already installed in the system.
# Supported platforms
`packethicn` has been tested in
-- Ubuntu 18.04
- Ubuntu 20.04
-- macOS 11.2
+- macOS 12.3
Other platforms and architectures may work.
-# Installation
+# Installation
## Build with HICN
### Dependencies
@@ -38,15 +39,10 @@ From the root HICN dir add the `-DBUILD_WSPLUGIN` flag to cmake.
```bash
$ cd hicn
-
$ mkdir build; cd build
-
-$ cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl\@1.1 -DBUILD_APPS=ON -DBUILD_WSPLUGIN=ON ..
-
+$ cmake -DBUILD_APPS=ON -DBUILD_WSPLUGIN=ON ..
$ make -j`nproc`
-
$ sudo make install
-
```
## Standalone build
@@ -55,22 +51,16 @@ $ sudo make install
#### Install dependencies
```bash
$ sudo add-apt-repository ppa:wireshark-dev/stable
-
$ curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
-
$ sudo apt install -y build-essential cmake libhicn-dev wireshark wireshark-dev libgcrypt-dev libgnutls28-dev
```
-#### Compile and install HICN plugin
+#### Compile and install HICN wireshark plugin
```bash
$ cd packethicn
-
$ mkdir build; cd build
-
$ cmake ..
-
$ make
-
$ sudo make install
```
@@ -80,15 +70,10 @@ If installing wireshark via brew use the `./install_macos.sh` script as shown be
```bash
$ brew tap icn-team/hicn-tap
-
$ brew install hicn
-
$ brew install wireshark
-
$ brew install cask wireshark
-
$ cd packethicn
-
$ ./install_macos.sh
```
@@ -96,13 +81,9 @@ Otherwise (if wireshark was compiled from sources) you can follow the setup for
```bash
$ cd packethicn
-
$ mkdir build; cd build
-
$ cmake ..
-
$ make
-
$ sudo make install
```
@@ -110,6 +91,7 @@ $ sudo make install
## Filters
+
| Filter | Description | Example |
| --- | --- | --- |
| `hicn` | HICN traffic only | *hicn* |
diff --git a/docs/source/started.md b/docs/source/started.md
index ef3763366..dd2f83bab 100644
--- a/docs/source/started.md
+++ b/docs/source/started.md
@@ -1,15 +1,16 @@
-# Getting started
+# Code structure
## 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 implementation and a
-real-time transport service for audio/video media.
+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 implementation and a real-time
+transport service for audio/video media.
## Directory layout
-```text
+
| Directory name | Description |
| -------------- | --------------------------------------------------------- |
| lib | Core support library |
@@ -19,39 +20,36 @@ real-time transport service for audio/video media.
| 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).
+hicn plugin is a VPP plugin that implement hicn packet processing as specified
+in [1] 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 latest 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 right code tree by searching the latest commit under a given git tag carrying the
-release version.
+The current master branch provides the latest release which is compatible with
+the latest 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 right 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.
+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.
+The transport stack is a unique library that is used for both the scalable and
+portable network stacks.
## Supported platforms
-- Ubuntu 18.04 LTS (amd64, arm64)
-- Debian Stable/Testing
-- Red Hat Enterprise Linux 7
-- CentOS 7
+- Ubuntu 20.04 LTS (amd64, arm64)
- Android 10 (amd64, arm64)
-- iOS 13
-- macOS 10.15
+- iOS 15
+- macOS 12.3
- Windows 10
Other platforms and architectures may work.
@@ -63,35 +61,97 @@ You can either use released packages, or compile hicn from sources.
curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
```
-### CentOS
+The following debian packages for Ubuntu are available dor amd64 and arm64
```bash
-curl -s https://packagecloud.io/install/repositories/fdio/release/script.rpm.sh | sudo bash
+facemgr-dev
+facemgr
+hicn-apps-dev
+hicn-apps
+hicn-light
+hicn-plugin-dev
+hicn-plugin
+libhicn-dev
+libhicn
+libhicnctrl-dev
+libhicnctrl-modules
+libhicnctrl
+libhicntransport-dev
+libhicntransport-io-modules
+libhicntransport
```
### macOS
```bash
+brew tap icn-team/hicn-tap
brew install hicn
```
+or
+
+```bash
+git clone https://github.com/FDio/hicn.git
+$ cd hicn
+$ OPENSSL_ROOT_DIR=/usr/local/opt/openssl\@1.1 make build-release
+```
+
### Android
+hICN is built as a native library for the Android NDK which are packaged
+as Android archives AAR and made available in a Maven repository in
+Github Packages in
+
+<https://github.com/orgs/icn-team/packages>
+
+To build from sources, refer to the Android SDK in
+
+<https://github.com/icn-team/android-sdk>
Install the applications via the Google Play Store
+
<https://play.google.com/store/apps/developer?id=ICN+Team>
### iOS
-Coming soon.
+Clone this distro
+
+```bash
+git clone https://github.com/icn-team/ios-sdk.git
+cd ios-sdk
+```
+Compile everything (dependencies and hICN modules)
+
+```bash
+make update
+make all
+```
+Compile everything with Qt (dependencies, hICN modules and Viper dependencies)
+
+```bash
+make update
+make all_qt
+```
### Windows
-Coming soon.
+Install vcpkg
+
+```bash
+git clone https://github.com/icn-team/windows-sdk
+.\windows-sdk\scripts\init.bat
+```
+
+
+```bash
+cd windows-sdk
+make all
+```
### 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>.
+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>.
The following images are nightly built and maintained.
@@ -106,6 +166,8 @@ docker pull icnteam/vhttpproxy:amd64
docker pull icnteam/vhttpproxy:arm64
```
+Other Dockerfiles are included in the main git repo for development.
+
### Vagrant
Vagrant boxes for a virtual switch are available at
@@ -117,12 +179,21 @@ vagrant box add icnteam/vswitch
Supported providers are libvirt, vmware and virtualbox.
+## References
+
+Giovanna Carofiglio, Luca Muscariello, Jordan Augé, Michele Papalini, Mauro
+Sardara, and Alberto Compagno. 2019. Enabling ICN in the Internet Protocol:
+Analysis and Evaluation of the Hybrid-ICN Architecture. In Proceedings of the
+6th ACM Conference on Information-Centric Networking (ICN '19). Association for
+Computing Machinery, New York, NY, USA, 55–66.
+DOI: https://doi.org/10.1145/3357150.3357394
+
## License
This software is distributed under the following license:
```bash
-Copyright (c) 2017-2020 Cisco and/or its affiliates.
+Copyright (c) 2019-2022 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:
diff --git a/docs/source/telemetry.md b/docs/source/telemetry.md
index 8887b8f1f..f81d21ee1 100644
--- a/docs/source/telemetry.md
+++ b/docs/source/telemetry.md
@@ -31,17 +31,14 @@ sudo make install
hICN collectd plugins have 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
+- Ubuntu 20.04 LTS
### Dependencies
Build dependencies:
-- VPP 20.01, Debian packages can be found on [packagecloud](https://packagecloud.io/fdio/release/install):
+VPP 22.02, Debian packages can be found on
+[packagecloud](https://packagecloud.io/fdio/release/install):
- vpp
- libvppinfra-dev
- vpp-dev
@@ -62,14 +59,18 @@ Before running collectd, a vpp forwarder must be started. If the vpp-hicn plugin
is used, the hicn-plugin must be available in the vpp forwarder.
If you need the custom types that the two plugins define, they are present in
-`telemetry/custom_types.db`. It is useful if you are using InfluxDB as it requires
-the type database for multi-value metrics
-(see [CollectD protocol support in InfluxDB](https://docs.influxdata.com/influxdb/v1.7/supported_protocols/collectd/)).
+`telemetry/custom_types.db`. It is useful if you are using InfluxDB as it
+requires the type database for multi-value metrics (see [CollectD protocol
+support in
+InfluxDB](https://docs.influxdata.com/influxdb/v1.7/supported_protocols/collectd/)).
## Plugin options
`vpp` and `vpp-hicn` have the same two options:
-- `Verbose` enables additional statistics. You can check the sources to have an exact list of available metrics.
-- `Tag` tags the data with the given string. Useful for identifying the context in which the data was retrieved in InfluxDB for instance. If the tag value is `None`, no tag is applied.
+- `Verbose` enables additional statistics. You can check the sources to have an
+ exact list of available metrics.
+- `Tag` tags the data with the given string. Useful for identifying the context
+ in which the data was retrieved in InfluxDB for instance. If the tag value is
+ `None`, no tag is applied.
### Example: storing statistics from vpp and vpp-hicn
diff --git a/docs/source/transport.md b/docs/source/transport.md
index 3e7844ad5..eb5b9d71a 100644
--- a/docs/source/transport.md
+++ b/docs/source/transport.md
@@ -1,38 +1,51 @@
-# Transport library
-
## Introduction
-This library provides transport services and socket API for applications willing to communicate
-using the hICN protocol stack.
+The transport library provides transport services and socket API for
+applications willing to communicate using the hICN protocol stack.
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.
+ the API provided by [libhicn](./lib.md).
+- IO modules for seamlessly connecting the application to the hicn-plugin for [VPP](https://github.com/FDio/vpp) or the
+ [hicn-light](./hicn-light.md) forwarder.
- Transport protocols (RAAQM, CBR, RTC)
-- Transport services (authentication, integrity, segmentation, reassembly, naming)
+- 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
### Ubuntu
-- libparc
-- libmemif (linux only, if compiling with VPP support)
-- libasio
+```bash
+sudo apt install libasio-dev libconfig++-dev libssl-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:
+need to also install vpp and its libraries.
-- DEB packages:
- - vpp
- - vpp-lib
- - vpp-dev
+```bash
+# Prevent vpp to set sysctl
+export VPP_INSTALL_SKIP_SYSCTL=1
+VPP_VERSION=$(cat "${VERSION_PATH}" | grep VPP_DEFAULT_VERSION | cut -d ' ' -f 2 | tr -d '"' | grep -Po '\d\d.\d\d')
-You can get them either from from the vpp packages or the source code. Check
-the [VPP wiki](https://wiki.fd.io/view/VPP) for instructions.
+curl -s https://packagecloud.io/install/repositories/fdio/${VPP_VERSION//./}/script.deb.sh | bash
+curl -L https://packagecloud.io/fdio/${VPP_VERSION//./}/gpgkey | apt-key add -
+sed -E -i 's/(deb.*)(\[.*\])(.*)/\1\3/g' /etc/apt/sources.list.d/fdio_${VPP_VERSION//./}.list
+apt-get update
+
+apt-get install -y \
+ vpp-dev \
+ libvppinfra-dev \
+ vpp-plugin-core \
+ vpp \
+ libvppinfra
+```
+
+You can get them either from from the vpp packages or the source code. Check the
+[VPP wiki](https://wiki.fd.io/view/VPP) for instructions.
### macOS
@@ -40,31 +53,23 @@ We recommend to use [HomeBrew](https://brew.sh/) for installing the libasio
dependency:
```bash
-brew install asio
+brew install asio libconfig openssl@1.1
```
-Download, compile and install libparc:
+Since VPP does not support macOS, the IO module memif is not built.
-```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
-```
-
-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
-From the project root folder:
+The library is built by default from the main CMakeLists.txt.
+If you have all the dependencies installed, including [libhicn](./lib.md),
+you can also build libtransport alone:
```bash
cd libtransport
mkdir build && cd build
cmake ..
-make
+cmake --build .
```
### Compile options
@@ -75,11 +80,7 @@ The build process can be customized with the following options:
- `CMAKE_BUILD_TYPE`: The build configuration. Options: `Release`, `Debug`.
Default is `Release`.
- `ASIO_HOME`: The folder containing the libasio headers.
-- `LIBPARC_HOME`: The folder containing the libparc headers and libraries.
- `VPP_HOME`: The folder containing the installation of VPP.
-- `LIBMEMIF_HOME`: The folder containing the libmemif headers and libraries.
-- `BUILD_MEMIF_CONNECTOR`: On linux, set this value to `ON` for building the
- VPP connector.
An option can be set using cmake -D`OPTION`=`VALUE`.
@@ -88,5 +89,245 @@ An option can be set using cmake -D`OPTION`=`VALUE`.
For installing the library, from the cmake build folder:
```bash
-sudo make install
+cmake --build . -- install
+```
+
+
+## Usage
+
+Examples on how to use the library can be found in the apps folder of the project.
+In particular you can check the **hiperf** application, which demonstrates
+how to use the API to interact with the hicn transport, both for consumer and producer.
+
+### Configuration file
+
+The transport can be configured using a configuration file. There are two ways
+to tell libransport where to find the configuration file:
+
+- programmatically - you set the configuration file path in your application:
+```cpp
+// Set conf file path
+std::string conf_file = "/opt/hicn/etc/transport.config"
+// Parse config file
+transport::interface::global_config::parseConfigurationFile(conf_file);
+```
+
+- using the environment variable `TRANSPORT_CONFIG`:
+```bash
+export TRANSPORT_CONFIG=/opt/hicn/etc/transport.config
+./hiperf -C b001::1
```
+
+Here is an example of configuration file:
+
+```
+// Configuration for io_module
+io_module = {
+ path = [];
+ name = "forwarder_module";
+};
+
+// Configuration for forwarder io_module
+forwarder = {
+ n_threads = 1;
+
+ connectors = {
+ c0 = {
+ /* local_address and local_port are optional */
+ local_address = "127.0.0.1";
+ local_port = 33436;
+ remote_address = "127.0.0.1";
+ remote_port = 33436;
+ }
+ };
+
+ listeners = {
+ l0 = {
+ local_address = "127.0.0.1";
+ local_port = 33437;
+ }
+ };
+};
+
+// Logging
+log = {
+ // Log level (INFO (0), WARNING (1), ERROR (2), FATAL (3))
+ minloglevel = 0;
+
+ // Verbosity level for debug logs
+ v= 2;
+
+ // Log to stderr
+ logtostderr = true;
+
+ // Get fancy colored logs
+ colorlogtostderr = true;
+
+ // Log messages above this level also to stderr
+ stderrthreshold = 2;
+
+ // Set log prefix for each line log
+ log_prefix = true;
+
+ // Log dir
+ log_dir = "/tmp";
+
+ // Log only specific modules.
+ // Example: "membuf=2,rtc=3"
+ vmodule = "";
+
+ // Max log size in MB
+ max_log_size = 10;
+
+ // Log rotation
+ stop_logging_if_full_disk = true;
+};
+```
+
+
+## Security
+
+hICN has built-in authentication and integrity features by either:
+* Cryptographically signing all packets using an asymmetric key (like RSA) or a
+ symmetric one (like HMAC). The latter requires that all parties have prior
+ access to the same key. Beware that this method is computationally expensive
+ and impacts max throughput and CPU usage.
+* Using manifests. Manifests are special packets that holds the digests of a
+ group of data packets. Only the manifest needs to be signed and authenticated;
+ other packets are authenticated simply by verifying that their digest is
+ present in a manifest.
+
+### Per-packet signatures
+
+To enable per-packet signature with asymmetric signing:
+* On the producer, disable manifests (which are ON by default):
+ ```cpp
+ producer_socket->setSocketOption(GeneralTransportOptions::MAKE_MANIFEST, 0);
+ ```
+* On the producer, instantiate an `AsymmetricSigner` object by passing either an
+ asymmetric pair of keys as
+ [EVP_KEY](https://www.openssl.org/docs/man3.0/man3/EVP_PKEY_new.html) object
+ or a keystore path and password as strings:
+ ```cpp
+ std::shared_ptr<Signer> signer = std::make_shared<AsymmetricSigner>("./rsa.p12", "hunter2");
+ ```
+* Pass the signer object to libtransport:
+ ```cpp
+ producer_socket->setSocketOption(GeneralTransportOptions::SIGNER, signer);
+ ```
+* On the consumer, instantiate an `AsymmetricVerifer` object by passing either a
+ certificate as a [X509](https://www.openssl.org/docs/man1.0.2/man3/x509.html)
+ object, an asymmetric public key as a
+ [EVP_KEY](https://www.openssl.org/docs/man3.0/man3/EVP_PKEY_new.html) object
+ or a certificate path as a string:
+ ```cpp
+ std::shared_ptr<Verifier> verifier = std::make_shared<Verifier>("./rsa.crt");
+ ```
+* Pass the verifier object to libtransport:
+ ```cpp
+ consumer_socket->setSocketOption(GeneralTransportOptions::VERIFIER, verifier);
+ ```
+
+To enable per-packet signature with symmetric signing, follow the above steps
+replacing `AsymmetricSigner` with `SymmetricSigner` and `AsymmetricVerifer` with
+`SymmetricSigner`. A `SymmetricSigner` only has one constructor which expects a
+`CryptoSuite` and a passphrase. A `SymmetricVerifier` also has a single
+constructor which expects a passphrase:
+```cpp
+std::shared_ptr<Signer> signer = std::make_shared<SymmetricSigner>(CryptoSuite::HMAC_SHA256, "hunter2");
+std::shared_ptr<Verifier> verifier = std::make_shared<SymmetricVerifier>("hunter2");
+```
+
+Check [Supported crypto suites](#supported-crypto-suites) for the list of
+available suites.
+
+### Enabling manifests
+
+* Follow steps 2-5 in [Per-packet signatures](#per-packet-signatures).
+* By default, a manifest holds the digest of 30 packets. To change this value:
+ ```cpp
+ producer_socket->setSocketOption(GeneralTransportOptions::MAKE_MANIFEST, 20);
+ ```
+
+In the case of RTC, manifests are sent after the data they contain and on the
+consumer side, data packets are immediately forwarded to the application, *even
+if they weren't authenticated yet via a manifest*. This is to minimize latency.
+The digest of incoming data packets are kept in a buffer while waiting for
+manifests to arrive. When that buffer goes above a threshold `T`, an alert is
+raised by the verifier object. That threshold is computed as follows:
+```
+T(t) = producer_rate(t) * max_unverified_time
+```
+
+`max_unverified_time` is a consumer socket option, in milliseconds. It is set
+to `2000` by default. To change it:
+```cpp
+consumer_socket_->setSocketOption(GeneralTransportOptions::MAX_UNVERIFIED_TIME, 4000);
+```
+
+### Handling authentication failures
+
+When a data packet fails authentication, or when the unverified buffer is full
+in the case of RTC, an alert is triggered by the verifier object. By default
+libtransport aborts the connection upon reception of that alert. You may want to
+intercept authentication failures in your application:
+* Define a callback with arguments an `uint32_t` integer, which will be set to
+ the suffix of the faulty packet, and a `auth::VerificationPolicy`, which will
+ be set to the action suggested by the verifier object. The callback must
+ return another `auth::VerificationPolicy` which will be the actual action
+ taken by libtransport:
+ ```cpp
+ auth::VerificationPolicy onAuthFailed(uint32_t suffix, auth::VerificationPolicy policy) {
+ std::cout << "auth failed for packet " << suffix << std::endl;
+ return auth::VerificationPolicy::ACCEPT;
+ }
+ ```
+* Give that callback to your `Verifier` object as well as a list of
+ `auth::VerificationPolicy` to intercept (if left empty, will be set by
+ default to `{ABORT, DROP}`):
+ ```cpp
+ verifier->setVerificationFailedCallback(&onAuthFailed, {
+ auth::VerificationPolicy::ABORT,
+ auth::VerificationPolicy::DROP,
+ auth::VerificationPolicy::UNKNOWN,
+ });
+ ```
+
+### Supported crypto suites
+
+The following `CryptoSuite` are supported by libtransport:
+```
+ECDSA_BLAKE2B512
+ECDSA_BLAKE2S256
+ECDSA_SHA256
+ECDSA_SHA512
+RSA_BLAKE2B512
+RSA_BLAKE2S256
+RSA_SHA256
+RSA_SHA512
+HMAC_BLAKE2B512
+HMAC_BLAKE2S256
+HMAC_SHA256
+HMAC_SHA512
+DSA_BLAKE2B512
+DSA_BLAKE2S256
+DSA_SHA256
+DSA_SHA512
+```
+
+
+## Logging
+
+Internally libtransport uses glog as logging library. If you want to have a more
+verbose transport log when launching a test or an app, you can set environment
+variables in this way:
+
+```
+GLOG_v=4 hiperf -S b001::/64
+```
+
+For a more exhaustive list of options, please check the instructions in the glog
+[README](https://github.com/google/glog#setting-flags).
+
+Useful options include enabling logging *per module*. Also you can compile out
+useless messages in release builds.
diff --git a/docs/source/utils.md b/docs/source/utils.md
index 79ada8985..d6044821a 100644
--- a/docs/source/utils.md
+++ b/docs/source/utils.md
@@ -19,7 +19,6 @@ Basic dependencies:
- OpenSSL
- pthreads
- libevent
-- libparc
- libhicntransport
## Executables
@@ -92,45 +91,59 @@ 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:
```bash
+HIPERF - Instrumentation tool for performing active networkmeasurements with hICN
usage: hiperf [-S|-C] [options] [prefix|name]
SERVER OR CLIENT:
--D = Run as a daemon
--R = Run RTC protocol (client or server)
--f <filename> = Log file
+-D Run as a daemon
+-R Run RTC protocol (client or server)
+-f <filename> Log file
+-z <io_module> IO module to use. Default: hicnlightng_module
+-F <conf_file> Path to optional configuration file for libtransport
+-a Enables data packet aggregation. Works only in RTC mode
+-X <param> Set FEC params. Options are Rely_K#_N# or RS_K#_N#
SERVER SPECIFIC:
--A <content_size> = Size of the content to publish. This is not the size of the packet (see -s for it).
--s <packet_size> = Size of the payload of each data packet.
--r = Produce real content of <content_size> bytes
--m = Produce transport manifest
--l = Start producing content upon the reception of the first interest
--K <keystore_path> = Path of p12 file containing the crypto material used for signing packets
--k <passphrase> = String from which a 128-bit symmetric key will be derived for signing packets
--y <hash_algorithm> = Use the selected hash algorithm for calculating manifest digests
--p <password> = Password for p12 keystore
--x = Produce a content of <content_size>, then after downloading it produce a new content of <content_size> without resetting the suffix to 0.
--B <bitrate> = Bitrate for RTC producer, to be used with the -R option.
--I = Interactive mode, start/stop real time content production by pressing return. To be used with the -R option
--E = Enable encrypted communication. Requires the path to a p12 file containing the crypto material used for the TLS handshake
+-A <content_size> Sends an application data unit in bytes that is published once before exit
+-s <packet_size> Data packet payload size.
+-r Produce real content of <content_size> bytes
+-m <manifest_capacity> Produce transport manifest
+-l Start producing content upon the reception of the first interest
+-K <keystore_path> Path of p12 file containing the crypto material used for signing packets
+-k <passphrase> String from which a 128-bit symmetric key will be derived for signing packets
+-p <password> Password for p12 keystore
+-y <hash_algorithm> Use the selected hash algorithm for computing manifest digests (default: SHA256)
+-x Produces application data units of size <content_size> without resetting the name suffix to 0.
+-B <bitrate> RTC producer data bitrate, to be used with the -R option.
+-I Interactive mode, start/stop real time content production by pressing return. To be used with the -R option
+-T <filename> Trace based mode, hiperf takes as input a file with a trace. Each line of the file indicates the timestamp and the size of the packet to generate. To be used with the -R option. -B and -I will be ignored.
+-E Enable encrypted communication. Requires the path to a p12 file containing the crypto material used for the TLS handshake
+-G <port> Input stream from localhost at the specified port
CLIENT SPECIFIC:
--b <beta_parameter> = RAAQM beta parameter
--d <drop_factor_parameter> = RAAQM drop factor parameter
--L <interest lifetime> = Set interest lifetime.
--M <Download for real> = Store the content downloaded.
--W <window_size> = Use a fixed congestion window for retrieving the data.
--i <stats_interval> = Show the statistics every <stats_interval> milliseconds.
--v = Enable verification of received data
--c <certificate_path> = Path of the producer certificate to be used for verifying the origin of the packets received. Must be used with -v.
--k <passphrase> = String from which is derived the symmetric key used by the producer to sign packets and by the consumer to verify them. Must be used with -v.
--t = Test mode, check if the client is receiving the correct data. This is an RTC specific option, to be used with the -R (default false)
--P = Prefix of the producer where to do the handshake
+-b <beta_parameter> RAAQM beta parameter
+-d <drop_factor_parameter> RAAQM drop factor parameter
+-L <interest lifetime> Set interest lifetime.
+-u <delay> Set max lifetime of unverified packets.
+-M <input_buffer_size> Size of consumer input buffer. If 0, reassembly of packets will be disabled.
+-W <window_size> Use a fixed congestion window for retrieving the data.
+-i <stats_interval> Show the statistics every <stats_interval> milliseconds.
+-c <certificate_path> Path of the producer certificate to be used for verifying the origin of the packets received.
+-k <passphrase> String from which is derived the symmetric key used by the producer to sign packets and by the consumer to verify them.
+-t Test mode, check if the client is receiving the correct data. This is an RTC specific option, to be used with the -R (default: false)
+-P Prefix of the producer where to do the handshake
+-j <relay_name> Publish received content under the name relay_name.This is an RTC specific option, to be used with the -R (default: false)
+-g <port> Output stream to localhost at the specified port
+-e <strategy> Enance the network with a realiability strategy. Options 1: unreliable, 2: rtx only, 3: fec only, 4: delay based, 5: low rate, 6: low rate and best path 7: low rate and replication, 8: low rate and best path/replication(default: 2 = rtx only)
+-H Disable periodic print headers in stats report.
+-n <nb_iterations> Print the stats report <nb_iterations> times and exit.
+ This option limits the duration of the run to <nb_iterations> * <stats_interval> milliseconds.
```
Example:
```
-hiperf -S c001::/64
+hiperf -S b001::/64
+hiperf -C b001::
```
## Client/Server benchmarking using `hiperf`
@@ -161,8 +174,7 @@ apt-get install -y git \
build-essential \
libasio-dev \
libcurl4-openssl-dev \
- --no-install-recommends \
- libparc-dev
+ --no-install-recommends
mkdir hicn-suite && cd hicn-suite
git clone https://github.com/FDio/hicn.git hicn-src
mkdir hicn-build && cd hicn-build
@@ -289,8 +301,7 @@ apt-get install -y git \
vpp vpp-dev vpp-plugin-core libvppinfra \
libmemif libmemif-dev \
python3-ply \
- --no-install-recommends \
- libparc-dev
+ --no-install-recommends
mkdir hicn-suite && cd hicn-suite
git clone https://github.com/FDio/hicn.git hicn-src
mkdir hicn-build && cd hicn-build
diff --git a/docs/source/vpp-plugin.md b/docs/source/vpp-plugin.md
index 7f49cd8b9..b6b469494 100644
--- a/docs/source/vpp-plugin.md
+++ b/docs/source/vpp-plugin.md
@@ -22,7 +22,7 @@ mkdir -p build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr
make
-sudo make install
+sudo cmake --build . -- install
```
VPP source code - build type `RELEASE`:
@@ -32,7 +32,7 @@ mkdir -p build
cd build
cmake .. -DVPP_HOME=<vpp dir>/build-root/install-vpp-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp-native/vpp
make
-sudo make install
+cmake --build . -- install
```
VPP source code - build type `DEBUG`:
@@ -42,7 +42,7 @@ mkdir -p build
cd build
cmake .. -DCMAKE_BUILD_TYPE=DEBUG -DVPP_HOME=<vpp dir>/build-root/install-vpp_debug-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp_debug-native/vpp
make
-sudo make install
+cmake --build . -- install
```
CMAKE variables:
@@ -57,7 +57,7 @@ CMAKE variables:
Build dependencies:
-- VPP 20.01
+- VPP 22.02
- DEB packages (can be found <https://packagecloud.io/fdio/release/install):>
- vpp
- libvppinfra-dev
@@ -65,11 +65,11 @@ Build dependencies:
Runtime dependencies:
-- VPP 20.01
+- VPP 22.02
- DEB packages (can be found <https://packagecloud.io/fdio/release/install):>
- vpp
- vpp-plugin-core
- - vpp-plugin-dpdk (only to use DPDK compatible nics)
+ - vpp-plugin-dpdk (optional - only to use DPDK compatible nics)
Hardware support (not mandatory):
@@ -91,7 +91,7 @@ Detailed information for configuring VPP can be found at
### Setup the host for VPP
-Hugepages must be enabled in the system.
+It is preferable to have hugepages enabled in the system, although it is not a requirement:
```bash
sudo sysctl -w vm.nr_hugepages=1024
@@ -163,7 +163,7 @@ interface.
VPP can be started as a process or a service:
-Start VPP as a service in Ubuntu 16.04+:
+Start VPP as a service in Ubuntu 20.04+:
```bash
sudo systemctl start vpp
```
@@ -299,22 +299,22 @@ vpp# set interface ip address TenGigabitEtherneta/0/1 2001::3/64
vpp# set interface state TenGigabitEtherneta/0/1 up
```
-Once the two forwarder are started, run the `ping_server` application on the
+Once the two forwarder are started, run the `hicn-ping-server` application on the
host where the forwarder B is running:
```bash
-sudo ping_server -n b002::1
+sudo hicn-ping-server -n b002::1/128 -z memif_module
```
-Then `ping_client` on the host where forwarder B is running:
+Then `hicn-ping-client` on the host where forwarder B is running:
```bash
-sudo ping_client -n b002::1
+sudo hicn-ping-client -n b002::1 -z memif_module
```
### Example: packet generator
-The packet generator can be used to test the performace of the hICN plugin, as
+The packet generator can be used to test the performance of the hICN plugin, as
well as a tool to inject packet in a forwarder or network for other test use
cases It is made of two entities, a client that inject interest into a vpp
forwarder and a server that replies to any interest with the corresponding