[HICN-531] update documentation with fixes and new content

Change-Id: I4d75f559875fbaae3a63ed20835461b3d18691fb
Signed-off-by: Luca Muscariello <muscariello@ieee.org>

6 files changed, 120 insertions, 102 deletions

diff --git a/docs/README.md b/docs/README.md
index d7a6c6cc8..be7f4e6df 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -26,7 +26,7 @@ $ source env/bin/activate
 $ pip install -r docs/etc/requirements.txt
 $ cd docs
 
-Which installs all the required applications into it's own, isolated,
+Which installs all the required applications into its own, isolated,
 virtual environment, so as to not interfere with other builds that may
 use different versions of software.
 
diff --git a/docs/source/apps.md b/docs/source/apps.md
index 1c44a8ca9..0a1d6eb20 100644
--- a/docs/source/apps.md
+++ b/docs/source/apps.md
@@ -3,7 +3,7 @@
 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 succesfully used to serve HTTP, RTP and
+hICN sockets have been successfully used to serve HTTP, RTP and
 RSockets application protocols.
 
 ## Dependencies
@@ -94,7 +94,7 @@ For running the hicn-plugin at the server there are two main alternatives:
 - Use a docker container
 - Run the hicn-plugin directly in a VM or Bare Metal Server
 
-### Docker
+### Docker VPP hICN proxy
 
 Install docker in the server VM:
 
@@ -102,86 +102,77 @@ Install docker in the server VM:
 server$ curl get.docker.com | bash
 ```
 
-Run the hicn-http-proxy container. Here we use a public server "example.com" as origin:
+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
-server$ docker run -e ORIGIN_ADDRESS=example.com    \
-             -e ORIGIN_PORT=80                      \
-             -e CACHE_SIZE=10000                    \
-             -e HICN_MTU=1200                       \
-             -e FIRST_IPV6_WORD=c001                \
-             -e HICN_PREFIX=http://webserver        \
-             --privileged                           \
-             --name vhttpproxy                      \
-             -d icnteam/vhttpproxy
+#!/bin/bash
+
+#Http proxy options
+ORIGIN_ADDRESS=${ORIGIN_ADDRESS:-"localhost"}
+ORIGIN_PORT=${ORIGIN_PORT:-"80"}
+CACHE_SIZE=${CACHE_SIZE:-"10000"}
+DEFAULT_CONTENT_LIFETIME=${DEFAULT_CONTENT_LIFETIME:-"7200"}
+HICN_MTU=${HICN_MTU:-"1300"}
+FIRST_IPV6_WORD=${FIRST_IPV6_WORD:-"b001"}
+USE_MANIFEST=${USE_MANIFEST:-"true"}
+HICN_PREFIX=${HICN_PREFIX:-"http://webserver"}
+
+# UDP Punting
+HICN_LISTENER_PORT=${HICN_LISTENER_PORT:-33567}
+TAP_ADDRESS_VPP=192.168.0.2
+TAP_ADDRESS_KER=192.168.0.1
+TAP_ADDRESS_NET=192.168.0.0/24
+TAP_ID=0
+TAP_NAME=tap${TAP_ID}
+
+vppctl create tap id ${TAP_ID}
+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
+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
+iptables -t nat -A POSTROUTING -j MASQUERADE --src ${TAP_ADDRESS_NET} ! \
+                                 --dst ${TAP_ADDRESS_NET} -o eth0
+# Add default route to vpp
+vppctl ip route add 0.0.0.0/0 via ${TAP_ADDRESS_KER} ${TAP_NAME}
+# Set UDP punting
+vppctl hicn punting add prefix ${FIRST_IPV6_WORD}::/16 intfc ${TAP_NAME}\
+                                type udp4 dst_port ${HICN_LISTENER_PORT}
+
+# Run the http proxy
+PARAMS="-a ${ORIGIN_ADDRESS} "
+PARAMS+="-p ${ORIGIN_PORT} "
+PARAMS+="-c ${CACHE_SIZE} "
+PARAMS+="-m ${HICN_MTU} "
+PARAMS+="-P ${FIRST_IPV6_WORD} "
+PARAMS+="-l ${DEFAULT_CONTENT_LIFETIME} "
+if [ "${USE_MANIFEST}" = "true" ]; then
+  PARAMS+="-M "
+fi
+
+hicn-http-proxy ${PARAMS} ${HICN_PREFIX}
 ```
 
