From 56e29ea01914681f394e3a0af4169936079858a7 Mon Sep 17 00:00:00 2001 From: Luca Muscariello Date: Wed, 12 Feb 2020 13:49:52 +0100 Subject: [HICN-512] documentation bundle using sphinx Change-Id: I1dcbca50f7406ef2714683547b6bb32463e1baf8 Signed-off-by: Luca Muscariello --- hicn-light/README.md | 299 --------------------------------------------------- 1 file changed, 299 deletions(-) delete mode 100644 hicn-light/README.md (limited to 'hicn-light') diff --git a/hicn-light/README.md b/hicn-light/README.md deleted file mode 100644 index f18de0df5..000000000 --- a/hicn-light/README.md +++ /dev/null @@ -1,299 +0,0 @@ -# hicn-light - -## 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 for local in-bound connections ---daemon = start as daemon process ---capacity = maximum number of content objects to cache. To disable the cache - objectStoreSize must be 0. - Default vaule for objectStoreSize is 100000 ---log = 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 = file to write log messages to (required in daemon mode) ---config = 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 - - :User defined name for listener, must start with alpha and bealphanum - :tcp | udp - :IPv4 or IPv6 address - :TCP/UDP port - -``` - -`add listener hicn`: creates a hicn listener with the specified options on the local forwarder. - -``` -add listener hicn - - :User defined name for listener, must start with alpha and be alphanum - :IPv4 or IPv6 address - -``` - -`add connection`: creates a TCP or UDP connection on the local forwarder with the specified options. - -``` -add connection - - : tcp | udp - : symbolic name, e.g. 'conn1' (must be unique, start with alpha) - : the IPv4 or IPv6 of the remote system - : the remote TCP/UDP port - : local IP address to bind to - : local TCP/UDP port - -``` -`add connection hicn`: creates an hicn connection on the local forwarder with the specified options. - -``` -add connection hicn - - : symbolic name, e.g. 'conn1' (must be unique, start with alpha) - : the IPv4 or IPv6 of the remote system - : local IP address to bind to - -``` -`list`: lists the connections, routes or listeners available on the local hicn-light forwarder -``` -list - -``` -`add route`: adds a route to the specified connection - -``` -add route - - :The symbolic name for an exgress (must be unique, start with alpha) - : :The egress connection id (see 'help list connections') - : :ipAddress/netmask - : :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 - - : tcp | upd. This is the protocol used to create the connection. - :The symbolic name for an exgress (must be unique, start with alpha) - : :The egress connection id (see 'help list connections') - -``` - -`remove route`: remove the specified prefix for a local connection - -``` -remove route - - : the alphanumeric name of a local connection - : the prefix (ipAddress/netmask) to remove -``` - -`cache serve`: enables/disables replies from local content store (if available) - -``` -cache serve -``` -`cache store`: enables/disables the storage of incoming data packets in the local content store -(if available) - -``` -cache store - -``` -`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 - - : the prefix to which apply the forwarding 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 - - :The symbolic name for an exgress (must be unique, start with alpha) - : :The egress connection id (see 'help list connections') - -``` -`add punting`: Add punting rules to the forwarders. - -``` -add punting - - : listener symbolic name -
: prefix to add as a punting rule. (example 1234::0/64) -``` -`mapme enable`: enables/disables mapme - -``` -mapme enable -``` -`mapme discovery`: enables/disables mapme discovery - -``` -mapme discovery -``` - -`mapme timescale`: set the timescale value expressed in millisencods - -``` -mapme timescale -``` -`mapme retx`: set the retrasmission time value expressed in millisecond - -``` -mapme retx -``` -`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. -``` -- cgit 1.2.3-korg