diff options
Diffstat (limited to 'docs/source/hicn-light.md')
| -rw-r--r-- | docs/source/hicn-light.md | 300 |
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. +``` |