aboutsummaryrefslogtreecommitdiffstats
path: root/hicn-light/README.md
blob: 974cad1fe10191312ad8ecfdbf87f730ea1a6009 (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
296
297
298
299
300
301
hicn-light
=======

## Introduction ##

hicn-light is a socket based forwarder

## Using hicn-light ##

### Platforms ###

hicn-light has been tested in:

- Ubuntu 16.04 (x86_64)
- Debian Testing
- MacOSX 10.12

Other platforms and architectures may work.

### Dependencies ###

Build dependencies:

- c99 ( clang / gcc )
- CMake 3.4

Basic dependencies:

- OpenSSL
- pthreads
- Libevent
- Libparc

## hicn-light Executables ##

hicn-light is a set of binary executables that are used to run a forwarder instance.
The forwarder can be run and configured using the commands

- `hicn-light-daemon`
- `hicn-light-control`

Use the `-h` option to display the help messages

### hicn-light Daemon ###

The command `hicn-light-daemon` runs the hicn-light forwarder. The forwarder can be executed
with the following options:

```
hicn-light-daemon [--port port] [--daemon] [--capacity objectStoreSize] [--log facility=level]
                [--log-file filename] [--config file]

Options:
--port <tcp_port>           = tcp port for local in-bound connections
--daemon                    = start as daemon process
--capacity <capacity>       = maximum number of content objects to cache. To disable the cache
                              objectStoreSize must be 0.
                              Default vaule for objectStoreSize is 100000
--log <log_granularity>     = sets a facility to a given log level. You can have multiple of these.
                              facilities: all, config, core, io, message, processor
                              levels: debug, info, notice, warning, error, critical, alert, off
                              example: hicn-light-daemon --log io=debug --log core=off
--log-file <output_logfile> = file to write log messages to (required in daemon mode)
--config <config_path>      = configuration filename
```

The configuration file contains configuration lines as per hicn-light-control (see below for all
the available commands). If logging level or content store capacity is set in the configuration
file, it overrides the command_line. When a configuration file is specified, no default listeners
are setup.  Only 'add listener' lines in the configuration file matter.

If no configuration file is specified, hicn-light-daemon will listen on TCP and UDP ports specified
by the --port flag (or default port).  It will listen on both IPv4 and IPv6 if available. The
default port for hicn-light is 9695. Commands are expected on port 2001.

### hicn-light-control ###

`hicn-light-control` can be used to send command to the hicn-light forwarder and configure it.
The command can be executed in the following way:

```
hicn-light-control [commands]

Options:
    -h                    = This help screen
    commands              = configuration line to send to hicn-light (use 'help' for list)
```

#### Available Commands in hicn-light-control ####

This is the full list of available commands in `hicn-light-control`. This commands can be used
from the command line running `hicn-light-control` as explained before, or listing them in a
configuration file.

Information about the commands are also available in the `hicn-light-control` help message.

`add listener`: creates a TCP or UDP listener with the specified options on the local forwarder.
For local connections (application to hicn-light) we expect a TCP listener. The default port for
the local listener is 9695.

```
add listener <protocol> <symbolic> <local_adress> <local_port>

  <symbolic>        :User defined name for listener, must start with alpha and bealphanum
  <protocol>        :tcp | udp
  <localAddress>    :IPv4 or IPv6 address
  <local_port>      :TCP/UDP port

```

`add listener hicn`: creates a hicn listener with the specified options on the local forwarder.

```
add listener hicn <symbolic> <local_adress>

  <symbolic>        :User defined name for listener, must start with alpha and be alphanum
  <localAddress>    :IPv4 or IPv6 address

```

`add connection`: creates a TCP or UDP connection on the local forwarder with the specified options.

```
add connection <protocol> <symbolic> <remote_ip> <remote_port> <local_ip> <local_port>

  <protocol>              : tcp | udp
  <symbolic>              : symbolic name, e.g. 'conn1' (must be unique, start with alpha)
  <remote_ip>             : the IPv4 or IPv6 of the remote system
  <remote_port>           : the remote TCP/UDP port
  <local_ip>              : local IP address to bind to
  <local_port>            : local TCP/UDP port

```
`add connection hicn`: creates an hicn connection on the local forwarder with the specified options.

```
add connection hicn <symbolic> <remote_ip> <local_ip>

  <symbolic>            : symbolic name, e.g. 'conn1' (must be unique, start with alpha)
  <remote_ip>           : the IPv4 or IPv6 of the remote system
  <local_ip>            : local IP address to bind to

```
`list`: lists the connections, routes or listeners available on the local hicn-light forwarder
```
list <connections | routes | listeners>

```
`add route`: adds a route to the specified connection

```
add route <symbolic | connid> <prefix> <cost>

  <symbolic>   :The symbolic name for an exgress (must be unique, start with alpha)
  <connid>:    :The egress connection id (see 'help list connections')
  <prefix>:    :ipAddress/netmask
  <cost>:      :positive integer representing cost
```

`remove connection`: removes the specified connection. At the moment, this commands is available
only for UDP connections, TCP is ignored.

```
remove connection <protocol> <symbolic | connid>

  <protocol>   : tcp | upd. This is the protocol used to create the connection.
  <symbolic>   :The symbolic name for an exgress (must be unique, start with alpha)
  <connid>:    :The egress connection id (see 'help list connections')

```

`remove route`: remove the specified prefix for a local connection

```
remove route <symbolic | connid> <prefix>

  <connid>    : the alphanumeric name of a local connection
  <prefix>    : the prefix (ipAddress/netmask) to remove
```

`cache serve`: enables/disables replies from local content store (if available)

```
cache serve <on|off>
```
`cache store`:  enables/disables the storage of incoming data packets in the local content store
(if available)

```
cache store <on|off>

```
`cache clear`: removes all the cached data form the local content store (if available)

```
cache clear

```
`set strategy`: sets the forwarding strategy for a give prefix. There are 4 different strategies
implemented in hicn-light:

- random: each interest is forwarded randomly to one of the available output connections
- random_per_dash_segment: the output connection is selected randomly for each DASH segment.
  This can be used only for DASH video streams.
- loadbalancer: each interest is forwarded toward the output connection with the lowest number
  of pending interests. The pending interest are the interest sent on a certain connection but
  not yet satisfied. More information are available in: 
  G. Carofiglio, M. Gallo, L. Muscariello, M. Papalini, S. Wang, 
  "Optimal multipath congestion control and request forwarding in information-centric networks", 
  ICNP 2013.
- loadbalancer_with_delay: implements the same strategy as loadbalancer but it takes into account
  also the propagation delay behind each connections.

```
set strategy <prefix> <strategy>

  <preifx>    : the prefix to which apply the forwarding strategy
  <strategy>  : random | random_per_dash_segment | loadbalancer | loadbalancer_with_delay
```
`set wldr`: turns on/off WLDR on the specified connection. WLDR (Wireless Loss Detiection and
 Recovery) is a protocol that can be used to recover losses generated by unreliable wireless 
 connections, such as WIFI. More information on WLDR are available in: 
 G. Carofiglio, L. Muscariello, M. Papalini, N. Rozhnova, X. Zeng, 
 "Leveraging ICN In-network Control for Loss Detection and Recovery in Wireless Mobile networks", 
 ICN 2016. Notice that WLDR is currently available only for UDP connections. In order to work
 properly, WLDR needs to be activated on both side of the connection.

```
set wldr <on|off> <symbolic | connid>

  <symbolic>   :The symbolic name for an exgress (must be unique, start with alpha)
  <connid>:    :The egress connection id (see 'help list connections')

```
`add punting`: Add punting rules to the forwarders.

```
add punting <symbolic> <prefix>

 <symbolic> : listener symbolic name
 <address>  : prefix to add as a punting rule. (example 1234::0/64)
```
`mapme enable`: enables/disables mapme

```
mapme enable <on|off>
```
`mapme discovery`: enables/disables mapme discovery

```
mapme discovery <on|off>
```

`mapme timescale`: set the timescale value expressed in millisencods

```
mapme timescale <milliseconds>
```
`mapme retx`: set the retrasmission time value expressed in millisecond

```
mapme retx <milliseconds>
```
`quit`: Exits the interactive shell

### hicn-light Configuration File Example ###

This is an example of a simple configuration file for hicn-light. It can be loaded by running
the command `hicn-light-daemon --config configFile.cfg`, assuming the file name is configFile.cfg

```
#create a local listener on port 9199. This will be used by the applications to talk
with the forwarder
add listener udp local0 127.0.0.1 9199

#create a connection with a remote node
add connection udp conn0 192.168.0.20 12345 127.0.0.1 9199

#add a route toward the remote node
add route conn0 192.168.0.20/24 1
```


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