aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/hicn-light.md
diff options
context:
space:
mode:
authorMauro Sardara <msardara@cisco.com>2020-02-12 17:03:47 +0000
committerGerrit Code Review <gerrit@fd.io>2020-02-12 17:03:47 +0000
commitf9243a2bf823086404be1c41c7bcc1b27cfab7de (patch)
tree83d34905027616eea2d7cf01d42c0f7769a96589 /docs/source/hicn-light.md
parent38cc8fb5b1c4d315648a5cc53bb0e874d54f436a (diff)
parent56e29ea01914681f394e3a0af4169936079858a7 (diff)
Merge "[HICN-512] documentation bundle using sphinx"
Diffstat (limited to 'docs/source/hicn-light.md')
-rw-r--r--docs/source/hicn-light.md300
1 files changed, 300 insertions, 0 deletions
diff --git a/docs/source/hicn-light.md b/docs/source/hicn-light.md
new file mode 100644
index 000000000..e321b78e5
--- /dev/null
+++ b/docs/source/hicn-light.md
@@ -0,0 +1,300 @@
+The Hybrid ICN Portable Forwarder
+==============================
+
+## Introduction
+
+hicn-light is a socket based forwarder
+
+## Using hicn-light
+
+### Platforms
+
+hicn-light has been tested in:
+
+- Ubuntu 16.04 / 18.04 (x86_64)
+- Debian Testing
+- Centos 7
+- MacOSX 10.12
+- Android
+- iOS
+
+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
+- 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.
+- low_latency: uses the face with the lowest latency. In case more faces have similar latency the strategy uses them in parallel
+
+```
+set strategy <prefix> <strategy>
+
+ <preifx> : the prefix to which apply the forwarding strategy
+ <strategy> : random | loadbalancer | low_latency
+```
+`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 192.168.0.1 9199
+
+#create a connection with a remote hicn-light-daemon, with a listener on 192.168.0.20 12345
+add connection udp conn0 192.168.0.20 12345 192.168.0.1 9199
+
+#add a route toward the remote node
+add route conn0 c001::/64 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.
+```