aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/utils.md
blob: 5b9178b56627a40b445f3f803a06b1c94035e2b0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
# Utility applications

## Introduction

hicn-ping-server, hicn-ping-client and hiperf are three utility applications for testing and benchmarking stack.

## Using hICN Utils applications

### 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:

```shell
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:

```shell
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:

```shell
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

```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

```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
```