aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/etc/requirements.txt32
-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
14 files changed, 620 insertions, 338 deletions
diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt
index 5b037c693..3ce3a7e00 100644
--- a/docs/etc/requirements.txt
+++ b/docs/etc/requirements.txt
@@ -1,27 +1,5 @@
-alabaster==0.7.12
-Babel==2.8.0
-certifi==2019.11.28
-chardet==3.0.4
-commonmark==0.9.1
-docutils==0.16
-idna==2.8
-imagesize==1.2.0
-Jinja2==2.10.3
-MarkupSafe==1.1.1
-packaging==20.0
-Pygments==2.5.2
-pyparsing==2.4.6
-pytz==2019.3
-recommonmark==0.6.0
-requests==2.22.0
-six==1.14.0
-snowballstemmer==2.0.0
-Sphinx==2.3.1
-sphinx-rtd-theme==0.4.3
-sphinxcontrib-applehelp==1.0.1
-sphinxcontrib-devhelp==1.0.1
-sphinxcontrib-htmlhelp==1.0.2
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.2
-sphinxcontrib-serializinghtml==1.1.3
-urllib3==1.25.8
+pip-tools==6.5.0 # BSD
+sphinx # BSD
+sphinx-rtd-theme # MIT
+sphinx-markdown-tables # GPLv3
+recommonmark # MIT \ No newline at end of file
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