-Create a hicn private network:
+Docker images of the example above are available at
+<https://hub.docker.com/r/icnteam/vhttpproxy>.
+Images can be pulled using the following tags.
 
-```bash
-server$ GATEWAY=192.168.0.254
-server$ docker network create --subnet 192.168.0.0/24 --gateway ${GATEWAY} hicn-network
-```
-
-Connect the proxy container to the hicn network:
-
-```bash
-server$ docker network connect hicn-network vhttpproxy
+```shell
+docker pull icnteam/vhttpproxy:amd64
+docker pull icnteam/vhttpproxy:arm64
 ```
 
-Connect the hicn network to the vpp forwarder:
-
-```bash
-server$ IP_ADDRESS=$(docker inspect -f "{{with index .NetworkSettings.Networks \"hicn-network\"}}{{.IPAddress}}{{end}}" vhttpproxy)
-server$ INTERFACE=$(docker exec -it vhttpproxy ifconfig | grep -B 1 ${IP_ADDRESS} | awk 'NR==1 {gsub(":","",$1); print $1}')
-server$ docker exec -it vhttpproxy ip addr flush dev ${INTERFACE}
-server$ docker exec -it vhttpproxy ethtool -K ${INTERFACE} tx off rx off ufo off gso off gro off tso off
-server$ docker exec -it vhttpproxy vppctl create host-interface name ${INTERFACE}
-server$ docker exec -it vhttpproxy vppctl set interface state host-${INTERFACE} up
-server$ docker exec -it vhttpproxy vppctl set interface ip address host-${INTERFACE} ${IP_ADDRESS}/24
-server$ docker exec -it vhttpproxy vppctl ip route add 10.0.0.0/24 via ${GATEWAY} host-eth1
-```
-
-Set the punting:
-
-```bash
-server$ PORT=12345
-server$ docker exec -it vhttpproxy vppctl hicn punting add prefix c001::/16 intfc host-${INTERFACE} type udp4 src_port ${PORT} dst_port ${PORT}
-```
-
-Docker containers are cool, but sometimes they do not allow you to do simple operations like expose ports while the container is already running. But we have a workaround for this :)
-
-```bash
-server$ sudo iptables -t nat -A DOCKER -p udp --dport ${PORT} -j DNAT --to-destination ${IP_ADDRESS}:${PORT}
-server$ sudo iptables -t nat -A POSTROUTING -j MASQUERADE -p udp --source ${IP_ADDRESS} --destination ${IP_ADDRESS} --dport ${PORT}
-server$ sudo iptables -A DOCKER -j ACCEPT -p udp --destination ${IP_ADDRESS} --dport ${PORT}
-```
-
-In the client, install the hicn stack:
-
-```bash
-client$ sudo apt-get install -y hicn-light hicn-apps
-```
-
-Create a configuration file for the hicn-light forwarder. Here we are configuring UDP faces:
-
-```bash
-client$ mkdir -p ${HOME}/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 > ${HOME}/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 c001::/16 1
-EOF
-```
+#### Client side
 
 Run the hicn-light forwarder
 
 ```bash
