[HICN-533] Update and format documentation

This patch fixes misspells, improves readability and tries to make the different
source files consistent between each other.

It also updates hiperf usage and hicn + VPP installation (in utils.md) and fixes
some mistakes related to collectd plugins (in telemetry.md).

Change-Id: I100a1c7e40dbe9c485ae4548ffc653765f4421b9
Signed-off-by: Olivier Roques <oroques+fdio@cisco.com>

1 files changed, 120 insertions, 91 deletions

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: