[HICN-223] Apps tutorial.

Change-Id: I5c17f4f72e1929f40f92718c9e479a6141b280f0
Signed-off-by: Mauro Sardara <msardara@cisco.com>

2 files changed, 177 insertions, 56 deletions

diff --git a/README.md b/README.md
index 3b10574e3..5e3ead81b 100644
--- a/README.md
+++ b/README.md
@@ -9,14 +9,14 @@ real-time transport service for audio/video media.
 
 ## Directory layout
 
-| Directory name         | Description                                    |
-| ---------------------- | ---------------------------------------------- |
-|      lib               | Core support library                           |
-|      hicn-plugin       | VPP plugin                                     |
-|      hicn-light        | Lightweight packet forwarder                   |
-|      libtransport      | Support library with transport layer and API   |
-|      utils             | Tools for testing                              |
-|      apps              | Application examples using hicn stack          |
+| Directory name | Description                                  |
+| -------------- | -------------------------------------------- |
+| lib            | Core support library                         |
+| hicn-plugin    | VPP plugin                                   |
+| hicn-light     | Lightweight packet forwarder                 |
+| libtransport   | Support library with transport layer and API |
+| utils          | Tools for testing                            |
+| apps           | Application examples using hicn stack        |
 
 hicn plugin is a VPP plugin that implement hicn packet processing as specified in
 https://datatracker.ietf.org/doc/draft-muscariello-intarea-hicn/. The transport library is used to
diff --git a/apps/README.md b/apps/README.md
index e7f4188bb..bee6545a6 100644
--- a/apps/README.md
+++ b/apps/README.md
@@ -1,70 +1,39 @@
-Application examples using hicn stack
-==================
+# Application examples using hICN stack
 
-## Introduction ##
+## Introduction
 
 higet and hicn-http-proxy are two application examples that use hicn stack.
 
-## Using hICN Application Examples ##
+## Using hICN Application Examples
 
-### Platforms ###
-
-The hICN application Examples have been tested in:
-
-- Ubuntu 16.04 (x86_64)
-- Debian Testing
-- MacOSX 10.12
-
-Other platforms and architectures may work.
-
-### Dependencies ###
+### Dependencies
 
 Build dependencies:
 
 - c++14 ( clang++ / g++ )
-- CMake 3.4
+- CMake 3.5 or higher
 
 Basic dependencies:
 
 - OpenSSL
 - pthreads
-- Libevent
-- Libparc
-- Libcurl
-
-## Executables ##
-
-The application examples are a set of binary executables that are used to run a simple http client (higet) and a hicn-http-proxy (hicn-http-proxy).
-
-### higet ###
-
-The command `higet` runs the higet application. higet can be executed
-with the following options:
+- libevent
+- libparc
+- libcurl
+- libhicntransport
 
-```
-higet [option]... [url]...
-Options:
--O <output_path>            = write documents to <output_file>
--S                          = print server response
-```
+## Executables
 
-### hicn-http-proxy ###
+### 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:
 
-- Receives a HTTP request over hICN
+- Receives a HTTP request from a hICN client
 - Forwards it to a HTTP server over TCP
-- Receives the response from the server and publishes it
-
-Subsequently, other hICN client asking for the same HTTP message can retrieve it directly
-through hICN, by retrieving it either from the forwarder caches or directly from the `hicn-http-proxy`.
+- Receives the response from the server and send it back to the client
 
-The proxy uses hICN names for performing the multiplexing of http requests, allowing a single
-hICN proxy with a single producer socket to serve multiple consumers asking for the same content. Conversely, a normal
-TCP proxy still needs to open one TCP connection per client.
-
-```
+```bash
 hicn-http-proxy [HTTP_PREFIX] [OPTIONS]
 
 HTTP_PREFIX: The prefix used for building the hicn names.
@@ -73,16 +42,168 @@ Options:
 -a <server_address>   = origin server address
 -p <server_port>      = origin server port
 -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:
-./hicn-http-proxy http://webserver -a 127.0.0.1 -p 8080 -c 10000
+./hicn-http-proxy http://webserver -a 127.0.0.1 -p 8080 -c 10000 -m 1200 -P b001
 ```
 
-## License ##
+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:
 
-This software is distributed under the following license:
+- 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.
+
+### higet
 
+Higet is a non-interactive HTTP client working on top oh hICN.
+
+```bash
+higet [option]... [url]
+Options:
+-O <output_path>            = write documents to <output_file>. Use '-' for stdout.
+-S                          = print server response.
+-P                          = optional first 16 bits of hicn prefix, in hexadecimal format
+
+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).
+
+### How To Setup A Simple HTTP Client-Server Scenario using the 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):
+
+```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
+
+Open a new terminal on the machine where you want to run the HTTP server and install apache2 http server:
+
+```bash
+server$ sudo apt-get install -y apache2
+server$ sudo systemctl start apache2
+```
+
+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 1000 --log-file ${HICN_ROOT}/hicn-light.log --config ${HICN_ROOT}/etc/hicn-light.conf
+```
+
+Run the [hicn-http-proxy](#hicn-http-proxy). Assuming the http origin is listening on port 80:
+
+```bash
+server$ ${HICN_ROOT}/bin/hicn-http-proxy -a 127.0.0.1 -p 80 -c 10000 -m 1200 -P c001 http://webserver
+```
+
+##### Client Configuration
+
+Create a configuration file for the hicn-light forwarder. 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 c001::/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 http client [higet](#higet) and print the http response on stdout:
+
+```bash
+client$ ${HICN_ROOT}/bin/higet -O - http://webserver/index.html -P c001
+EOF
+```
+
+#### 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 c001::/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 c001::/16
+add listener hicn list0 ${LOCAL_IP}
+add connection hicn conn0 ${REMOTE_IP} ${LOCAL_IP}
+add route conn0 c001::/16 1
+EOF
+```
+
+## License
+
+This software is distributed under the following license:
+
+```text
 Copyright (c) 2017-2019 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.