-client$ sudo /usr/bin/hicn-light-daemon --daemon --capacity 1000 --log-file ${HOME}/hicn-light.log --config ${HOME}/etc/hicn-light.conf
+client$ sudo /usr/bin/hicn-light-daemon --daemon --capacity 1000 --log-file \
+                   ${HOME}/hicn-light.log --config ${HOME}/etc/hicn-light.conf
 ```
 
 Run the http client [higet](#higet) and print the http response on stdout:
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 17aeb3a1c..99ea39afa 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,6 +1,16 @@
 Hybrid Information-Centric Networking
 =====================================
 
+Hybrid Information-Centric Networking (hICN) is a network architecture that makes
+use of IPv6 or IPv4 to realize location-independent communications. It is largely
+inspired by the pioneer work of Van Jacobson on Content-Centric Networking, that was
+a clean-slate architecture whereas hICN is based on the Internet protocol and easy to
+deploy in today networks and applications. hICN brings many-to-many communications,
+multi-homing, multi-path, multi-source, group communications to the Internet protocol
+without replicated unicast. The project implements novel transport protocols, with a socket API,
+for real-time and capacity seeking applications. A scalable stack is available based
+on VPP and a client stack is provided to support any mobile and desktop operating system.
+
 .. toctree::
 
    started
diff --git a/docs/source/interface.md b/docs/source/interface.md
index 13f1007a3..9e6b6f383 100644
--- a/docs/source/interface.md
+++ b/docs/source/interface.md
@@ -38,7 +38,7 @@ interfaces:
     protocol to discover a remote hICN forwarder that might be needed to
     establish overlay faces.
 
-- network\_framework [MacOS, iOS]
+- network_framework [MacOS, iOS]
 
     This component uses the recommended Network framework on Apple devices,
     which provided all required information to query faces in a unified API:
@@ -82,11 +82,11 @@ The face manager source code includes a template that can be used as a skeleton
 to develop new faces. It can be found in `src/interface/dummy/dummy.{h,c}`. Both
 include guard and specific interface functions are prefixed by a (short)
 identifier which acts as a namespace for interface specific code (in our case
-the string 'dummy\_').
+the string 'dummy_').
 
-Registration and instanciation of the different interfaces is currently done at
+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 avaialble in the code between `#if 0/#endif` tags.
+interface are available in the code between `#if 0/#endif` tags.
 
 #### Interface template header; configuration parameters
 
@@ -96,7 +96,7 @@ the interface, if any.
 
 In the template, these configuration options are empty:
 
-```C#
+```C
 /*
  * Configuration data
  */
@@ -124,7 +124,7 @@ interface.
 Each interface can hold a pointer to an internal data structure, which is
 declared as follows:
 
-```C#
+```C
 /*
  * Internal data
  */
