summaryrefslogtreecommitdiffstats
path: root/utils
diff options
context:
space:
mode:
authorLuca Muscariello <muscariello@ieee.org>2020-02-12 13:49:52 +0100
committerLuca Muscariello <muscariello@ieee.org>2020-02-12 17:51:13 +0100
commit56e29ea01914681f394e3a0af4169936079858a7 (patch)
tree2b364c9da3a44637e9e2ba87b7009424ad8b192b /utils
parent202c6bc2788c943b15026c24900c321b9bbeed3c (diff)
[HICN-512] documentation bundle using sphinx
Change-Id: I1dcbca50f7406ef2714683547b6bb32463e1baf8 Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Diffstat (limited to 'utils')
-rw-r--r--utils/README.md325
1 files changed, 0 insertions, 325 deletions
diff --git a/utils/README.md b/utils/README.md
deleted file mode 100644
index 0d81ea426..000000000
--- a/utils/README.md
+++ /dev/null
@@ -1,325 +0,0 @@
-# Utility applications
-
-## Introduction
-
-hicn-ping-server, hicn-ping-client and hiperf are three utility applications for testing and benchmarking stack.
-
-## Using hICN Utils applications
-
-### Platforms
-
-hicn-light has been tested in:
-
-- Ubuntu 16.04 / 18.04 (x86_64)
-- Debian Testing
-- Centos 7
-- MacOSX 10.12
-- Android
-- iOS
-
-### Dependencies
-
-Build dependencies:
-
-- c++14 ( clang++ / g++ )
-- CMake 3.4
-
-Basic dependencies:
-
-- ppenSSL
-- pthreads
-- libevent
-- libparc
-- libhicntransport
-
-## 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).
-
-### hicn-ping-server
-
-The command `hicn-ping-server` runs the server side ping application. hicn-ping-server can be executed
-with the following options:
-
-```
-usage: hicn-ping-server [options]
-
-Options:
--s <content_size> = object content size (default 1350B)
--n <hicn_name> = hicn name (default b001::/64)
--f = set tcp flags according to the flag received (default false)
--l <lifetime> = data lifetime
--r = always reply with a reset flag (default false)
--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)
--d = daemon mode
--H = help
-
-Example:
-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:
-
-```
-usage: hicn-ping-client [options]
-
-Options:
--i <ping_interval> = ping interval in microseconds (default 1000000ms)
--m <max_pings> = maximum number of pings to send (default 10)
--s <source_port> = source port (default 9695)
--d <destination_port> = destination port (default 8080)
--t <ttl> = set packet ttl (default 64)
--O = open tcp connection (three way handshake) (default false)
--S = send always syn messages (default false)
--A = send always ack messages (default false)
--n <hicn_name> = hicn name (default b001::1)
--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)
--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:
-
-```
-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
-
-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
-
-This software is distributed under the following license:
-
-```
-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.
-You may obtain a copy of the License at:
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```