summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/source/apps.md87
-rw-r--r--docs/source/control.md160
-rw-r--r--docs/source/hicn-light.md107
-rw-r--r--docs/source/interface.md24
-rw-r--r--docs/source/lib.md13
-rw-r--r--docs/source/started.md26
-rw-r--r--docs/source/telemetry.md52
-rw-r--r--docs/source/transport.md51
-rw-r--r--docs/source/utils.md211
-rw-r--r--docs/source/vpp-plugin.md201
10 files changed, 508 insertions, 424 deletions
diff --git a/docs/source/apps.md b/docs/source/apps.md
index 0a1d6eb20..64c3d9a68 100644
--- a/docs/source/apps.md
+++ b/docs/source/apps.md
@@ -1,10 +1,10 @@
# Applications
-The open source distribution provides a few application examples:
-one MPEG-DASH video player, and an HTTP reverse proxy a command line
-HTTP GET client.
-hICN sockets have been successfully used to serve HTTP, RTP and
-RSockets application protocols.
+The open source distribution provides a few application examples: a MPEG-DASH
+video player, a HTTP reverse proxy, a command line HTTP GET client.
+
+hICN sockets have been successfully used to serve HTTP, RTP and RSockets
+application protocols.
## Dependencies
@@ -26,12 +26,13 @@ Basic dependencies:
### hicn-http-proxy
-`hicn-http-proxy` is a reverse proxy which can be used for augmenting the performance of a legacy HTTP/TCP server
-by making use of hICN. It performs the following operations:
+`hicn-http-proxy` is a reverse proxy which can be used for augmenting the
+performance of a legacy HTTP/TCP server by making use of hICN. It performs
+the following operations:
-- Receives a HTTP request from a hICN client
-- Forwards it to a HTTP server over TCP
-- Receives the response from the server and send it back to the client
+- Receive a HTTP request from a hICN client
+- Forward it to a HTTP server over TCP
+- Receive the response from the server and send it back to the client
```bash
hicn-http-proxy [HTTP_PREFIX] [OPTIONS]
@@ -44,17 +45,21 @@ Options:
-c <cache_size> = cache size of the proxy, in number of hicn data packets
-m <mtu> = mtu of hicn packets
-P <prefix> = optional most significant 16 bits of hicn prefix, in hexadecimal format
+```
Example:
+```bash
./hicn-http-proxy http://webserver -a 127.0.0.1 -p 8080 -c 10000 -m 1200 -P b001
```
-The hICN names used by the hicn-http-proxy for naming the HTTP responses are composed in the following way,
-starting from the most significant byte:
+The hICN names used by the hicn-http-proxy for naming the HTTP responses are
+composed in the following way, starting from the most significant byte:
- The first 2 bytes are the prefix specified in the -P option
-- The next 6 bytes are the hash (Fowler–Noll–Vo non-crypto hash) of the locator (in the example `webserver`, without the `http://` part)
-- The last 8 bytes are the hash (Fowler–Noll–Vo non-crypto hash) of the http request corresponding to the response being forwarded back to the client.
+- The next 6 bytes are the hash (Fowler–Noll–Vo non-crypto hash) of the locator
+ (in the example `webserver`, without the `http://` part)
+- The last 8 bytes are the hash (Fowler–Noll–Vo non-crypto hash) of the http
+ request corresponding to the response being forwarded back to the client.
### higet
@@ -71,23 +76,30 @@ Example:
./higet -P b001 -O - http://webserver/index.html
```
-The hICN names used by higet for naming the HTTP requests are composed the same way as described in [hicn-http-proxy](#hicn-http-proxy).
+The hICN names used by higet for naming the HTTP requests are composed the
+way described in [hicn-http-proxy](#hicn-http-proxy).
-## HTTP Client-Server with hicn-http-proxy
+## HTTP client-server with hicn-http-proxy
-We consider the following topology, consisting on two linux VM which are able to communicate through an IP network (you can also use containers or physical machines):
+We consider the following topology, consisting on two linux VMs which are able
+to communicate through an IP network (you can also use containers or physical
+machines):
```text
|client (10.0.0.1/24; 9001::1/64)|======|server (10.0.0.2/24; 9001::2/64)|
```
-Install the hICN suite on two linux VM. This tutorial makes use of Ubuntu 18.04, but it could easily be adapted to other platforms.
-You can either install the hICN stack using binaries or compile the code. In this tutorial we will make use of docker container and binaries packages.
+Install the hICN suite on two linux VM. This tutorial makes use of Ubuntu 18.04,
+but it could easily be adapted to other platforms. You can either install the hICN
+stack using binaries or compile the code. In this tutorial we will make use of
+docker container and binaries packages.
-The client will use of the hicn-light forwarder, which is lightweight and tailored for devices such as android and laptops.
-The server will use the hicn-plugin of vpp, which guarantees better performances and it is the best choice for server applications.
+The client will use of the hicn-light forwarder, which is lightweight and tailored
+for devices such as android and laptops. The server will use the hicn-plugin of vpp,
+which guarantees better performances and it is the best choice for server applications.
-Keep in mind that on the same system the stack based on vpp forwarder cannot coexist with the stack based on hicn light.
+Keep in mind that on the same system the stack based on vpp forwarder cannot
+coexist with the stack based on hicn light.
For running the hicn-plugin at the server there are two main alternatives:
@@ -102,13 +114,13 @@ Install docker in the server VM:
server$ curl get.docker.com | bash
```
-Run the hicn-http-proxy container. Here we use a public server at "localhost" as origin and
-HTTP traffic is server with an IPv6 name prefix b001.
+Run the hicn-http-proxy container. Here we use a public server at `localhost` as
+origin and HTTP traffic is server with an IPv6 name prefix `b001`.
```bash
#!/bin/bash
-#Http proxy options
+# http proxy options
ORIGIN_ADDRESS=${ORIGIN_ADDRESS:-"localhost"}
ORIGIN_PORT=${ORIGIN_PORT:-"80"}
CACHE_SIZE=${CACHE_SIZE:-"10000"}
@@ -118,7 +130,7 @@ FIRST_IPV6_WORD=${FIRST_IPV6_WORD:-"b001"}
USE_MANIFEST=${USE_MANIFEST:-"true"}
HICN_PREFIX=${HICN_PREFIX:-"http://webserver"}
-# UDP Punting
+# udp punting
HICN_LISTENER_PORT=${HICN_LISTENER_PORT:-33567}
TAP_ADDRESS_VPP=192.168.0.2
TAP_ADDRESS_KER=192.168.0.1
@@ -131,10 +143,10 @@ vppctl set int state ${TAP_NAME} up
vppctl set interface ip address tap0 ${TAP_ADDRESS_VPP}/24
ip addr add ${TAP_ADDRESS_KER}/24 brd + dev ${TAP_NAME}
-# Redirect the udp traffic on port 33567 (The one used for hicn) to VPP
+# Redirect the udp traffic on port 33567 (The one used for hicn) to vpp
iptables -t nat -A PREROUTING -p udp --dport ${HICN_LISTENER_PORT} -j DNAT \
--to-destination ${TAP_ADDRESS_VPP}:${HICN_LISTENER_PORT}
-# Masquerade all the traffic coming from VPP
+# Masquerade all the traffic coming from vpp
iptables -t nat -A POSTROUTING -j MASQUERADE --src ${TAP_ADDRESS_NET} ! \
--dst ${TAP_ADDRESS_NET} -o eth0
# Add default route to vpp
@@ -161,14 +173,14 @@ Docker images of the example above are available at
<https://hub.docker.com/r/icnteam/vhttpproxy>.
Images can be pulled using the following tags.
-```shell
+```bash
docker pull icnteam/vhttpproxy:amd64
docker pull icnteam/vhttpproxy:arm64
```
#### Client side
-Run the hicn-light forwarder
+Run the hicn-light forwarder:
```bash
client$ sudo /usr/bin/hicn-light-daemon --daemon --capacity 1000 --log-file \
@@ -183,20 +195,26 @@ client$ /usr/bin/higet -O - http://webserver/index.html -P c001
### Host/VM
-You can install the hicn-plugin of vpp on your VM and directly use DPDK compatible nics, forwarding hicn packets directly over the network. DPDK compatible nics can be used inside a container as well.
+You can install the hicn-plugin of vpp on your VM and directly use DPDK
+compatible nics, forwarding hicn packets directly over the network. DPDK
+compatible nics can be used inside a container as well.
```bash
server$ sudo apt-get install -y hicn-plugin vpp-plugin-dpdk hicn-apps-memif
```
-It will install all the required deps (vpp, hicn apps and libraries compiled for communicating with vpp using shared memories). Configure VPP following the steps described [here](https://github.com/FDio/hicn/blob/master/hicn-plugin/README.md#configure-vpp).
+It will install all the required deps (vpp, hicn apps and libraries compiled for
+communicating with vpp using shared memories). Configure VPP following the steps
+described [here](https://github.com/FDio/hicn/blob/master/hicn-plugin/README.md#configure-vpp).
This tutorial assumes you configured two interfaces in your server VM:
- One interface which uses the DPDK driver, to be used by VPP
- One interface which is still owned by the kernel
-The DPDK interface will be used for connecting the server with the hicn client, while the other interface will guarantee connectivity to the applications running in the VM, including the hicn-http-proxy. If you run the commands:
+The DPDK interface will be used for connecting the server with the hicn client,
+while the other interface will guarantee connectivity to the applications running
+in the VM, including the hicn-http-proxy. If you run the commands:
```bash
server$ sudo systemctl restart vpp
@@ -218,7 +236,8 @@ server$ vppctl set int state GigabitEthernetb/0/0 up
server$ vppctl set interface ip address GigabitEthernetb/0/0 9001::1/64
```
-Take care of replacing the interface name (`GigabitEthernetb/0/0`) with the actual name of your interface.
+Take care of replacing the interface name (`GigabitEthernetb/0/0`) with the
+actual name of your interface.
Now enable the hicn plugin and set the punting for the hicn packets:
diff --git a/docs/source/control.md b/docs/source/control.md
index e8d42bffa..b7b5ebce0 100644
--- a/docs/source/control.md
+++ b/docs/source/control.md
@@ -1,12 +1,13 @@
-# Control Plane Support
+# Control plane support
Control plane functionalities are provides via SDN controllers or via standard
IP routing protocols. SDN support is provided by using the NETCONF/YANG protocol
for network management, control and telemetry.
Routing is supported via synchronization of the IP FIB and the IP RIB as implemented
-by one of the routng protocols in FRR. Without loss of generality we have reported
+by one of the routing protocols in FRR. Without loss of generality we have reported
below one example of IGP routing via OSPF for IPv6.
+
The VPP IP FIB can be controlled and updated by one FRR routing protocol which
is used for routing over locators and also over hICN name prefixes.
@@ -28,24 +29,26 @@ at <https://dl.bintray.com/icn-team/apt-hicn-extras>.
For instance in Ubuntu 18 LTS:
-Install the sysrepo YANG data store and a NETCONF server.
+Install the sysrepo YANG data store and a NETCONF server:
-```shell
+```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.
+Install the VPP based hICN virtual switch:
-```shell
+```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 install under '/usr/lib/$(uname -m)-linux-gnu/modules_yang'.
-Configure the NETCONF/YANG components
-```shell
+The hICN YANG models are installed under `/usr/lib/$(uname -m)-linux-gnu/modules_yang`.
+
+Configure the NETCONF/YANG components:
+
+```bash
bash /usr/bin/setup.sh sysrepoctl /usr/lib/$(uname -m)-linux-gnu/modules_yang root
bash /usr/bin/merge_hostkey.sh sysrepocfg openssl
bash /usr/bin/merge_config.sh sysrepocfg genkey
@@ -53,7 +56,7 @@ bash /usr/bin/merge_config.sh sysrepocfg genkey
You can manually install the yang model using the following bash script:
-```shell
+```bash
EXIT_CODE=0
command -v sysrepoctl > /dev/null
if [ $? != 0 ]; then
@@ -70,8 +73,8 @@ hicn.yang can be found in the yang-model. It consists of two container nodes:
```text
|--+ hicn-conf: holds the configuration data;
-| |--+ params: contains all configuration parameters;
-|--+ hicn-state: provides the state data
+| |--+ params: contains all configuration parameters;
+|--+ hicn-state: provides the state data
| |--+ state,
| |--+ strategy,
| |--+ strategies,
@@ -92,7 +95,7 @@ data in hicn-state.
To setup the startup configuration you can use the following script:
-```shell
+```bash
EXIT_CODE=0
command -v sysrepocfg > /dev/null
if [ $? != 0 ]; then
@@ -105,7 +108,7 @@ fi
startup.xml is placed in the yang-model. Here you can find the content:
-```shell
+```xml
<hicn-conf xmlns="urn:sysrepo:hicn">
<params>
<enable_disable>false</enable_disable>
@@ -119,7 +122,7 @@ startup.xml is placed in the yang-model. Here you can find the content:
</hicn-conf>
```
-It contains the leaves of the params in hicn-conf node which is
+It contains the leaves of the parameters in hicn-conf node which is
used as the startup configuration. This configuration can be changed through the
controller by subscribing which changes the target to the running state. hicn
yang model provides a list of RPCs which allows controller to communicate
@@ -129,7 +132,7 @@ state data.
In order to run different RPCs from controller you can use the examples in the
controler_rpcs_instances.xml in the yang-model. Here you can find the content:
-```shell
+```xml
<node-params-get xmlns="urn:sysrepo:hicn"/>
<node-stat-get xmlns="urn:sysrepo:hicn"/>
@@ -213,16 +216,17 @@ netopeer2-server which serves as NETCONF server.
#### Connect from netopeer2-cli
-In order to connect through the netopeer client run the netopeer2-cli. Then, follow these steps:
+In order to connect through the netopeer client run the netopeer2-cli. Then,
+follow these steps:
- connect --host XXX --login XXX
- get (you can get the configuration and operational data)
- get-config (you can get the configuration data)
- edit-config --target running --config
-You can modify the configuration but it needs an xml configuration input
+You can modify the configuration but it needs an xml configuration input.
-```shell
+```xml
<hicn-conf xmlns="urn:sysrepo:hicn">
<params>
<enable_disable>false</enable_disable>
@@ -249,23 +253,24 @@ In order to connect through the OpenDaylight follow these procedure:
- run a rest client program (e.g., postman or RESTClient)
- mount the remote netopeer2-server to the OpenDaylight by the following REST API:
-PUT <http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/hicn-node>
-
-with the following body
-
-```shell
- <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
- <node-id>hicn-node</node-id>
- <host xmlns="urn:opendaylight:netconf-node-topology">Remote_NETCONF_SERVER_IP</host>
- <port xmlns="urn:opendaylight:netconf-node-topology">830</port>
- <username xmlns="urn:opendaylight:netconf-node-topology">username</username>
- <password xmlns="urn:opendaylight:netconf-node-topology">password</password>
- <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
- <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">1</keepalive-delay>
- </node>
-```
-
-Note that the header files must be set to Content-Type: application/xml, Accept: application/xml.
+ ```
+ PUT <http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/hicn-node>`
+ ```
+ with the following body:
+
+ ```xml
+ <node xmlns="urn:TBD:params:xml:ns:yang:network-topology">
+ <node-id>hicn-node</node-id>
+ <host xmlns="urn:opendaylight:netconf-node-topology">Remote_NETCONF_SERVER_IP</host>
+ <port xmlns="urn:opendaylight:netconf-node-topology">830</port>
+ <username xmlns="urn:opendaylight:netconf-node-topology">username</username>
+ <password xmlns="urn:opendaylight:netconf-node-topology">password</password>
+ <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only>
+ <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">1</keepalive-delay>
+ </node>
+ ```
+
+ Note that the header files must be set to `Content-Type: application/xml, Accept: application/xml`.
- send the operation through the following REST API:
@@ -302,44 +307,44 @@ The current version is compatible with the 20.01 VPP stable and sysrepo devel.
## Routing plugin for VPP and FRRouting for OSPF6
-This document describes how to configure the VPP with hicn_router
+This document describes how to configure the VPP with hicn_router
plugin and FRR to enable the OSPF protocol. The VPP and FRR
are configured in a docker file.
### DPDK configuration on host machine
-```text
-- Install and configure DPDK
-- make install T=x86_64-native-linux-gcc && cd x86_64-native-linux-gcc && sudo make install
- - modprobe uio
- - modprobe uio_pci_generic
- - dpdk-devbind --status
- - the PCIe number of the desired device can be observed ("xxx")
- - sudo dpdk-devbind -b uio_pci_generic "xxx"
+Install and configure DPDK:
+```bash
+make install T=x86_64-native-linux-gcc && cd x86_64-native-linux-gcc && sudo make install
+modprobe uio
+modprobe uio_pci_generic
+dpdk-devbind --status
+the PCIe number of the desired device can be observed ("xxx")
+sudo dpdk-devbind -b uio_pci_generic "xxx"
```
### VPP configuration
-```text
-- Run and configure the VPP (hICN router plugin is required to be installed in VPP)
- - set int state TenGigabitEtherneta/0/0 up
- - set int ip address TenGigabitEtherneta/0/0 a001::1/24
- - create loopback interface
- - set interface state loop0 up
- - set interface ip address loop0 b001::1/128
- - enable tap-inject # This creates the taps by router plugin
- - show tap-inject # This shows the created taps
- - ip mroute add ff02::/64 via local Forward # ff02:: is multicast ip address
- - ip mroute add ff02::/64 via TenGigabitEtherneta/0/0 Accept
- - ip mroute add ff02::/64 via loop0 Accept
+Run and configure the VPP (hICN router plugin is required to be installed in VPP):
+```bash
+vpp# set int state TenGigabitEtherneta/0/0 up
+vpp# set int ip address TenGigabitEtherneta/0/0 a001::1/24
+vpp# create loopback interface
+vpp# set interface state loop0 up
+vpp# set interface ip address loop0 b001::1/128
+vpp# enable tap-inject # This creates the taps by router plugin
+vpp# show tap-inject # This shows the created taps
+vpp# ip mroute add ff02::/64 via local Forward # ff02:: is multicast ip address
+vpp# ip mroute add ff02::/64 via TenGigabitEtherneta/0/0 Accept
+vpp# ip mroute add ff02::/64 via loop0 Accept
```
-```text
-- Setup the tap interface
- - ip addr add a001::1/24 dev vpp0
- - ip addr add b001::1/128 dev vpp1
- - ip link set dev vpp0 up
- - ip link set dev vpp1 up
+Setup the tap interface:
+```bash
+ip addr add a001::1/24 dev vpp0
+ip addr add b001::1/128 dev vpp1
+ip link set dev vpp0 up
+ip link set dev vpp1 up
```
### FRR configuration
@@ -347,20 +352,21 @@ are configured in a docker file.
Install FRR in Ubuntu 18 LTS:
<http://docs.frrouting.org/projects/dev-guide/en/latest/building-frr-for-ubuntu1804.html>
+Run and configure FRRouting (ospf):
```text
-- Run and configure FRRouting (ospf)
- - /usr/lib/frr/frrinit.sh start &
- - vtysh
- - configure terminal
- - router ospf6
- - area 0.0.0.0 range a001::1/24
- - area 0.0.0.0 range b001::1/128
- - interface vpp0 area 0.0.0.0
- - interface vpp1 area 0.0.0.0
- - end
- - wr
- - add "no ipv6 nd suppress-ra" to the first configurtion part of the /etc/frr/frr.conf
+/usr/lib/frr/frrinit.sh start &
+vtysh
+configure terminal
+router ospf6
+area 0.0.0.0 range a001::1/24
+area 0.0.0.0 range b001::1/128
+interface vpp0 area 0.0.0.0
+interface vpp1 area 0.0.0.0
+end
+wr
+add "no ipv6 nd suppress-ra" to the first configurtion part of the /etc/frr/frr.conf
```
-After the following configuration, the traffic over tap interface can be observered through "tcpdump- i vpp1".
-The neighborhood and route can be seen by the "show ipv6 ospf6 neighbor/route".
+After the following configuration, the traffic over tap interface can be observed
+via `tcpdump- i vpp1`. The neighborhood and route can be seen with the
+`show ipv6 ospf6 neighbor/route` command.
diff --git a/docs/source/hicn-light.md b/docs/source/hicn-light.md
index cee76940b..90e0afc91 100644
--- a/docs/source/hicn-light.md
+++ b/docs/source/hicn-light.md
@@ -1,4 +1,4 @@
-# Portable Forwarder
+# Portable forwarder
## Introduction
@@ -21,22 +21,22 @@ Basic dependencies:
- libevent
- libparc
-## hicn-light Executables
+## hicn-light executables
hicn-light is a set of binary executables that are used to run a forwarder instance.
-The forwarder can be run and configured using the commands
+The forwarder can be run and configured using the commands:
- `hicn-light-daemon`
- `hicn-light-control`
-Use the `-h` option to display the help messages
+Use the `-h` option to display the help messages.
-### hicn-light Daemon
+### hicn-light daemon
The command `hicn-light-daemon` runs the hicn-light forwarder. The forwarder can be executed
with the following options:
-```shell
+```bash
hicn-light-daemon [--port port] [--daemon] [--capacity objectStoreSize] [--log facility=level]
[--log-file filename] [--config file]
@@ -68,7 +68,7 @@ default port for hicn-light is 9695. Commands are expected on port 2001.
`hicn-light-control` can be used to send command to the hicn-light forwarder and configure it.
The command can be executed in the following way:
-```shell
+```bash
hicn-light-control [commands]
Options:
@@ -76,7 +76,7 @@ Options:
commands = configuration line to send to hicn-light (use 'help' for list)
```
-#### Available Commands in hicn-light-control
+#### Available commands in hicn-light-control
This is the full list of available commands in `hicn-light-control`. This commands can be used
from the command line running `hicn-light-control` as explained before, or listing them in a
@@ -88,29 +88,27 @@ Information about the commands are also available in the `hicn-light-control` he
For local connections (application to hicn-light) we expect a TCP listener. The default port for
the local listener is 9695.
-```shell
+```bash
add listener <protocol> <symbolic> <local_adress> <local_port>
<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.
-```shell
+```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
-
```
`add connection`: creates a TCP or UDP connection on the local forwarder with the specified options.
-```shell
+```bash
add connection <protocol> <symbolic> <remote_ip> <remote_port> <local_ip> <local_port>
<protocol> : tcp | udp
@@ -119,12 +117,11 @@ add connection <protocol> <symbolic> <remote_ip> <remote_port> <local_ip> <local
<remote_port> : the remote TCP/UDP port
<local_ip> : local IP address to bind to
<local_port> : local TCP/UDP port
-
```
`add connection hicn`: creates an hicn connection on the local forwarder with the specified options.
-```shell
+```bash
add connection hicn <symbolic> <remote_ip> <local_ip>
<symbolic> : symbolic name, e.g. 'conn1' (must be unique, start with alpha)
@@ -133,16 +130,15 @@ add connection hicn <symbolic> <remote_ip> <local_ip>
```
-`list`: lists the connections, routes or listeners available on the local hicn-light forwarder
+`list`: lists the connections, routes or listeners available on the local hicn-light forwarder.
-```shell
+```bash
list <connections | routes | listeners>
-
```
-`add route`: adds a route to the specified connection
+`add route`: adds a route to the specified connection.
-```shell
+```bash
add route <symbolic | connid> <prefix> <cost>
<symbolic> :The symbolic name for an exgress (must be unique, start with alpha)
@@ -154,7 +150,7 @@ add route <symbolic | connid> <prefix> <cost>
`remove connection`: removes the specified connection. At the moment, this commands is available
only for UDP connections, TCP is ignored.
-```shell
+```bash
remove connection <protocol> <symbolic | connid>
<protocol> : tcp | upd. This is the protocol used to create the connection.
@@ -163,48 +159,49 @@ remove connection <protocol> <symbolic | connid>
```
-`remove route`: remove the specified prefix for a local connection
+`remove route`: remove the specified prefix for a local connection.
-```shell
+```bash
remove route <symbolic | connid> <prefix>
<connid> : the alphanumeric name of a local connection
<prefix> : the prefix (ipAddress/netmask) to remove
```
-`cache serve`: enables/disables replies from local content store (if available)
+`cache serve`: enables/disables replies from local content store (if available).
-```shell
+```bash
cache serve <on|off>
```
`cache store`: enables/disables the storage of incoming data packets in the local content store
-(if available)
+(if available).
-```shell
+```bash
cache store <on|off>
```
-`cache clear`: removes all the cached data form the local content store (if available)
+`cache clear`: removes all the cached data form the local content store (if available).
-```shell
+```bash
cache clear
```
`set strategy`: sets the forwarding strategy for a give prefix. There are 4 different strategies
implemented in hicn-light:
-- random: each interest is forwarded randomly to one of the available output connections
-- loadbalancer: each interest is forwarded toward the output connection with the lowest number
+- **random**: each interest is forwarded randomly to one of the available output connections.
+- **loadbalancer**: each interest is forwarded toward the output connection with the lowest number
of pending interests. The pending interest are the interest sent on a certain connection but
- not yet satisfied. More information are available in:
- G. Carofiglio, M. Gallo, L. Muscariello, M. Papalini, S. Wang,
- "Optimal multipath congestion control and request forwarding in information-centric networks",
+ not yet satisfied. More information are available in:
+ G. Carofiglio, M. Gallo, L. Muscariello, M. Papalini, S. Wang,
+ "Optimal multipath congestion control and request forwarding in information-centric networks",
ICNP 2013.
-- low_latency: uses the face with the lowest latency. In case more faces have similar latency the strategy uses them in parallel
+- **low_latency**: uses the face with the lowest latency. In case more faces have similar
+ latency the strategy uses them in parallel.
-```shell
+```bash
set strategy <prefix> <strategy>
<preifx> : the prefix to which apply the forwarding strategy
@@ -212,14 +209,14 @@ set strategy <prefix> <strategy>
```
`set wldr`: turns on/off WLDR on the specified connection. WLDR (Wireless Loss Detiection and
- Recovery) is a protocol that can be used to recover losses generated by unreliable wireless
- connections, such as WIFI. More information on WLDR are available in:
- G. Carofiglio, L. Muscariello, M. Papalini, N. Rozhnova, X. Zeng,
- "Leveraging ICN In-network Control for Loss Detection and Recovery in Wireless Mobile networks",
+ Recovery) is a protocol that can be used to recover losses generated by unreliable wireless
+ connections, such as WIFI. More information on WLDR are available in:
+ G. Carofiglio, L. Muscariello, M. Papalini, N. Rozhnova, X. Zeng,
+ "Leveraging ICN In-network Control for Loss Detection and Recovery in Wireless Mobile networks",
ICN 2016. Notice that WLDR is currently available only for UDP connections. In order to work
properly, WLDR needs to be activated on both side of the connection.
-```shell
+```bash
set wldr <on|off> <symbolic | connid>
<symbolic> :The symbolic name for an exgress (must be unique, start with alpha)
@@ -227,46 +224,46 @@ set wldr <on|off> <symbolic | connid>
```
-`add punting`: Add punting rules to the forwarders.
+`add punting`: add punting rules to the forwarders.
-```shell
+```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
+`mapme enable`: enables/disables mapme.
-```shell
+```bash
mapme enable <on|off>
```
-`mapme discovery`: enables/disables mapme discovery
+`mapme discovery`: enables/disables mapme discovery.
-```shell
+```bash
mapme discovery <on|off>
```
-`mapme timescale`: set the timescale value expressed in millisencods
+`mapme timescale`: set the timescale value expressed in milliseconds.
-```shell
+```bash
mapme timescale <milliseconds>
```
-`mapme retx`: set the retrasmission time value expressed in millisecond
+`mapme retx`: set the retransmission time value expressed in millisecond.
-```shell
+```bash
mapme retx <milliseconds>
```
-`quit`: Exits the interactive shell
+`quit`: exits the interactive bash.
-### hicn-light Configuration File Example
+### hicn-light configuration file example
This is an example of a simple configuration file for hicn-light. It can be loaded by running
-the command `hicn-light-daemon --config configFile.cfg`, assuming the file name is configFile.cfg
+the command `hicn-light-daemon --config configFile.cfg`, assuming the file name is `configFile.cfg`.
-```shell
+```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
diff --git a/docs/source/interface.md b/docs/source/interface.md
index 9e6b6f383..cf05a5c7b 100644
--- a/docs/source/interface.md
+++ b/docs/source/interface.md
@@ -1,4 +1,4 @@
-# Face Manager
+# Face manager
## Overview
@@ -88,7 +88,7 @@ Registration and instantiation of the different interfaces is currently done at
compile time in the file `src/api.c`, and the appropriate hooks to use the dummy
interface are available in the code between `#if 0/#endif` tags.
-#### Interface template header; configuration parameters
+#### Interface template header and configuration parameters
All interfaces have a standard interface defined in `src/interface.{h,c}`, and
as such the header file is only used to specify the configuration parameters of
@@ -210,7 +210,7 @@ if (rc < 0) {
}
```
-#### Implementation of the Interface API
+#### Implementation of the interface API
We now quickly go other the different functions, but their usage will be better
understood through the hands-on example treated in the following section.
@@ -277,7 +277,7 @@ dereference it from the interface pointer they receive as parameter:
dummy_data_t * data = (dummy_data_t*)interface->data;
```
-#### Raising and Receiving Events
+#### Raising and receiving events
An interface will receive events in the form of a facelet through the `*_on_event`
function. It can then use the facelet API we have described above to read
@@ -287,7 +287,7 @@ As this information is declared const, the interface can either create a new
facelet (identified by the same netdevice and protocol family), or eventually
clone it.
-The facelet event can then be defined and raised to the face maanger for further
+The facelet event can then be defined and raised to the face manager for further
processing through the following code:
```C
@@ -298,7 +298,7 @@ processing through the following code:
Here the event is a facelet creation (`EVENT_TYPE_CREATE`). The full facelet API
and the list of possible event types is available in `src/facelet.h`
-#### Integration in the Build System
+#### Integration in the build system
The build system is based on CMake. Each interface should declare its source
files, private and public header files, as well as link dependencies in the
@@ -306,7 +306,7 @@ local `CMakeLists.txt` file.
TODO: detail the structure of the file
-### Hands-On
+### Hands-on
#### Architecture
@@ -325,18 +325,18 @@ equal to either \0 (which we might interpret as enable LTE, disable WiFi), or \1
Our objective is to develop a new face manager interface that would listen to
such event in order to update the administrative status of the current faces.
-This would thus alternatively set the different interfaces admnistratively up
+This would thus alternatively set the different interfaces administratively up
and down (which takes precedence over the actual status of the interface when
the forwarder establishes the set of available next hops for a given prefix).
The actual realization of such queries will be ultimately performed by the
hicn-light interface.
-#### Sample Server and Client
+#### Sample server and client
In the folder containing the source code of hICN, the following commands allow
to run the sample server:
-```shell
+```bash
cd ctrl/facemgr/examples/updownsrv
make
./updownsrv
@@ -346,7 +346,7 @@ The server should display "Waiting for clients..."
Similar commands allow to run the sample client:
-```shell
+```bash
cd ctrl/facemgr/examples/updowncli
make
./updowncli
@@ -355,7 +355,7 @@ make
The client should display "Waiting for server data...", then every couple of
seconds display either "WiFi" or "LTE".
-#### Face Manager Interface
+#### Face manager interface
An example illustrating how to connect to the dummy service from `updownsrv` is
provided as the `updown` interface in the facemgr source code.
diff --git a/docs/source/lib.md b/docs/source/lib.md
index 1e7d09e7a..bd021d30c 100644
--- a/docs/source/lib.md
+++ b/docs/source/lib.md
@@ -1,5 +1,4 @@
-
-# Core Library
+# Core library
## Introduction
@@ -30,9 +29,9 @@ A commandline interface (hicnc) is also provided that uses the library and can
for instance be used as a test traffic generator. This interface can be run as
either a consumer, a producer, or a simple forwarder.
-## Directory Layout
+## Directory layout
-```shell
+```bash
.
+-- CMakeLists.txt CMkake global build file
+-- doc Package documentation
@@ -45,7 +44,7 @@ either a consumer, a producer, or a simple forwarder.
| +-- error.{h,c} Error management files
| +-- header.h hICN header definitions
| +-- hicn.h Master include file
-| +-- mapme.{h,c} MAP-Me : anchorless producer mobility mechanisms
+| +-- mapme.{h,c} MAP-Me : anchorless producer mobility mechanisms
| +-- name.{h,c} hICN naming conventions and name processing + IP helpers
| +-- ops.{h,c} Protocol-independent hICN operations
| +-- protocol/* Protocol headers + protocol-dependent implementations
@@ -67,16 +66,20 @@ Basic dependencies: None
### Release mode
+```bash
mkdir build
cd build
cmake ..
make
sudo make install
+```
### Debug mode
+```bash
mkdir debug
cd debug
cmake .. -DCMAKE_BUILD_TYPE=Debug
make
sudo make install
+```
diff --git a/docs/source/started.md b/docs/source/started.md
index 3c5181297..ef3763366 100644
--- a/docs/source/started.md
+++ b/docs/source/started.md
@@ -4,10 +4,10 @@
hicn is an open source implementation of Cisco's hICN. It includes a network stack, that implements
ICN forwarding path in IPv6, and a transport stack that implements two main transport protocols and
-a socket API. The transport protocols provide one reliable transport service implementaton and a
+a socket API. The transport protocols provide one reliable transport service implementation and a
real-time transport service for audio/video media.
-## Directory Layout
+## Directory layout
```text
| Directory name | Description |
@@ -29,11 +29,11 @@ local namespace (local face management).
## Release note
-The current master branch provides the latest release which is compatible with the lates VPP stable.
+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 rigth code tree by searching the latest commit under a given git tag carrying the
+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.
@@ -43,7 +43,7 @@ on VPP and one portable based on IPC and sockets.
The transport stack is a unique library that is used for both the scalable
and portable network stacks.
-## Supported Platforms
+## Supported platforms
- Ubuntu 18.04 LTS (amd64, arm64)
- Debian Stable/Testing
@@ -59,19 +59,19 @@ You can either use released packages, or compile hicn from sources.
### Ubuntu
-```shell
+```bash
curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
```
### CentOS
-```shell
+```bash
curl -s https://packagecloud.io/install/repositories/fdio/release/script.rpm.sh | sudo bash
```
### macOS
-```shell
+```bash
brew install hicn
```
@@ -90,11 +90,12 @@ Coming soon.
### Docker
-Several docker images are nightly built with the latest software for Ubuntu 18 LTS (amd64/arm64), and available on docker hub at <https://hub.docker.com/u/icnteam>.
+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.
-```shell
+```bash
docker pull icnteam/vswitch:amd64
docker pull icnteam/vswitch:arm64
@@ -110,16 +111,17 @@ docker pull icnteam/vhttpproxy:arm64
Vagrant boxes for a virtual switch are available at
<https://app.vagrantup.com/icnteam>
-```shell
+```bash
vagrant box add icnteam/vswitch
```
+
Supported providers are libvirt, vmware and virtualbox.
## License
This software is distributed under the following license:
-```shell
+```bash
Copyright (c) 2017-2020 Cisco and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
diff --git a/docs/source/telemetry.md b/docs/source/telemetry.md
index 868958f2b..4296f1c12 100644
--- a/docs/source/telemetry.md
+++ b/docs/source/telemetry.md
@@ -2,29 +2,27 @@
Tools to collect telemetry from hICN forwarders.
-## Introduction ##
+## Introduction
-The project containes two plugins for [collectd](https://github.com/collectd/collectd):
+The project contains two plugins for [collectd](https://github.com/collectd/collectd):
* vpp: to collect statistics for VPP
* vpp-hicn: to collect statistics for [hICN](https://github.com/FDio/hicn)
+Currently the two plugins provide the following functionalities:
+* vpp: statistics (rx/tx bytes and packets) for each available interface.
+* vpp-hicn: statistics (rx/tx bytes and packets) for each available face.
-Currently the two plugins provide the followign funtionalities:
+## Quick start
-* VPP: statistics (rx/tx bytes and packets) for each available interface.
-* HICN-VPP: statistics (rx/tx bytes and packets) for each available face.
+From the code tree root:
-## Quick Start ##
-
-```
-From the code tree root
-
-$ cd telemetry
-$ mkdir -p build
-$ cd build
-$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr
-$ make
-$ sudo make install
+```bash
+cd telemetry
+mkdir -p build
+cd build
+cmake .. -DCMAKE_INSTALL_PREFIX=/usr
+make
+sudo make install
```
## Using hICN collectd plugins
@@ -39,7 +37,6 @@ hICN collectd plugins have been tested in:
- Red Hat Enterprise Linux 7
- CentOS 7
-
### Dependencies
Build dependencies:
@@ -54,16 +51,19 @@ Build dependencies:
## Getting started
Collectd needs to be configured in order to use the hICN collectd plugins.
-The configuration can be achieved editing the file '/etc/collectd/collectd.conf' and adding the following lines:
-
+The configuration can be achieved editing the file '/etc/collectd/collectd.conf'
+and adding the following lines:
```
LoadPlugin vpp
LoadPlugin vpp_hicn
```
-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
+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.
+
+### Example: storing statistics from vpp and vpp-hicn
-### Example: use rrdtool and csv plugin to store statistics from vpp and vpp-hicn plugins
+We'll use the rrdtool and csv plugins to store statistics from vpp and vpp-hicn.
Edit the configuration file as the following:
@@ -73,7 +73,7 @@ Edit the configuration file as the following:
######################################################################
FQDNLookup true
BaseDir "/collectd"
-Interval 2
+Interval 1
######################################################################
# Logging #
@@ -104,13 +104,13 @@ LoadPlugin vpp_hicn
</Plugin>
<Plugin rrdtool>
- DataDir "/collectd/rrd" # the folder under which statistics are written in csv
+ DataDir "/collectd/rrd" # the folder under which statistics are written in rrd
</Plugin>
```
-Run vpp and collectd
+Run vpp and collectd:
```
-$ systemctl start vpp
-$ systemctl start collectd
+systemctl start vpp
+systemctl start collectd
```
diff --git a/docs/source/transport.md b/docs/source/transport.md
index 4719d7227..3e7844ad5 100644
--- a/docs/source/transport.md
+++ b/docs/source/transport.md
@@ -1,4 +1,4 @@
-# The Transport Library
+# Transport library
## Introduction
@@ -6,14 +6,16 @@ This library provides transport services and socket API for applications willing
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.
+- Implementation of the hICN core objects (interest, data, name..) exploiting
+ the API provided by [libhicn](../lib).
+- Connectors for connecting the application to either the hicn-plugin or the
+ hicn-light forwarder.
- Transport protocols (RAAQM, CBR, RTC)
- Transport services (authentication, integrity, segmentation, reassembly, naming)
-- Interfaces for applications (from low-level interfaces for interest-data interaction to high level interfaces for Application Data Unit interaction)
+- Interfaces for applications (from low-level interfaces for interest-data
+ interaction to high level interfaces for Application Data Unit interaction)
-## Build Dependencies
+## Build dependencies
### Ubuntu
@@ -21,31 +23,34 @@ Overview:
- libmemif (linux only, if compiling with VPP support)
- libasio
-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:
+If you wish to use the library for connecting to the vpp hicn-plugin, you will
+need to also install vpp, the vpp libraries and the libmemif libraries:
- DEB packages:
- vpp
- vpp-lib
- vpp-dev
-You can get them either from from the vpp packages ot the source code. Check the [VPP wiki](https://wiki.fd.io/view/VPP) for instructions.
+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
-We recommend to use [HomeBrew](https://brew.sh/) for installing the libasio dependency:
+We recommend to use [HomeBrew](https://brew.sh/) for installing the libasio
+dependency:
```bash
- brew install asio
+brew install asio
```
Download, compile and install libparc:
```bash
- git clone -b cframework/master https://gerrit.fd.io/r/cicn cframework && cd cframework
- mkdir -p libparc.build && cd libparc.build
- cmake ../libparc
- make
- make install
+git clone -b cframework/master https://gerrit.fd.io/r/cicn cframework && cd cframework
+mkdir -p libparc.build && cd libparc.build
+cmake ../libparc
+make
+make install
```
Libparc will be installed by default under `/usr/local/lib` and `/usr/local/include`.
@@ -56,10 +61,10 @@ Since VPP does not support macOS, the hicn-plugin connector is not built.
From the project root folder:
```bash
- cd libtransport
- mkdir build && cd build
- cmake ..
- make
+cd libtransport
+mkdir build && cd build
+cmake ..
+make
```
### Compile options
@@ -67,12 +72,14 @@ From the project root folder:
The build process can be customized with the following options:
- `CMAKE_INSTALL_PREFIX`: The path where you want to install the library.
-- `CMAKE_BUILD_TYPE`: The build configuration. Options: `Release`, `Debug`. Default is `Release`.
+- `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.
+- `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`.
@@ -81,5 +88,5 @@ An option can be set using cmake -D`OPTION`=`VALUE`.
For installing the library, from the cmake build folder:
```bash
- sudo make install
+sudo make install
```
diff --git a/docs/source/utils.md b/docs/source/utils.md
index 57104e12a..79ada8985 100644
--- a/docs/source/utils.md
+++ b/docs/source/utils.md
@@ -2,20 +2,21 @@
## Introduction
-hicn-ping-server, hicn-ping-client and hiperf are three utility applications for testing and benchmarking stack.
+hicn-ping-server, hicn-ping-client and hiperf are three utility applications
+for testing and benchmarking stack.
-## Using hICN Utils applications
+## Using hICN utils applications
### Dependencies
Build dependencies:
-- C++14 ( clang++ / g++ )
+- C++14 (clang++ / g++)
- CMake 3.4
Basic dependencies:
-- ppenSSL
+- OpenSSL
- pthreads
- libevent
- libparc
@@ -23,14 +24,16 @@ Basic dependencies:
## Executables
-The utility applications are a set of binary executables consisting of a client/server ping applications (hicn-ping-server and hicn-ping-client) and a hicn implementation of hicn (hiperf).
+The utility applications are a set of binary executables consisting of a
+client/server ping applications (hicn-ping-server and hicn-ping-client) and
+a hicn implementation of iPerf (hiperf).
### hicn-ping-server
-The command `hicn-ping-server` runs the server side ping application. hicn-ping-server can be executed
-with the following options:
+The command `hicn-ping-server` runs the server side ping application.
+`hicn-ping-server` can be executed with the following options:
-```shell
+```bash
usage: hicn-ping-server [options]
Options:
@@ -42,20 +45,23 @@ Options:
-t <ttl> = set ttl (default 64)
-V = verbose, prints statistics about the messagges sent and received (default false)
-D = dump, dumps sent and received packets (default false)
--q = quite, not prints (default false)
+-q = quiet, no printing (default false)
-d = daemon mode
-H = help
+```
Example:
+
+```bash
hicn-ping-server -n c001::/64
```
### hicn-ping-client
-The command `hicn-ping-client` runs the client side ping application. hicn-ping-client can be executed
-with the following options:
+The command `hicn-ping-client` runs the client side ping application.
+`hicn-ping-client` can be executed with the following options:
-```shell
+```bash
usage: hicn-ping-client [options]
Options:
@@ -71,91 +77,108 @@ Options:
-l <lifetime> = interest lifetime in milliseconds (default 500ms)
-V = verbose, prints statistics about the messagges sent and received (default false)
-D = dump, dumps sent and received packets (default false)
--q = quiet, not prints (default false)
+-q = quiet, no printing (default false)
-H = help
+```
Example:
+```
hicn-ping-client -n c001::1
```
### hiperf
-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:
+The command `hiperf` is a tool for performing network throughput measurements
+with hicn. It can be executed as server or client using the following options:
-```shell
+```bash
usage: hiperf [-S|-C] [options] [prefix|name]
-Options:
--D = run as a daemon
--R = run RTC protocol (client or server)
--f <ouptup_log_file> = output log file path
-
-Server specific:
--A <download_size> = size of the content to publish. This is not the size of the packet (see -s for it)
--s <payload_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 the packets
--y <hash_algorithm> = use the selected hash algorithm for calculating manifest digests
--p <password> = password for p12 keystore
--x = produce a content of <download_size>, then after downloading it produces a new
- content of <download_size> without resetting the suffix to 0
--B <bitrate> = bitrate for RTC producer, to be used with the -R option, in kbps (example: 64kbps)
-
-Client specific:
--b <beta_parameter> = RAAQM beta parameter
--d <drop_factor_parameter> = RAAQM drop factor parameter
--M = store the content downloaded (default false)
--W <window_size> = use a fixed congestion window for retrieving the data
--c <certificate_path> = path of the producer certificate to be used for verifying the origin of the packets received
--i <stats_interval> = show the statistics every <stats_interval> milliseconds
--v = Enable verification of received data
+SERVER OR CLIENT:
+-D = Run as a daemon
+-R = Run RTC protocol (client or server)
+-f <filename> = Log file
+
+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
+
+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
+```
Example:
+```
hiperf -S c001::/64
```
-## Client-Server Benchmarking using hiperf
+## Client/Server benchmarking using `hiperf`
### hicn-light-daemon
-This tutorial will explain how to configure a simple client-server topology and retrieve network measurements using the hiperf utility.
+This tutorial will explain how to configure a simple client-server topology and
+retrieve network measurements using the hiperf utility.
-We consider this simple topology, consisting on two linux VM which are able to communicate through an IP network (you can also use containers or physical machines):
+We consider this simple topology, consisting on two linux VM which are able to
+communicate through an IP network (you can also use containers or physical
+machines):
-```text
+```
|client (10.0.0.1/24; 9001::1/64)|======|server (10.0.0.2/24; 9001::2/64)|
```
-Install the hICN suite on two linux VM. This tutorial makes use of Ubuntu 18.04, but it could easily be adapted to other platforms.
-You can either install the hICN stack using binaries or compile the code. In this tutorial we will build the code from source.
+Install the hICN suite on two linux VM. This tutorial makes use of Ubuntu 18.04,
+but it could easily be adapted to other platforms.
+You can either install the hICN stack using binaries or compile the code. In
+this tutorial we will build the code from source.
```bash
-$ curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
-$ apt-get install -y git \
- cmake \
- build-essential \
- libasio-dev \
- libcurl4-openssl-dev \
- libparc-dev \
- --no-install-recommends
-
-$ mkdir hicn-suite && cd hicn-suite
-$ git clone https://github.com/FDio/hicn hicn-src
-$ mkdir hicn-build && cd hicn-build
-$ cmake ../hicn-src -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../hicn-install -DBUILD_APPS=ON
-$ make -j 4 install
-$ export HICN_ROOT=${PWD}/../hicn-install
+apt-get update && apt-get install -y curl
+curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
+apt-get install -y git \
+ cmake \
+ build-essential \
+ libasio-dev \
+ libcurl4-openssl-dev \
+ --no-install-recommends \
+ libparc-dev
+mkdir hicn-suite && cd hicn-suite
+git clone https://github.com/FDio/hicn.git hicn-src
+mkdir hicn-build && cd hicn-build
+cmake ../hicn-src -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../hicn-install -DBUILD_APPS=ON
+make -j4 install
+export HICN_ROOT=${PWD}/../hicn-install
```
It should install the hICN suite under hicn-install.
#### hicn-light forwarder with UDP faces
-##### Server Configuration
+##### Server configuration
-Create a configuration file for the hicn-light forwarder. Here we are configuring UDP faces.
+Create a configuration file for the hicn-light forwarder. Here we are
+configuring UDP faces.
```bash
server$ mkdir -p ${HICN_ROOT}/etc
@@ -166,25 +189,29 @@ add listener udp list0 ${LOCAL_IP} ${LOCAL_PORT}
EOF
```
-Start the hicn-light forwarder
+Start the hicn-light forwarder:
```bash
server$ sudo ${HICN_ROOT}/bin/hicn-light-daemon --daemon --capacity 0 --log-file ${HICN_ROOT}/hicn-light.log --config ${HICN_ROOT}/etc/hicn-light.conf
```
-We set the forwarder capacity to 0 because we want to measure the end-to-end performance without retrieving any data packet from intermediate caches.
+We set the forwarder capacity to 0 because we want to measure the end-to-end
+performance without retrieving any data packet from intermediate caches.
-Run the [hiperf](#hiperf) server.
+Run the [hiperf](#hiperf) server:
```bash
server$ ${HICN_ROOT}/bin/hiperf -S b001::/64
```
-The hiperf server will register the prefix b001::/64 on the local forwarder and will reply with pre-allocated data packet. In this test we won't consider segmentation and reassembly cost.
+The hiperf server will register the prefix b001::/64 on the local forwarder and
+will reply with pre-allocated data packet. In this test we won't consider
+segmentation and reassembly cost.
-##### Client Configuration
+##### Client configuration
-Create a configuration file for the hicn-light forwarder at the client. Here we are configuring UDP faces.
+Create a configuration file for the hicn-light forwarder at the client. Here we
+are configuring UDP faces.
```bash
client$ mkdir -p ${HICN_ROOT}/etc
@@ -199,7 +226,7 @@ add route conn0 b001::/16 1
EOF
```
-Run the hicn-light forwarder
+Run the hicn-light forwarder:
```bash
client$ sudo ${HICN_ROOT}/bin/hicn-light-daemon --daemon --capacity 1000 --log-file ${HICN_ROOT}/hicn-light.log --config ${HICN_ROOT}/etc/hicn-light.conf
@@ -216,7 +243,8 @@ This will run the client with a fixed window of 50 interests.
#### hicn-light forwarder with hICN faces
-For sending hICN packets directly over the network, using hicn faces, change the configuration of the two forwarders and restart them.
+For sending hICN packets directly over the network, using hicn faces, change
+the configuration of the two forwarders and restart them.
#### Server
@@ -247,27 +275,28 @@ EOF
### VPP based hicn-plugin
-Compile the hicn stack enabling the [vpp](https://github.com/FDio/vpp) support.
-
-In this example we will do a local hiperf client-server communication.
+In this example we will do a local hiperf client-server communication. First,
+we need to compile the hicn stack and enable [VPP](https://github.com/FDio/vpp)
+support:
```bash
-$ curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
-$ apt-get install -y git \
- cmake \
- build-essential \
- libasio-dev \
- libcurl4-openssl-dev \
- libparc-dev \
- vpp libvppinfra vpp-plugin-core vpp-dev python3-ply python python-ply \
- --no-install-recommends
-
-$ mkdir hicn-suite && cd hicn-suite
-$ git clone https://github.com/FDio/hicn hicn-src
-$ mkdir hicn-build && cd hicn-build
-$ cmake ../hicn-src -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_APPS=ON -DBUILD_HICNPLUGIN=ON
-$ sudo make -j 4 install
-$ export HICN_ROOT=${PWD}/../hicn-install
+apt-update && apt-get install -y curl
+curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash
+apt-get install -y git \
+ cmake \
+ build-essential \
+ libasio-dev \
+ vpp vpp-dev vpp-plugin-core libvppinfra \
+ libmemif libmemif-dev \
+ python3-ply \
+ --no-install-recommends \
+ libparc-dev
+mkdir hicn-suite && cd hicn-suite
+git clone https://github.com/FDio/hicn.git hicn-src
+mkdir hicn-build && cd hicn-build
+cmake ../hicn-src -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_APPS=ON -DBUILD_HICNPLUGIN=ON
+sudo make -j 4 install
+export HICN_ROOT=${PWD}/../hicn-install
```
Make sure vpp is running:
diff --git a/docs/source/vpp-plugin.md b/docs/source/vpp-plugin.md
index 772f9a730..0200e38b7 100644
--- a/docs/source/vpp-plugin.md
+++ b/docs/source/vpp-plugin.md
@@ -1,6 +1,4 @@
-# VPP plugin
-
-The hICN-plugin forwarder
+# VPP Plugin
## Introduction
@@ -13,40 +11,46 @@ The plugin provides the following functionalities:
- Content caching
- Forwarding strategies
-## Quick Start
+## Quick start
+
+All of these commands should be run from the code tree root.
+VPP installed with DEB pkg:
```bash
-From the code tree root
-
-(VPP installed with DEB pkg)
-$ cd hicn-plugin
-$ mkdir -p build
-$ cd build
-$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr
-$ make
-$ sudo make install
-
-(VPP source code -- build type RELEASE)
-$ cd hicn-plugin
-$ 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
-
-(VPP source code -- build type DEBUG)
-$ cd hicn-plugin
-$ 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
+cd hicn-plugin
+mkdir -p build
+cd build
+cmake .. -DCMAKE_INSTALL_PREFIX=/usr
+make
+sudo make install
+```
-CMAKE variables:
-- CMAKE_INSTALL_PREFIX -- set the install directory for the hicn-plugin. This is the common path to the lib folder containing vpp_plugins and vpp_api_test_plugins folders. Default is /usr/local.
-- VPP_HOME -- set the directory containing the include and lib directories of vpp.
+VPP source code - build type `RELEASE`:
+```bash
+cd hicn-plugin
+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
```
+VPP source code - build type `DEBUG`:
+```bash
+cd hicn-plugin
+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 variables:
+- `CMAKE_INSTALL_PREFIX`: set the install directory for the hicn-plugin. This
+ is the common path to the lib folder containing vpp_plugins and
+ vpp_api_test_plugins folders. Default is /usr/local.
+- `VPP_HOME`: set the directory containing the include and lib directories of vpp.
+
## Using hICN plugin
### Dependencies
@@ -55,17 +59,17 @@ Build dependencies:
- VPP 20.01
- DEB packages (can be found <https://packagecloud.io/fdio/release/install):>
- - vpp
- - libvppinfra-dev
- - vpp-dev
+ - vpp
+ - libvppinfra-dev
+ - vpp-dev
Runtime dependencies:
- VPP 20.01
- DEB packages (can be found <https://packagecloud.io/fdio/release/install):>
- - vpp
- - vpp-plugin-core
- - vpp-plugin-dpdk (only to use DPDK compatible nics)
+ - vpp
+ - vpp-plugin-core
+ - vpp-plugin-dpdk (only to use DPDK compatible nics)
Hardware support (not mandatory):
@@ -73,7 +77,7 @@ Hardware support (not mandatory):
## Getting started
-In order to start, the hICN plugin requires a running instance of VPP
+In order to start, the hICN plugin requires a running instance of VPP.
The steps required to successfully start hICN are:
- Setup the host to run VPP
@@ -82,25 +86,27 @@ The steps required to successfully start hICN are:
- Configure VPP interfaces
- Configure and start hICN
-Detailed information for configuring VPP can be found at [https://wiki.fd.io/view/VPP](https://wiki.fd.io/view/VPP).
+Detailed information for configuring VPP can be found at
+[https://wiki.fd.io/view/VPP](https://wiki.fd.io/view/VPP).
### Setup the host for VPP
-Hugepages must be enabled in the system
+Hugepages must be enabled in the system.
-```shell
+```bash
sudo sysctl -w vm.nr_hugepages=1024
```
-In order to use a DPDK interface, the `uio` and `uio_pci_generic` or `vfio_pci` modules need to be loaded in the kernel
+In order to use a DPDK interface, the `uio` and `uio_pci_generic` or `vfio_pci`
+modules need to be loaded in the kernel.
-```shell
+```bash
sudo modprobe uio
sudo modprobe uio_pci_generic
sudo modprobe vfio_pci
```
-If the DPDK interface we want to assign to VPP is up, we must bring it down
+If the DPDK interface we want to assign to VPP is up, we must bring it down:
```bash
sudo ifconfig <interface_name> down
@@ -114,10 +120,10 @@ sudo ip link set <interface_name> down
### Configure VPP
-The file /etc/VPP/startup.conf contains a set of parameters to setup VPP at startup.
-The following example sets up VPP to use a DPDK interfaces:
+The file `/etc/VPP/startup.conf` contains a set of parameters to setup VPP
+at startup. The following example sets up VPP to use a DPDK interface:
-``` shell
+```bash
unix {
nodaemon
log /tmp/vpp.log
@@ -150,37 +156,42 @@ plugins {
}
```
-Where `0000:08:00.0` must be replaced with the actual PCI address of the DPDK interface
+`0000:08:00.0` must be replaced with the actual PCI address of the DPDK
+interface.
### Start VPP
VPP can be started as a process or a service:
-``` shell
-Start VPP as a service in Ubuntu 16.04
-$ sudo systemctl start vpp
-
-Start VPP as a process in both 16.04
-$ sudo vpp -c /etc/vpp/startup.conf
+Start VPP as a service in Ubuntu 16.04+:
+```bash
+sudo systemctl start vpp
+```
+Start VPP as a process:
+```bash
+sudo vpp -c /etc/vpp/startup.conf
```
### Configure hICN plugin
-The hICN plugin can be configured either using the VPP command-line interface (CLI), through a configuration file or through the VPP binary api
+The hICN plugin can be configured either using the VPP command-line interface
+(CLI), through a configuration file or through the VPP binary API.
#### hICN plugin CLI
-The CLI commands for the hICN plugin start all with the hicn keyword. To see the full list of command available type:
+The CLI commands for the hICN plugin start all with the `hicn` keyword.
+To see the full list of command available type:
-``` shell
-$ sudo vppctl
+```bash
+sudo vppctl
vpp# hicn ?
```
-`hicn control param`: configures the internal parameter of the hICN plugin. This command must be run before hicn control start.
+`hicn control param`: configures the internal parameter of the hICN plugin.
+This command must be run before hicn control start.
-```shell
+```bash
hicn control param { pit { size <entries> | { dfltlife | minlife | maxlife } <seconds> } | cs {size <entries> | app <portion to reserved to app>} }
<entries> :set the maximum number of entry in the PIT or CS. Default for PIT is 131072, for CS is 4096. CS size cannot be grater than PIT size. Moreover CS size must be smaller than (# of vlib buffer - 8196).
<seconds> :set the default, maximum or minimum lifetime of pit entries. Default value 2s (default), 0.2s (minumum), 20s (maximum)
@@ -193,18 +204,17 @@ hicn control param { pit { size <entries> | { dfltlife | minlife | maxlife } <se
`hicn face app` : manipulates producer and consumer application faces in the forwarder.
-```shell
+```bash
hicn face app {add intfc <sw_if> {prod prefix <hicn_prefix> cs_size <size_in_packets>} {cons}} | {del <face_id>}
<sw_if> :software interface existing in vpp on top of which to create an application face
<hicn_prefix> :prefix to bound to the producer application face. Only content matching the prefix will be allowed through such face.
<size_in_packets> :content store size associated to the producer face.
<face_id> :id of the face to remove
-
```
`hicn face ip`: manipulates ip application faces in the forwarder.
-```shell
+```bash
hicn face ip {add [local <src_address>] remote <dst_address> intfc <sw_if>} | {del id <face_id>}
<src_address> :the IPv4 or IPv6 local IP address to bind to (not mandatory, if not specified the local address is one of the address assigned to sw_if)
<dst_address> :the IPv4 or IPv6 address of the remote system
@@ -214,7 +224,7 @@ hicn face ip {add [local <src_address>] remote <dst_address> intfc <sw_if>} | {d
`hicn face show`: list the available faces in the forwarder.
-```shell
+```bash
hicn face show [<face_id>| type <ip/udp>]
<face_id> :face id of which we want to display the informations
<ip/udp> :shows all the ip or udp faces available
@@ -222,7 +232,7 @@ hicn face show [<face_id>| type <ip/udp>]
`hicn face udp`: manipulates udp application faces in the forwarder.
-```shell
+```bash
hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address> port <dst_port>} intfc <sw_if> | {del id <face_id>}
<src_address> :the IPv4 or IPv6 local IP address to bind to
<src_port> :the local UDP port
@@ -235,16 +245,16 @@ hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address
`hicn fib`: manipulates hicn fib entries.
-```shell
+```bash
hicn fib {{add | delete } prefix <prefix> face <face_id> } | set strategy <strategy_id> prefix <prefix>
<prefix> :prefix to add to the FIB
<face_id> :face id to add as nexto hop in the FIB entry
<strategy_id> :set a strategy for the corresponding prefix
```
-`hicn pgen client`: set an vpp forwarder as an hicn packet generator client
+`hicn pgen client`: set an vpp forwarder as an hicn packet generator client.
-```shell
+```bash
hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> lifetime <interest-lifetime> intfc <data in-interface> max_seq <max sequence number> n_flows <number of flows>
<ip|hicn> :set if the underlying forwarder is configured as ip or hicn
<src_addr> :source address to use in the interests, i.e., the locator for routing the data packet back
@@ -256,9 +266,9 @@ hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> life
<number of flows> :emulate multiple flows downloaded in parallel
```
-`hicn pgen server`: set an vpp forwarder as an hicn packet generator client
+`hicn pgen server`: set an vpp forwarder as an hicn packet generator client.
-```shell
+```bash
hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size <payload_size>
<ip|hicn> :set if the underlying forwarder is configured as ip or hicn
<prefix> :prefix to use to reply to interest
@@ -266,9 +276,9 @@ hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size
<payload_size> :size of the data payload
```
-`hicn punting`: manipulates punting rules
+`hicn punting`: manipulates punting rules.
-```shell
+```bash
hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|udp6> src_port <src_port> dst_port <dst_port>}
<prefix> :prefix to punt to the hICN plugin
<sw_if> :software interface where to apply the punting
@@ -279,7 +289,7 @@ hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|ud
`hicn show`: show forwarder information.
-```shell
+```bash
hicn show [detail] [strategies]
<detail> :shows additional details as pit,cs entries allocation/deallocation
<strategies> :shows only the available strategies int he forwarder
@@ -287,7 +297,7 @@ hicn show [detail] [strategies]
`hicn strategy mw set`: set the weight for a face.
-```shell
+```bash
hicn strategy mw set prefix <prefix> face <face_id> weight <weight>
<prefix> :prefix to which the strategy applies
<face_id> :id of the face to set the weight
@@ -296,9 +306,12 @@ hicn strategy mw set prefix <prefix> face <face_id> weight <weight>
#### hICN plugin configuration file
-A configuration can be use to setup the hicn plugin when vpp starts. The configuration file is made of a list of CLI commands. In order to set vpp to read the configuration file, the file /etc/vpp/startup.conf needs to be modified as follows:
+A configuration can be use to setup the hicn plugin when vpp starts.
+The configuration file is made of a list of CLI commands. In order to set vpp
+to read the configuration file, the file `/etc/vpp/startup.conf` needs to be
+modified as follows:
-```shell
+```bash
unix {
nodaemon
log /tmp/vpp.log
@@ -309,16 +322,23 @@ unix {
#### hICN plugin binary API
-The binary api, or the vapi, can be used as well to configure the hicn plugin. For each cli command there is a corresponding message in the binary api. The list of messages is available in the file hicn.api (located in hicn/hicn-plugin/src/)
+The binary api, or the vapi, can be used as well to configure the hicn plugin.
+For each CLI command there is a corresponding message in the binary api.
+The list of messages is available in the file hicn.api (located in
+`hicn/hicn-plugin/src/`).
-### Example: consumer and producer Ping
+### Example: consumer and producer ping
-In this example, we connect two vpp forwarders, A and B, each of them running the hicn plugin. On top of forwarder A we run the ping_client application, on top of forwarder B we run the ping_server application. Each application connects to the underlying forwarder through a memif-interface. The two forwarders are connected through a dpdk link.
+In this example, we connect two vpp forwarders, A and B, each of them running
+the hicn plugin. On top of forwarder A we run the `ping_client` application,
+on top of forwarder B we run the `ping_server` application. Each application
+connects to the underlying forwarder through a memif-interface. The two
+forwarders are connected through a dpdk link.
-#### Forwarder A
+#### Forwarder A (client)
-```shell
-$ sudo vppctl
+```bash
+sudo vppctl
vpp# set interface ip address TenGigabitEtherneta/0/0 2001::2/64
vpp# set interface state TenGigabitEtherneta/0/0 up
vpp# hicn control start
@@ -327,24 +347,25 @@ vpp# hicn fib add prefix b002::1/64 face 0
vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/0 type ip
```
-#### Forwarder B
+#### Forwarder B (server)
-```shell
-$ sudo vppctl
+```bash
+sudo vppctl
vpp# set interface ip address TenGigabitEtherneta/0/1 2001::3/64
vpp# set interface state TenGigabitEtherneta/0/1 up
vpp# hicn control start
vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/1 type ip
```
-Once the two forwarder are started, run the ping_server application on the host where the forwarder B is running
+Once the two forwarder are started, run the `ping_server` application on the
+host where the forwarder B is running:
-```shell
+```bash
sudo ping_server -n b002::1
```
-and the client on the host where forwarder B is running
+Then `ping_client` on the host where forwarder B is running:
-```shell
+```bash
sudo ping_client -n b002::1
```