@@ -142,7 +142,7 @@ typedef struct {
 ```
 
 We find here a copy of the configuration settings (which allows the called to
-instanciate the structure on the stack), as well as a file descriptor
+instantiate the structure on the stack), as well as a file descriptor
 (assuming most interfaces will react on events on a file descriptor).
 
 The rest of the file consists in the implementation of the interface, in
@@ -150,8 +150,8 @@ particular the different function required by the registration of a new
 interface to the system. They are grouped as part of the `interface_ops_t` data
 structure declared at the end of the file:
 
-```C#
-interface\_ops\_t dummy\_ops = {
+```C
+interface_ops_t dummy_ops = {
     .type = "dummy",
     .initialize = dummy_initialize,
     .finalize = dummy_finalize,
@@ -170,14 +170,14 @@ typedef struct {
     /** The type given to the interfaces */
     char * type;
     /* Constructor */
-    int (*initialize)(struct interface\_s * interface, void * cfg);
+    int (*initialize)(struct interface_s * interface, void * cfg);
     /* Destructor */
     int (*finalize)(struct interface_s * interface);
     /* Callback upon file descriptor event (iif previously registered) */
     int (*callback)(struct interface_s * interface);
     /* Callback upon facelet events coming from the face manager */
     int (*on_event)(struct interface_s * interface, const struct facelet_s * facelet);
-} interface\_ops\_t;
+} interface_ops_t;
 ```
 
 Such an interface has to be registered first, then one (or multiple) instance(s)
@@ -196,9 +196,9 @@ if (rc < 0)
     goto ERR_REGISTER;
 ```
 
-- interface instanciation:
+- interface instantiation:
 
-```C++
+```C
 #include "interfaces/dummy/dummy.h"
 
 /* [...] */
@@ -219,7 +219,7 @@ In the template, the constructor is the most involved as it need to:
 
 - initialize the internal data structure:
 
-```C#
+```C
     dummy_data_t * data = malloc(sizeof(dummy_data_t));
     if (!data)
         goto ERR_MALLOC;
@@ -228,7 +228,7 @@ In the template, the constructor is the most involved as it need to:
 
 - process configuration parameters, eventually setting some default values:
 
-```C#
+```C
     /* Use default values for unspecified configuration parameters */
     if (cfg) {
         data->cfg = *(dummy_cfg_t *)cfg;
@@ -246,7 +246,7 @@ event loop for read events. A return value of 0 means the interface does not
 require any file descriptor. As usual, a negative return value indicates an
 error.
 
-```C#
+```C
     data->fd = 0;
 
     /* ... */
@@ -273,14 +273,14 @@ In order to retrieve the internal data structure, that should in particular
 store such a file descriptor, all other function but the constructor can
 dereference it from the interface pointer they receive as parameter:
 
-```C++
-dummy\_data\_t * data = (dummy\_data\_t*)interface->data;
+```C
+dummy_data_t * data = (dummy_data_t*)interface->data;
 ```
 
 #### 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 describe above to read
+function. It can then use the facelet API we have described above to read
 information about the face.
 
 As this information is declared const, the interface can either create a new
@@ -290,7 +290,7 @@ clone it.
 The facelet event can then be defined and raised to the face maanger for further
 processing through the following code:
 
-```C++
+```C
     facelet_set_event(facelet, EVENT_TYPE_CREATE);
     interface_raise_event(interface, facelet);
 ```
@@ -361,5 +361,5 @@ An example illustrating how to connect to the dummy service from `updownsrv` is
 provided as the `updown` interface in the facemgr source code.
 
 This interface periodically swaps the status of the LTE interface up and down.
-It is instanciated as part of the facemgr codebase when the code is compiled
+It is instantiated as part of the facemgr codebase when the code is compiled
 with the ``-DWITH_EXAMPLE_UPDOWN` cmake option.
diff --git a/docs/source/started.md b/docs/source/started.md
index 168ce1272..3c5181297 100644
--- a/docs/source/started.md
+++ b/docs/source/started.md
@@ -90,13 +90,30 @@ 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
+docker pull icnteam/vswitch:amd64
+docker pull icnteam/vswitch:arm64
+
+docker pull icnteam/vserver:amd64
+docker pull icnteam/vserver:arm64
+
+docker pull icnteam/vhttpproxy:amd64
+docker pull icnteam/vhttpproxy:arm64
+```
 
 ### Vagrant
 
-Vagrant boxes for a virtual switch are available at <https://app.vagrantup.com/icnteam/boxes/vswitch>.
-Supported providers are kvm, vmware and virtualbox.
+Vagrant boxes for a virtual switch are available at
+<https://app.vagrantup.com/icnteam>
+
+```shell
+vagrant box add icnteam/vswitch
+```
+Supported providers are libvirt, vmware and virtualbox.
 
 ## License
 
diff --git a/docs/source/telemetry.md b/docs/source/telemetry.md
index 0af3b0e02..868958f2b 100644
--- a/docs/source/telemetry.md
+++ b/docs/source/telemetry.md
@@ -27,9 +27,9 @@ $ make
 $ sudo make install
 ```
 
-## Using hICN collectd plugins ##
+## Using hICN collectd plugins
 
-### Platforms ###
+### Platforms
 
 hICN collectd plugins have been tested in:
 
@@ -40,7 +40,7 @@ hICN collectd plugins have been tested in:
 - CentOS 7
 
 
-### Dependencies ###
+### Dependencies
 
 Build dependencies:
 
@@ -51,7 +51,7 @@ Build dependencies:
   - vpp-dev
   - hicn-plugin-dev
 
-## Getting started ##
+## 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:
@@ -67,7 +67,7 @@ Before running collectd, a vpp forwarder must be started. If the vpp-hicn plugin
 
 Edit the configuration file as the following:
 
-```
+```html
 ######################################################################
 # Global                                                             #
 ######################################################################