From 861c1ba313e000f91b8dca188c69af1b44f3806f Mon Sep 17 00:00:00 2001 From: Mauro Sardara Date: Mon, 24 Jun 2019 17:48:14 +0200 Subject: [HICN-223] Utils tutorial Change-Id: Icfa91c6f939d073c358c146cd0cf2ab13733c603 Signed-off-by: Mauro Sardara --- hicn-light/README.md | 41 ++++----- utils/README.md | 234 ++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 232 insertions(+), 43 deletions(-) diff --git a/hicn-light/README.md b/hicn-light/README.md index 974cad1fe..559659dd1 100644 --- a/hicn-light/README.md +++ b/hicn-light/README.md @@ -1,23 +1,25 @@ -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: @@ -28,10 +30,10 @@ Basic 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 @@ -41,7 +43,7 @@ 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: @@ -73,7 +75,7 @@ If no configuration file is specified, hicn-light-daemon will listen on TCP and 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: @@ -86,7 +88,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 @@ -263,7 +265,7 @@ mapme retx ``` `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 @@ -271,17 +273,16 @@ the command `hicn-light-daemon --config configFile.cfg`, assuming the file name ``` #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: diff --git a/utils/README.md b/utils/README.md index 73525c6c2..0d81ea426 100644 --- a/utils/README.md +++ b/utils/README.md @@ -1,23 +1,23 @@ -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: @@ -26,16 +26,17 @@ 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: @@ -55,9 +56,12 @@ 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: @@ -80,11 +84,14 @@ 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] @@ -103,9 +110,9 @@ Server specific: -k = path of p12 file containing the crypto material used for signing the packets -y = use the selected hash algorithm for calculating manifest digests -p = password for p12 keystore --x = produce a content of , then after downloading it produce a new content of +-x = produce a content of , then after downloading it produces a new content of without resetting the suffix to 0 --B = bitrate for RTC producer, to be used with the -R option +-B = bitrate for RTC producer, to be used with the -R option, in kbps (example: 64kbps) Client specific: -b = RAAQM beta parameter @@ -115,9 +122,190 @@ Client specific: -c = path of the producer certificate to be used for verifying the origin of the packets received -i = show the statistics every 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: -- cgit 1.2.3-korg