-hicn-light
-=======
+# hicn-light
-## Introduction ##
+## Introduction
hicn-light is a socket based forwarder
-## Using hicn-light ##
+## Using hicn-light
-### Platforms ###
+### Platforms
hicn-light has been tested in:
-- Ubuntu 16.04 (x86_64)
+- Ubuntu 16.04 / 18.04 (x86_64)
- Debian Testing
+- Centos 7
- MacOSX 10.12
+- Android
+- iOS
Other platforms and architectures may work.
-### Dependencies ###
+### Dependencies
Build dependencies:
- OpenSSL
- pthreads
-- Libevent
-- Libparc
+- 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
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:
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.
-### hicn-light-control ###
+### hicn-light-control
`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:
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
```
`quit`: Exits the interactive shell
-### 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
```
#create a local listener on port 9199. This will be used by the applications to talk
with the forwarder
-add listener udp local0 127.0.0.1 9199
+add listener udp local0 192.168.0.1 9199
-#create a connection with a remote node
-add connection udp conn0 192.168.0.20 12345 127.0.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
#add a route toward the remote node
-add route conn0 192.168.0.20/24 1
+add route conn0 c001::/64 1
```
-
-## License ##
+## License
This software is distributed under the following license:
-Utility applications
-==================
+# Utility applications
-## Introduction ##
+## Introduction
-hicn-ping-server, hicn-ping-client and hiperf are three utility applications that use hicn 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
-### Platforms ###
+### Platforms
-The hICN application Examples have been tested in:
+hicn-light has been tested in:
-- Ubuntu 16.04 (x86_64)
+- Ubuntu 16.04 / 18.04 (x86_64)
- Debian Testing
+- Centos 7
- MacOSX 10.12
+- Android
+- iOS
-Other platforms and architectures may work.
-
-### Dependencies ###
+### Dependencies
Build dependencies:
Basic dependencies:
-- OpenSSL
+- ppenSSL
- pthreads
-- Libevent
-- Libparc
+- libevent
+- libparc
+- libhicntransport
-## Executables ##
+## Executables
-The utility applications are a set of binary executables that are used to run a clinet/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 hicn (hiperf).
-### hicn-ping-server ###
+### hicn-ping-server
The command `hicn-ping-server` runs the server side ping application. hicn-ping-server can be executed
with the following options:
-q = quite, not prints (default false)
-d = daemon mode
-H = help
+
+Example:
+hicn-ping-server -n c001::/64
```
-### hicn-ping-client ###
+### hicn-ping-client
The command `hicn-ping-client` runs the client side ping application. hicn-ping-client can be executed
with the following options:
-D = dump, dumps sent and received packets (default false)
-q = quiet, not prints (default false)
-H = help
+
+Example:
+hicn-ping-client -n c001::1
```
-### hiperf ###
+### 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:
```
usage: hiperf [-S|-C] [options] [prefix|name]
-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 produce a new content of
+-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
+-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
-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
+
+Example:
+hiperf -S c001::/64
+```
+
+## How To Benchmark Client-Server Throughput 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.
+
+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.
+
+```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
+```
+
+It should install the hICN suite under hicn-install.
+
+#### hICN stack based on hicn-light forwarder with UDP faces
+
+##### Server Configuration
+
+Create a configuration file for the hicn-light forwarder. Here we are configuring UDP faces.
+
+```bash
+server$ mkdir -p ${HICN_ROOT}/etc
+server$ LOCAL_IP="10.0.0.1" # Put here the actual IPv4 of the local interface
+server$ LOCAL_PORT="12345"
+server$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf
+add listener udp list0 ${LOCAL_IP} ${LOCAL_PORT}
+EOF
+```
+
+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.
+
+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.
+
+##### Client Configuration
+
+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
+client$ LOCAL_IP="10.0.0.2" # Put here the actual IPv4 of the local interface
+client$ LOCAL_PORT="12345"
+client$ REMOTE_IP="10.0.0.1" # Put here the actual IPv4 of the remote interface
+client$ REMOTE_PORT="12345"
+client$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf
+add listener udp list0 ${LOCAL_IP} ${LOCAL_PORT}
+add connection udp conn0 ${REMOTE_IP} ${REMOTE_PORT} ${LOCAL_IP} ${LOCAL_PORT}
+add route conn0 b001::/16 1
+EOF
+```
+
+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
+```
+
+Run the [hiperf](#hiperf) client:
+
+```bash
+client$ ${HICN_ROOT}/bin/hiperf -C b001::1 -W 50
+EOF
+```
+
+This will run the client with a fixed window of 50 interests.
+
+#### Using 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.
+
+##### Server Configuration
+
+```bash
+server$ mkdir -p ${HICN_ROOT}/etc
+server$ LOCAL_IP="9001::1"
+server$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf
+add listener hicn lst 0::0
+add punting lst b001::/16
+add listener hicn list0 ${LOCAL_IP}
+EOF
+```
+
+#### Client Configuration
+
+```bash
+client$ mkdir -p ${HICN_ROOT}/etc
+client$ LOCAL_IP="9001::2"
+client$ REMOTE_IP="9001::1"
+client$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf
+add listener hicn lst 0::0
+add punting lst b001::/16
+add listener hicn list0 ${LOCAL_IP}
+add connection hicn conn0 ${REMOTE_IP} ${LOCAL_IP}
+add route conn0 b001::/16 1
+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.
+
+```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
+```
+
+Make sure vpp is running:
+
+```bash
+$ sudo systemctl restart vpp
+```
+
+Run the hicn-plugin:
+
+```bash
+$ vppctl hicn control start
+```
+
+Run hiperf server:
+
+```bash
+$ hiperf -S b001::/64
+```
+
+Run hiperf client:
+
+```bash
+$ hiperf -C b001::1 -W 300
```
-## License ##
+## License
This software is distributed under the following license:
Code Review / hicn.git / commitdiff