diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/etc/requirements.txt | 32 | ||||
| -rw-r--r-- | docs/source/1-architecture.md | 42 | ||||
| -rw-r--r-- | docs/source/apps.md | 1 | ||||
| -rw-r--r-- | docs/source/conf.py | 10 | ||||
| -rw-r--r-- | docs/source/control.md | 332 | ||||
| -rw-r--r-- | docs/source/hicn-light.md | 127 | ||||
| -rw-r--r-- | docs/source/index.rst | 71 | ||||
| -rw-r--r-- | docs/source/interface.md | 33 | ||||
| -rw-r--r-- | docs/source/packethicn.md | 36 | ||||
| -rw-r--r-- | docs/source/started.md | 143 | ||||
| -rw-r--r-- | docs/source/telemetry.md | 25 | ||||
| -rw-r--r-- | docs/source/transport.md | 339 | ||||
| -rw-r--r-- | docs/source/utils.md | 83 | ||||
| -rw-r--r-- | docs/source/vpp-plugin.md | 26 |
14 files changed, 642 insertions, 658 deletions
diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt index 5b037c693..3ce3a7e00 100644 --- a/docs/etc/requirements.txt +++ b/docs/etc/requirements.txt @@ -1,27 +1,5 @@ -alabaster==0.7.12 -Babel==2.8.0 -certifi==2019.11.28 -chardet==3.0.4 -commonmark==0.9.1 -docutils==0.16 -idna==2.8 -imagesize==1.2.0 -Jinja2==2.10.3 -MarkupSafe==1.1.1 -packaging==20.0 -Pygments==2.5.2 -pyparsing==2.4.6 -pytz==2019.3 -recommonmark==0.6.0 -requests==2.22.0 -six==1.14.0 -snowballstemmer==2.0.0 -Sphinx==2.3.1 -sphinx-rtd-theme==0.4.3 -sphinxcontrib-applehelp==1.0.1 -sphinxcontrib-devhelp==1.0.1 -sphinxcontrib-htmlhelp==1.0.2 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==1.0.2 -sphinxcontrib-serializinghtml==1.1.3 -urllib3==1.25.8 +pip-tools==6.5.0 # BSD +sphinx # BSD +sphinx-rtd-theme # MIT +sphinx-markdown-tables # GPLv3 +recommonmark # MIT
\ No newline at end of file diff --git a/docs/source/1-architecture.md b/docs/source/1-architecture.md new file mode 100644 index 000000000..8f3cfc78a --- /dev/null +++ b/docs/source/1-architecture.md @@ -0,0 +1,42 @@ +# Data identifiers and locators + +Hybrid ICN makes use of data identifiers to name the data produced by an end +host. Data identifiers are encoded using a routable name prefix and a non +routable name suffix to provide the ability to index a single IP packet in an +prefix is unambigous manner. A full data name is composed of 160 bits. A +routable name prefix in IPv4 network is 32 bits long while in IPv6 is 128 bits +long. A name prefix is a valid IPv4 or IPv6 address. The 32 rightmost bits are +used by the applications to index data within the same stream. + +A data source that is using the hicn stack is reacheable through IP routing +where a producer socket is listening as the producer name prefix is IP routable. + +Locators are IP interface identifiers and are IPv4 or IPv6 addresses. Data +consumers are reacheable through IP routing over their locators. + +For requests, the name prefix is stored in the destination address field of the +IP header while the source address field stored the locator of the consumer. + + +# Producer/Consumer Architecture +Applications make use of the hicn network architecture by using a Prod/Cons API. +Each communication socket is connection-less as a data producer makes data +available to data consumer by pushing data into a named buffer. Consumers are +responsible for pulling data from data producers by sending requests indexing +the full data name which index a single MTU sized data packet. The core + +# Packet forwarding +Packet forwarding leverages IP routing as requests are forwarded using name +prefixes and replies using locators. + +# Relay nodes +A relay node is implemented by using a packet cache which is used to temporarily +store requests and replies. The relay node acts as a virtual proxy for the data +producers as it caches data packets which can be sent back to data consumer by +using the full name as an index. Requests must be cached and forwarded upstream +towards data producers which will be able reach back the relay nodes by using +the IP locators of the relays. Cached requests store all locators as currently +written in the source address field of the request while requests forwarded +upstream will get the source address rewritten with the relay node locator. Data +packets can reach the original consumers via the relay nodes by using the +requence of cached locators. diff --git a/docs/source/apps.md b/docs/source/apps.md index 64c3d9a68..4131eba82 100644 --- a/docs/source/apps.md +++ b/docs/source/apps.md @@ -18,7 +18,6 @@ Basic dependencies: - OpenSSL - pthreads - libevent -- libparc - libcurl - libhicntransport diff --git a/docs/source/conf.py b/docs/source/conf.py index bb6715564..d00e821ab 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,13 +19,13 @@ # -- Project information ----------------------------------------------------- project = u'Hybrid ICN' -copyright = u'(c) 2017-2020 Cisco and/or its affiliates.' -author = u'Luca Muscariello' +copyright = u'(c) 2018-2022 Cisco and/or its affiliates.' +author = u'HICN Team Members' # The short X.Y version version = u'' # The full version, including alpha/beta/rc tags -release = u'20.01' +release = u'22.02' # -- General configuration --------------------------------------------------- @@ -37,7 +37,7 @@ release = u'20.01' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['recommonmark'] +extensions = ['recommonmark', 'sphinx_markdown_tables'] # Prefix document path to section labels, otherwise autogenerated labels would look like 'heading' # rather than 'path/to/file:heading' @@ -88,7 +88,7 @@ html_theme = "sphinx_rtd_theme" html_static_path = ['_static'] def setup(app): - app.add_stylesheet('css/rules.css') + app.add_css_file('css/rules.css') # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/source/control.md b/docs/source/control.md index 9564a23af..fb6b7faf3 100644 --- a/docs/source/control.md +++ b/docs/source/control.md @@ -1,333 +1,3 @@ # Control plane support -Control plane functionalities are provides via SDN controllers or via standard -IP routing protocols. SDN support is provided by using the NETCONF/YANG protocol -for network management, control and telemetry. - -Routing is supported via synchronization of the IP FIB and the IP RIB as implemented -by one of the routing protocols in FRR. Without loss of generality we have reported -below one example of IGP routing via OSPF for IPv6. - -The VPP IP FIB can be controlled and updated by one FRR routing protocol which -is used for routing over locators and also over hICN name prefixes. - -## NETCONF/YANG - -### Getting started - -NETCONF/YANG support is provided via several external components such as -libyang, sysrepo, libnetconf and netopeer. -The hicn project provides a sysrepo plugin and a YANG model for two devices: -the VPP based hicn virtual switch and the portable forwarder. -The YANG model for the VPP based hICN vSwitch is based the full hICN C API -exported by the VPP plugin with the addition of some VPP APIs such as -interface and FIB management which are required by the hICN plugin. - -To install libyang, sysrepo, libnetconf and netopeer2 for Ubuntu18 amd64/arm64 -or CentOS 7 and ad-hoc repository is available and maintained in bintray -at <https://dl.bintray.com/icn-team/apt-hicn-extras>. - -For instance in Ubuntu 18 LTS: - -Install the sysrepo YANG data store and a NETCONF server: - -```bash -echo "deb [trusted=yes] https://dl.bintray.com/icn-team/apt-hicn-extras bionic main" \ - | tee -a /etc/apt/sources.list -apt-get update && apt-get install -y libyang sysrepo libnetconf2 netopeer2-server -``` - -Install the VPP based hICN virtual switch: - -```bash -curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | bash -apt-get update && apt-get install -y hicn-plugin vpp-plugin-dpdk hicn-sysrepo-plugin -``` - -The hICN YANG models are installed under `/usr/lib/$(uname -m)-linux-gnu/modules_yang`. - -Configure the NETCONF/YANG components: - -```bash -bash /usr/bin/setup.sh sysrepoctl /usr/lib/$(uname -m)-linux-gnu/modules_yang root -bash /usr/bin/merge_hostkey.sh sysrepocfg openssl -bash /usr/bin/merge_config.sh sysrepocfg genkey -``` - -You can manually install the yang model using the following bash script: - -```bash -EXIT_CODE=0 -command -v sysrepoctl > /dev/null -if [ $? != 0 ]; then - echo "Could not find command \"sysrepoctl\"." - exit ${EXIT_CODE} -else -sysrepoctl --install --yang=path_to_hicn_yang_model -fi -``` - -### YANG model - -hicn.yang can be found in the yang-model. It consists of two container nodes: - -```text -|--+ hicn-conf: holds the configuration data; -| |--+ params: contains all configuration parameters; -|--+ hicn-state: provides the state data -| |--+ state, -| |--+ strategy, -| |--+ strategies, -| |--+ route, -| |--+ face-ip-params -and corresponding leaves. -``` - -A controller can configure these parameters through the edit-config RPC -call. This node can be used to enable and to initialize the hicn-plugin in VPP -instance. hicn-state container is used to provide the state data to the -controller. It consists of state, strategy, strategies, route, and face-ip-params -nodes with the corresponding leaves. In the hicn model a variety of RPCs are provided -to allow controller to communicate with the hicn-plugin as well as update the state -data in hicn-state. - -### Example - -To setup the startup configuration you can use the following script: - -```bash -EXIT_CODE=0 -command -v sysrepocfg > /dev/null -if [ $? != 0 ]; then - echo "Could not find command \"sysrepocfg\"." - exit ${EXIT_CODE} -else -sysrepocfg -d startup -i path_to_startup_xml -f xml hicn -fi -``` - -startup.xml is placed in the yang-model. Here you can find the content: - -```xml -<hicn-conf xmlns="urn:sysrepo:hicn"> -<params> - <enable_disable>false</enable_disable> - <pit_max_size>-1</pit_max_size> - <cs_max_size>-1</cs_max_size> - <cs_reserved_app>-1</cs_reserved_app> - <pit_dflt_lifetime_sec>-1</pit_dflt_lifetime_sec> - <pit_max_lifetime_sec>-1</pit_max_lifetime_sec> - <pit_min_lifetime_sec>-1</pit_min_lifetime_sec> -</params> -</hicn-conf> -``` - -It contains the leaves of the parameters in hicn-conf node which is -used as the startup configuration. This configuration can be changed through the -controller by subscribing which changes the target to the running state. hicn -yang model provides a list of RPCs which allows controller to communicate -directly with the hicn-plugin. This RPCs may also cause the modification in -state data. - -In order to run different RPCs from controller you can use the examples in the -controler_rpcs_instances.xml in the yang-model. Here you can find the content: - -```xml -<node-params-get xmlns="urn:sysrepo:hicn"/> - -<node-stat-get xmlns="urn:sysrepo:hicn"/> - -<strategy-get xmlns="urn:sysrepo:hicn"> - <strategy_id>0</strategy_id> -</strategy-get> - -<strategies-get xmlns="urn:sysrepo:hicn"/> - -<route-get xmlns="urn:sysrepo:hicn"> - <prefix0>10</prefix0> - <prefix1>20</prefix1> - <len>30</len> -</route-get> - -<face-params-get xmlns="urn:sysrepo:hicn"> - <faceid>10</faceid> -</face-params-get> - -<hicn-enable xmlns="urn:sysrepo:hicn"> - <prefix>b001::/64</prefix> -</hicn-enable> - -<hicn-disable xmlns="urn:sysrepo:hicn"> - <prefix>b001::/64</prefix> -</hicn-disable> -``` - -#### Run the plugin - -First, verify the plugin and binary libraries are located correctly, then run -the vpp through (service vpp start). Next, run the sysrepo plugin -(sysrepo-plugind), for debug mode: sysrep-plugind -d -v 4 which runs with high -verbosity. Now, the hicn sysrepo plugin is loaded. Then, run the -netopeer2-server which serves as NETCONF server - -#### Connect from netopeer2-cli - -In order to connect through the netopeer client run the netopeer2-cli. Then, -follow these steps: - -- connect --host XXX --login XXX -- get (you can get the configuration and operational data) -- get-config (you can get the configuration data) -- edit-config --target running --config - -With the default netopeer2-server configuration the authentication required by -netopeer2-cli reflects the ssh authentication (username and password or public -key). For other means of authentication please refer to netopeer2-server -documentation (e.g., netopeer2/server/configuration/README.md). - -You can modify the configuration but it needs an xml configuration input. - -```xml -<hicn-conf xmlns="urn:sysrepo:hicn"> -<params> - <enable_disable>false</enable_disable> - <pit_max_size>-1</pit_max_size> - <cs_max_size>-1</cs_max_size> - <cs_reserved_app>-1</cs_reserved_app> - <pit_dflt_lifetime_sec>-1</pit_dflt_lifetime_sec> - <pit_max_lifetime_sec>-1</pit_max_lifetime_sec> - <pit_min_lifetime_sec>-1</pit_min_lifetime_sec> -</params> -</hicn-conf> -``` - -- user-rpc (you can call one of the rpc proposed by hicn model but it needs an xml input) - -#### Connect from OpenDaylight (ODL) controller - -In order to connect through the OpenDaylight follow these procedure: - -- run karaf distribution (./opendayligh_installation_folder/bin/karaf) -- install the required feature list in DOL (feature:install odl-netconf-server - odl-netconf-connector odl-restconf-all odl-netconf-topology or - odl-netconf-clustered-topology) -- run a rest client program (e.g., postman or RESTClient) -- mount the remote netopeer2-server to the OpenDaylight by the following REST API: - - ``` - PUT <http://localhost:8181/restconf/config/network-topology:network-topology/topology/topology-netconf/node/hicn-node>` - ``` - with the following body: - - ```xml - <node xmlns="urn:TBD:params:xml:ns:yang:network-topology"> - <node-id>hicn-node</node-id> - <host xmlns="urn:opendaylight:netconf-node-topology">Remote_NETCONF_SERVER_IP</host> - <port xmlns="urn:opendaylight:netconf-node-topology">830</port> - <username xmlns="urn:opendaylight:netconf-node-topology">username</username> - <password xmlns="urn:opendaylight:netconf-node-topology">password</password> - <tcp-only xmlns="urn:opendaylight:netconf-node-topology">false</tcp-only> - <keepalive-delay xmlns="urn:opendaylight:netconf-node-topology">1</keepalive-delay> - </node> - ``` - - Note that the header files must be set to `Content-Type: application/xml, Accept: application/xml`. - -- send the operation through the following REST API: - -POST <http://localhost:8181/restconf/operations/network-topology:network-topology/topology/topology-netconf/node/hicn-node/yang-ext:mount/ietf-netconf:edit-config> - -The body can be used the same as edit-config in netopeer2-cli. - -#### Connect from Cisco Network Services Orchestrator (NSO) - -To connect NSO to the netopeer2-server, first, you need to write a NED package -for your device. The procedure to create NED for hicn is explained in the -following: - -Place hicn.yang model in a folder called hicn-yang-model, and follow these steps: - -- ncs-make-package --netconf-ned ./hicn-yang-model ./hicn-nso -- cd hicn-nso/src; make -- ncs-setup --ned-package ./hicn-nso --dest ./hicn-nso-project -- cd hicn-nso-project -- ncs -- ncs_cli -C -u admin -- configure -- devices authgroups group authhicn default-map remote-name user_name remote-password password -- devices device hicn address IP_device port 830 authgroup authhicn device-type netconf -- state admin-state unlocked -- commit -- ssh fetch-host-keys - -At this point, we are able to connect to the remote device. - -## Release note - -The current version is compatible with the 20.01 VPP stable and sysrepo devel. - -## Routing plugin for VPP and FRRouting for OSPF6 - -This document describes how to configure the VPP with hicn_router -plugin and FRR to enable the OSPF protocol. The VPP and FRR -are configured in a docker file. - -### DPDK configuration on host machine - -Install and configure DPDK: -```bash -make install T=x86_64-native-linux-gcc && cd x86_64-native-linux-gcc && sudo make install -modprobe uio -modprobe uio_pci_generic -dpdk-devbind --status -the PCIe number of the desired device can be observed ("xxx") -sudo dpdk-devbind -b uio_pci_generic "xxx" -``` - -### VPP configuration - -Run and configure the VPP (hICN router plugin is required to be installed in VPP): -```bash -vpp# set int state TenGigabitEtherneta/0/0 up -vpp# set int ip address TenGigabitEtherneta/0/0 a001::1/24 -vpp# create loopback interface -vpp# set interface state loop0 up -vpp# set interface ip address loop0 b001::1/128 -vpp# enable tap-inject # This creates the taps by router plugin -vpp# show tap-inject # This shows the created taps -vpp# ip mroute add ff02::/64 via local Forward # ff02:: is multicast ip address -vpp# ip mroute add ff02::/64 via TenGigabitEtherneta/0/0 Accept -vpp# ip mroute add ff02::/64 via loop0 Accept -``` - -Setup the tap interface: -```bash -ip addr add a001::1/24 dev vpp0 -ip addr add b001::1/128 dev vpp1 -ip link set dev vpp0 up -ip link set dev vpp1 up -``` - -### FRR configuration - -Install FRR in Ubuntu 18 LTS: -<http://docs.frrouting.org/projects/dev-guide/en/latest/building-frr-for-ubuntu1804.html> - -Run and configure FRRouting (ospf): -```text -/usr/lib/frr/frrinit.sh start & -vtysh -configure terminal -router ospf6 -area 0.0.0.0 range a001::1/24 -area 0.0.0.0 range b001::1/128 -interface vpp0 area 0.0.0.0 -interface vpp1 area 0.0.0.0 -end -wr -add "no ipv6 nd suppress-ra" to the first configurtion part of the /etc/frr/frr.conf -``` - -After the following configuration, the traffic over tap interface can be observed -via `tcpdump- i vpp1`. The neighborhood and route can be seen with the -`show ipv6 ospf6 neighbor/route` command. +A new control plane for hicn is under construction. diff --git a/docs/source/hicn-light.md b/docs/source/hicn-light.md index 90e0afc91..f5012f8e9 100644 --- a/docs/source/hicn-light.md +++ b/docs/source/hicn-light.md @@ -11,15 +11,14 @@ to communicate. Build dependencies: -- C99 ( clang / gcc ) -- CMake 3.4 +- C11 ( clang / gcc ) +- CMake 3.10 Basic dependencies: - OpenSSL - pthreads - libevent -- libparc ## hicn-light executables @@ -37,31 +36,27 @@ The command `hicn-light-daemon` runs the hicn-light forwarder. The forwarder can with the following options: ```bash -hicn-light-daemon [--port port] [--daemon] [--capacity objectStoreSize] [--log facility=level] +hicn-light-daemon [--port port] [--daemon] [--capacity objectStoreSize] [--log 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 +--port <tcp_port> = tcp port for local in-bound connections +--daemon = start as daemon process +--capacity <objectStoreSize> = 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 the log level. Available levels: trace, debug, info, warn, error, fatal +--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. +file, it overrides the command_line. -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. +In addition to the listeners setup in the configuration file, 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. ### hicn-light-control @@ -82,28 +77,20 @@ This is the full list of available commands in `hicn-light-control`. This comman 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. +The list of commands can be navigated using `hicn-light-control help`, `hicn-light-control help <object>`, `hicn-light-control help <object> <action>`. `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. ```bash -add listener <protocol> <symbolic> <local_adress> <local_port> +add listener <protocol> <symbolic> <local_address> <local_port> <interface> <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. - -```bash -add listener hicn <symbolic> <local_adress> - - <symbolic> :User defined name for listener, must start with alpha and be alphanum - <localAddress> :IPv4 or IPv6 address + <interface> :interface on which to bind ``` `add connection`: creates a TCP or UDP connection on the local forwarder with the specified options. @@ -119,17 +106,6 @@ add connection <protocol> <symbolic> <remote_ip> <remote_port> <local_ip> <local <local_port> : local TCP/UDP port ``` -`add connection hicn`: creates an hicn connection on the local forwarder with the specified options. - -```bash -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. ```bash @@ -142,7 +118,7 @@ list <connections | routes | listeners> 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') + <connid>: :The egress connection id (see 'list connection' command) <prefix>: :ipAddress/netmask <cost>: :positive integer representing cost ``` @@ -151,11 +127,10 @@ add route <symbolic | connid> <prefix> <cost> only for UDP connections, TCP is ignored. ```bash -remove connection <protocol> <symbolic | connid> +remove connection <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') + <connid>: :The egress connection id (see 'list connection' command) ``` @@ -168,24 +143,24 @@ remove route <symbolic | connid> <prefix> <prefix> : the prefix (ipAddress/netmask) to remove ``` -`cache serve`: enables/disables replies from local content store (if available). +`serve cache`: enables/disables replies from local content store (if available). ```bash -cache serve <on|off> +serve cache <on|off> ``` -`cache store`: enables/disables the storage of incoming data packets in the local content store +`store cache`: enables/disables the storage of incoming data packets in the local content store (if available). ```bash -cache store <on|off> +store cache <on|off> ``` -`cache clear`: removes all the cached data form the local content store (if available). +`clear cache`: removes all the cached data form the local content store (if available). ```bash -cache clear +clear cache ``` `set strategy`: sets the forwarding strategy for a give prefix. There are 4 different strategies @@ -200,12 +175,14 @@ implemented in hicn-light: ICNP 2013. - **low_latency**: uses the face with the lowest latency. In case more faces have similar latency the strategy uses them in parallel. +- **replication** +- **bastpath** ```bash set strategy <prefix> <strategy> <preifx> : the prefix to which apply the forwarding strategy - <strategy> : random | loadbalancer | low_latency + <strategy> : random | loadbalancer | low_latency | replication | bestpath ``` `set wldr`: turns on/off WLDR on the specified connection. WLDR (Wireless Loss Detiection and @@ -224,36 +201,13 @@ set wldr <on|off> <symbolic | connid> ``` -`add punting`: add punting rules to the forwarders. - -```bash -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. - -```bash -mapme enable <on|off> -``` -`mapme discovery`: enables/disables mapme discovery. - -```bash -mapme discovery <on|off> -``` - -`mapme timescale`: set the timescale value expressed in milliseconds. - -```bash -mapme timescale <milliseconds> -``` - -`mapme retx`: set the retransmission time value expressed in millisecond. +`set mapme`: enables/disables mapme, enables/disables mapme discovery, set the timescale value (expressed in milliseconds), set the retransmission time value (expressed in milliseconds). ```bash -mapme retx <milliseconds> +mapme set enable <on|off> +mapme set discovery <on|off> +mapme set timescale <milliseconds> +mapme set retx <milliseconds> ``` `quit`: exits the interactive bash. @@ -264,13 +218,12 @@ This is an example of a simple configuration file for hicn-light. It can be load the command `hicn-light-daemon --config configFile.cfg`, assuming the file name is `configFile.cfg`. ```bash -#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 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 eth0 -#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 +# 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 eth0 -#add a route toward the remote node +# Add a route toward the remote node add route conn0 c001::/64 1 ``` diff --git a/docs/source/index.rst b/docs/source/index.rst index 99ea39afa..c41df95ca 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,27 +1,76 @@ Hybrid Information-Centric Networking ===================================== -Hybrid Information-Centric Networking (hICN) is a network architecture that makes -use of IPv6 or IPv4 to realize location-independent communications. It is largely -inspired by the pioneer work of Van Jacobson on Content-Centric Networking, that was -a clean-slate architecture whereas hICN is based on the Internet protocol and easy to -deploy in today networks and applications. hICN brings many-to-many communications, -multi-homing, multi-path, multi-source, group communications to the Internet protocol -without replicated unicast. The project implements novel transport protocols, with a socket API, -for real-time and capacity seeking applications. A scalable stack is available based -on VPP and a client stack is provided to support any mobile and desktop operating system. +Hybrid Information-Centric Networking (hICN) is a network architecture that +makes use of IPv6 or IPv4 to implement location-independent communications. It +is largely inspired by the pioneer work of Van Jacobson on Content-Centric +Networking (RFC 8569, RFC 8609) that is a clean-slate architecture. hICN is +based on the Internet protocol and easyier to deploy in today networks and +applications. hICN brings many-to-many communications, multi-homing, multi-path, +multi-source, group communications to the Internet protocol. The current code +implements also transport protocols, with a socket API, for real-time and +capacity seeking applications. A scalable stack is available based on VPP and a +client stack is provided to support mobile and desktop operating systems. + +A detailed description of the architecture is described in the paper + +Giovanna Carofiglio, Luca Muscariello, Jordan Augé, Michele Papalini, Mauro +Sardara, and Alberto Compagno. 2019. Enabling ICN in the Internet Protocol: +Analysis and Evaluation of the Hybrid-ICN Architecture. In Proceedings of the +6th ACM SIGCOMM Conference on Information-Centric Networking (ICN '19). +Association for Computing Machinery, New York, NY, USA, 55–66. DOI: +https://doi.org/10.1145/3357150.3357394 + +The project wiki page is full of resources https://wiki.fd.io/view/HICN + +.. toctree:: + :caption: Architecture + + 1-architecture + .. toctree:: + :caption: Getting started + :maxdepth: 1 started + +.. toctree:: + :caption: Core library + :maxdepth: 1 + lib + +.. toctree:: + :caption: The VPP Plugin + :maxdepth: 1 + vpp-plugin + +.. toctree:: + :caption: The Transport Library + :maxdepth: 1 + transport + +.. toctree:: + :caption: The Portable Forwarder + :maxdepth: 1 + hicn-light + +.. toctree:: + :caption: Network Control and Management + :maxdepth: 1 + interface control telemetry - utils - apps +.. toctree:: + :caption: Applications and Tools + :maxdepth: 1 + utils + apps + packethicn
\ No newline at end of file diff --git a/docs/source/interface.md b/docs/source/interface.md index cf05a5c7b..909f60bfa 100644 --- a/docs/source/interface.md +++ b/docs/source/interface.md @@ -45,35 +45,6 @@ interfaces: link and address information, interface types, and bonjour service discovery. -### Architectural overview - -#### Facelets - -TODO: - -```text -- Key attributes (netdevice and protocol family) -- Facelet API -``` - -#### Events - -TODO - -#### Facelet cache & event scheduling - -TODO: - -```text - - Facelet cache - - Joins - - How synchronization work -``` - -### Interface API - -TODO - ## Developing a new interface ### Dummy template @@ -261,7 +232,7 @@ error. ``` While support for multiple file descriptors might be added in the future, an -alternative short-term implementation might consider the instanciation of +alternative short-term implementation might consider the instantiation of multiple interface, as is done for Bonjour in the current codebase, in `src/api.c`. @@ -304,8 +275,6 @@ The build system is based on CMake. Each interface should declare its source files, private and public header files, as well as link dependencies in the local `CMakeLists.txt` file. -TODO: detail the structure of the file - ### Hands-on #### Architecture diff --git a/docs/source/packethicn.md b/docs/source/packethicn.md index cf4976837..acf2d7cc9 100644 --- a/docs/source/packethicn.md +++ b/docs/source/packethicn.md @@ -1,11 +1,13 @@ HICN Plugin for Wireshark =================== -The `packethicn` plugin adds support to Wireshark to parse and dissect HICN traffic. +The `packethicn` plugin adds support to Wireshark to parse and dissect HICN +traffic. `packethicn` can be compiled and installed in two ways: -1. Alongside HICN, from the HICN root dir (see [Build with HICN](#Build-with-HICN)) +1. Alongside HICN, from the HICN root dir (see [Build with + HICN](#Build-with-HICN)) 2. As a standalone component (see [Standalone build](#Standalone-build)) @@ -14,13 +16,12 @@ The second one is preferred if HICN is already installed in the system. # Supported platforms `packethicn` has been tested in -- Ubuntu 18.04 - Ubuntu 20.04 -- macOS 11.2 +- macOS 12.3 Other platforms and architectures may work. -# Installation +# Installation ## Build with HICN ### Dependencies @@ -38,15 +39,10 @@ From the root HICN dir add the `-DBUILD_WSPLUGIN` flag to cmake. ```bash $ cd hicn - $ mkdir build; cd build - -$ cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl\@1.1 -DBUILD_APPS=ON -DBUILD_WSPLUGIN=ON .. - +$ cmake -DBUILD_APPS=ON -DBUILD_WSPLUGIN=ON .. $ make -j`nproc` - $ sudo make install - ``` ## Standalone build @@ -55,22 +51,16 @@ $ sudo make install #### Install dependencies ```bash $ sudo add-apt-repository ppa:wireshark-dev/stable - $ curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash - $ sudo apt install -y build-essential cmake libhicn-dev wireshark wireshark-dev libgcrypt-dev libgnutls28-dev ``` -#### Compile and install HICN plugin +#### Compile and install HICN wireshark plugin ```bash $ cd packethicn - $ mkdir build; cd build - $ cmake .. - $ make - $ sudo make install ``` @@ -80,15 +70,10 @@ If installing wireshark via brew use the `./install_macos.sh` script as shown be ```bash $ brew tap icn-team/hicn-tap - $ brew install hicn - $ brew install wireshark - $ brew install cask wireshark - $ cd packethicn - $ ./install_macos.sh ``` @@ -96,13 +81,9 @@ Otherwise (if wireshark was compiled from sources) you can follow the setup for ```bash $ cd packethicn - $ mkdir build; cd build - $ cmake .. - $ make - $ sudo make install ``` @@ -110,6 +91,7 @@ $ sudo make install ## Filters + | Filter | Description | Example | | --- | --- | --- | | `hicn` | HICN traffic only | *hicn* | diff --git a/docs/source/started.md b/docs/source/started.md index ef3763366..dd2f83bab 100644 --- a/docs/source/started.md +++ b/docs/source/started.md @@ -1,15 +1,16 @@ -# Getting started +# Code structure ## Introduction -hicn is an open source implementation of Cisco's hICN. It includes a network stack, that implements -ICN forwarding path in IPv6, and a transport stack that implements two main transport protocols and -a socket API. The transport protocols provide one reliable transport service implementation and a -real-time transport service for audio/video media. +hicn is an open source implementation of Cisco's hICN. It includes a network +stack, that implements ICN forwarding path in IPv6, and a transport stack that +implements two main transport protocols and a socket API. The transport +protocols provide one reliable transport service implementation and a real-time +transport service for audio/video media. ## Directory layout -```text + | Directory name | Description | | -------------- | --------------------------------------------------------- | | lib | Core support library | @@ -19,39 +20,36 @@ real-time transport service for audio/video media. | utils | Tools for testing | | apps | Application examples using hicn stack | | ctrl | Tools and libraries for network management and control | -``` -hicn plugin is a VPP plugin that implement hicn packet processing as specified in -<https://datatracker.ietf.org/doc/draft-muscariello-intarea-hicn/.> The transport library is used to -implement the hicn host stack and makes use of libmemif as high performance connector between -transport and the network stack. The transport library makes use of VPP binary API to configure the -local namespace (local face management). +hicn plugin is a VPP plugin that implement hicn packet processing as specified +in [1] The transport library is used to implement the hicn host stack and makes +use of libmemif as high performance connector between transport and the network +stack. The transport library makes use of VPP binary API to configure the local +namespace (local face management). ## Release note -The current master branch provides the latest release which is compatible with the latest VPP stable. -No other VPP releases are supported nor maintained. At every new VPP release distribution hicn -master branch is updated to work with the latest stable release. All previous stable releases -are discontinued and not maintained. The user who is interested in a specific release can always -checkout the right code tree by searching the latest commit under a given git tag carrying the -release version. +The current master branch provides the latest release which is compatible with +the latest VPP stable. No other VPP releases are supported nor maintained. At +every new VPP release distribution hicn master branch is updated to work with +the latest stable release. All previous stable releases are discontinued and not +maintained. The user who is interested in a specific release can always checkout +the right code tree by searching the latest commit under a given git tag +carrying the release version. -The Hybrid ICN software distribution can be installed for several platforms. -The network stack comes in two different implementations: one scalable based -on VPP and one portable based on IPC and sockets. +The Hybrid ICN software distribution can be installed for several platforms. The +network stack comes in two different implementations: one scalable based on VPP +and one portable based on IPC and sockets. -The transport stack is a unique library that is used for both the scalable -and portable network stacks. +The transport stack is a unique library that is used for both the scalable and +portable network stacks. ## Supported platforms -- Ubuntu 18.04 LTS (amd64, arm64) -- Debian Stable/Testing -- Red Hat Enterprise Linux 7 -- CentOS 7 +- Ubuntu 20.04 LTS (amd64, arm64) - Android 10 (amd64, arm64) -- iOS 13 -- macOS 10.15 +- iOS 15 +- macOS 12.3 - Windows 10 Other platforms and architectures may work. @@ -63,35 +61,97 @@ You can either use released packages, or compile hicn from sources. curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash ``` -### CentOS +The following debian packages for Ubuntu are available dor amd64 and arm64 ```bash -curl -s https://packagecloud.io/install/repositories/fdio/release/script.rpm.sh | sudo bash +facemgr-dev +facemgr +hicn-apps-dev +hicn-apps +hicn-light +hicn-plugin-dev +hicn-plugin +libhicn-dev +libhicn +libhicnctrl-dev +libhicnctrl-modules +libhicnctrl +libhicntransport-dev +libhicntransport-io-modules +libhicntransport ``` ### macOS ```bash +brew tap icn-team/hicn-tap brew install hicn ``` +or + +```bash +git clone https://github.com/FDio/hicn.git +$ cd hicn +$ OPENSSL_ROOT_DIR=/usr/local/opt/openssl\@1.1 make build-release +``` + ### Android +hICN is built as a native library for the Android NDK which are packaged +as Android archives AAR and made available in a Maven repository in +Github Packages in + +<https://github.com/orgs/icn-team/packages> + +To build from sources, refer to the Android SDK in + +<https://github.com/icn-team/android-sdk> Install the applications via the Google Play Store + <https://play.google.com/store/apps/developer?id=ICN+Team> ### iOS -Coming soon. +Clone this distro + +```bash +git clone https://github.com/icn-team/ios-sdk.git +cd ios-sdk +``` +Compile everything (dependencies and hICN modules) + +```bash +make update +make all +``` +Compile everything with Qt (dependencies, hICN modules and Viper dependencies) + +```bash +make update +make all_qt +``` ### Windows -Coming soon. +Install vcpkg + +```bash +git clone https://github.com/icn-team/windows-sdk +.\windows-sdk\scripts\init.bat +``` + + +```bash +cd windows-sdk +make all +``` ### Docker -Several docker images are nightly built with the latest software for Ubuntu 18 LTS (amd64/arm64), -and available on docker hub at <https://hub.docker.com/u/icnteam>. +Several docker images are nightly built with the latest software for Ubuntu 18 +LTS (amd64/arm64), and available on docker hub at +<https://hub.docker.com/u/icnteam>. The following images are nightly built and maintained. @@ -106,6 +166,8 @@ docker pull icnteam/vhttpproxy:amd64 docker pull icnteam/vhttpproxy:arm64 ``` +Other Dockerfiles are included in the main git repo for development. + ### Vagrant Vagrant boxes for a virtual switch are available at @@ -117,12 +179,21 @@ vagrant box add icnteam/vswitch Supported providers are libvirt, vmware and virtualbox. +## References + +Giovanna Carofiglio, Luca Muscariello, Jordan Augé, Michele Papalini, Mauro +Sardara, and Alberto Compagno. 2019. Enabling ICN in the Internet Protocol: +Analysis and Evaluation of the Hybrid-ICN Architecture. In Proceedings of the +6th ACM Conference on Information-Centric Networking (ICN '19). Association for +Computing Machinery, New York, NY, USA, 55–66. +DOI: https://doi.org/10.1145/3357150.3357394 + ## License This software is distributed under the following license: ```bash -Copyright (c) 2017-2020 Cisco and/or its affiliates. +Copyright (c) 2019-2022 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: diff --git a/docs/source/telemetry.md b/docs/source/telemetry.md index 8887b8f1f..b4d538d76 100644 --- a/docs/source/telemetry.md +++ b/docs/source/telemetry.md @@ -31,22 +31,19 @@ sudo make install hICN collectd plugins have been tested in: -- Ubuntu 16.04 LTS (x86_64) -- Ubuntu 18.04 LTS (x86_64) -- Debian Stable/Testing -- Red Hat Enterprise Linux 7 -- CentOS 7 +- Ubuntu 20.04 LTS ### Dependencies Build dependencies: -- VPP 20.01, Debian packages can be found on [packagecloud](https://packagecloud.io/fdio/release/install): +VPP 22.02, Debian packages can be found on +[packagecloud](https://packagecloud.io/fdio/release/install): - vpp - libvppinfra-dev - vpp-dev - hicn-plugin-dev -- `collectd` and `collectd-dev`: `sudo apt install collectd collectd-dev` +- `collectd` and `collectd-dev`: `sudo apt install collectd collectd-dev libyajl-dev` ## Getting started @@ -62,14 +59,18 @@ Before running collectd, a vpp forwarder must be started. If the vpp-hicn plugin is used, the hicn-plugin must be available in the vpp forwarder. If you need the custom types that the two plugins define, they are present in -`telemetry/custom_types.db`. It is useful if you are using InfluxDB as it requires -the type database for multi-value metrics -(see [CollectD protocol support in InfluxDB](https://docs.influxdata.com/influxdb/v1.7/supported_protocols/collectd/)). +`telemetry/custom_types.db`. It is useful if you are using InfluxDB as it +requires the type database for multi-value metrics (see [CollectD protocol +support in +InfluxDB](https://docs.influxdata.com/influxdb/v1.7/supported_protocols/collectd/)). ## Plugin options `vpp` and `vpp-hicn` have the same two options: -- `Verbose` enables additional statistics. You can check the sources to have an exact list of available metrics. -- `Tag` tags the data with the given string. Useful for identifying the context in which the data was retrieved in InfluxDB for instance. If the tag value is `None`, no tag is applied. +- `Verbose` enables additional statistics. You can check the sources to have an + exact list of available metrics. +- `Tag` tags the data with the given string. Useful for identifying the context + in which the data was retrieved in InfluxDB for instance. If the tag value is + `None`, no tag is applied. ### Example: storing statistics from vpp and vpp-hicn diff --git a/docs/source/transport.md b/docs/source/transport.md index 3e7844ad5..c5250023a 100644 --- a/docs/source/transport.md +++ b/docs/source/transport.md @@ -1,38 +1,51 @@ -# Transport library - ## Introduction -This library provides transport services and socket API for applications willing to communicate -using the hICN protocol stack. +The transport library provides transport services and socket API for +applications willing to communicate using the hICN protocol stack. Overview: - Implementation of the hICN core objects (interest, data, name..) exploiting - the API provided by [libhicn](../lib). -- Connectors for connecting the application to either the hicn-plugin or the - hicn-light forwarder. + the API provided by [libhicn](./lib.md). +- IO modules for seamlessly connecting the application to the hicn-plugin for [VPP](https://github.com/FDio/vpp) or the + [hicn-light](./hicn-light.md) forwarder. - Transport protocols (RAAQM, CBR, RTC) -- Transport services (authentication, integrity, segmentation, reassembly, naming) +- Transport services (authentication, integrity, segmentation, reassembly, + naming) - Interfaces for applications (from low-level interfaces for interest-data interaction to high level interfaces for Application Data Unit interaction) + ## Build dependencies ### Ubuntu -- libparc -- libmemif (linux only, if compiling with VPP support) -- libasio +```bash +sudo apt install libasio-dev libconfig++-dev libssl-dev +``` If you wish to use the library for connecting to the vpp hicn-plugin, you will -need to also install vpp, the vpp libraries and the libmemif libraries: +need to also install vpp and its libraries. -- DEB packages: - - vpp - - vpp-lib - - vpp-dev +```bash +# Prevent vpp to set sysctl +export VPP_INSTALL_SKIP_SYSCTL=1 +VPP_VERSION=$(cat "${VERSION_PATH}" | grep VPP_DEFAULT_VERSION | cut -d ' ' -f 2 | tr -d '"' | grep -Po '\d\d.\d\d') -You can get them either from from the vpp packages or the source code. Check -the [VPP wiki](https://wiki.fd.io/view/VPP) for instructions. +curl -s https://packagecloud.io/install/repositories/fdio/${VPP_VERSION//./}/script.deb.sh | bash +curl -L https://packagecloud.io/fdio/${VPP_VERSION//./}/gpgkey | apt-key add - +sed -E -i 's/(deb.*)(\[.*\])(.*)/\1\3/g' /etc/apt/sources.list.d/fdio_${VPP_VERSION//./}.list +apt-get update + +apt-get install -y \ + vpp-dev \ + libvppinfra-dev \ + vpp-plugin-core \ + vpp \ + libvppinfra +``` + +You can get them either from from the vpp packages or the source code. Check the +[VPP wiki](https://wiki.fd.io/view/VPP) for instructions. ### macOS @@ -40,31 +53,23 @@ We recommend to use [HomeBrew](https://brew.sh/) for installing the libasio dependency: ```bash -brew install asio +brew install asio libconfig openssl@1.1 ``` -Download, compile and install libparc: - -```bash -git clone -b cframework/master https://gerrit.fd.io/r/cicn cframework && cd cframework -mkdir -p libparc.build && cd libparc.build -cmake ../libparc -make -make install -``` +Since VPP does not support macOS, the IO module memif is not built. -Libparc will be installed by default under `/usr/local/lib` and `/usr/local/include`. -Since VPP does not support macOS, the hicn-plugin connector is not built. ## Build the library -From the project root folder: +The library is built by default from the main CMakeLists.txt. +If you have all the dependencies installed, including [libhicn](./lib.md), +you can also build libtransport alone: ```bash cd libtransport mkdir build && cd build cmake .. -make +cmake --build . ``` ### Compile options @@ -75,11 +80,7 @@ The build process can be customized with the following options: - `CMAKE_BUILD_TYPE`: The build configuration. Options: `Release`, `Debug`. Default is `Release`. - `ASIO_HOME`: The folder containing the libasio headers. -- `LIBPARC_HOME`: The folder containing the libparc headers and libraries. - `VPP_HOME`: The folder containing the installation of VPP. -- `LIBMEMIF_HOME`: The folder containing the libmemif headers and libraries. -- `BUILD_MEMIF_CONNECTOR`: On linux, set this value to `ON` for building the - VPP connector. An option can be set using cmake -D`OPTION`=`VALUE`. @@ -88,5 +89,269 @@ An option can be set using cmake -D`OPTION`=`VALUE`. For installing the library, from the cmake build folder: ```bash -sudo make install +cmake --build . -- install +``` + + +## Usage + +Examples on how to use the library can be found in the apps folder of the project. +In particular you can check the **hiperf** application, which demonstrates +how to use the API to interact with the hicn transport, both for consumer and producer. + +### Configuration file + +The transport can be configured using a configuration file. There are two ways +to tell libransport where to find the configuration file: + +- programmatically - you set the configuration file path in your application: +```cpp +// Set conf file path +std::string conf_file = "/opt/hicn/etc/transport.config" +// Parse config file +transport::interface::global_config::parseConfigurationFile(conf_file); +``` + +- using the environment variable `TRANSPORT_CONFIG`: +```bash +export TRANSPORT_CONFIG=/opt/hicn/etc/transport.config +./hiperf -C b001::1 +``` + +Here is an example of configuration file: + +``` +// Configuration for io_module +io_module = { + path = []; + name = "forwarder_module"; +}; + +// Configuration for forwarder io_module +forwarder = { + n_threads = 1; + + connectors = { + c0 = { + /* local_address and local_port are optional */ + local_address = "127.0.0.1"; + local_port = 33436; + remote_address = "127.0.0.1"; + remote_port = 33436; + } + }; + + listeners = { + l0 = { + local_address = "127.0.0.1"; + local_port = 33437; + } + }; +}; + +// Logging +log = { + // Log level (INFO (0), WARNING (1), ERROR (2), FATAL (3)) + minloglevel = 0; + + // Verbosity level for debug logs + v= 2; + + // Log to stderr + logtostderr = true; + + // Get fancy colored logs + colorlogtostderr = true; + + // Log messages above this level also to stderr + stderrthreshold = 2; + + // Set log prefix for each line log + log_prefix = true; + + // Log dir + log_dir = "/tmp"; + + // Log only specific modules. + // Example: "membuf=2,rtc=3" + vmodule = ""; + + // Max log size in MB + max_log_size = 10; + + // Log rotation + stop_logging_if_full_disk = true; +}; +``` + + +## Security + +hICN has built-in authentication and integrity features by either: +* Cryptographically signing all packets using an asymmetric key (like RSA) or a + symmetric one (like HMAC). The latter requires that all parties have prior + access to the same key. Beware that this method is computationally expensive + and impacts max throughput and CPU usage. +* Using manifests. Manifests are special packets that holds the digests of a + group of data packets. Only the manifest needs to be signed and authenticated; + other packets are authenticated simply by verifying that their digest is + present in a manifest. + +### Per-packet signatures + +To enable per-packet signature with asymmetric signing: +* On the producer, disable manifests (which are ON by default): + ```cpp + producer_socket->setSocketOption(GeneralTransportOptions::MANIFEST_MAX_CAPACITY, 0u); + ``` +* On the producer, instantiate an `AsymmetricSigner` object by passing either an + asymmetric pair of keys as + [EVP_KEY](https://www.openssl.org/docs/man3.0/man3/EVP_PKEY_new.html) object + or a keystore path and password as strings: + ```cpp + std::shared_ptr<Signer> signer = std::make_shared<AsymmetricSigner>("./rsa.p12", "hunter2"); + ``` +* Pass the signer object to libtransport: + ```cpp + producer_socket->setSocketOption(GeneralTransportOptions::SIGNER, signer); + ``` +* On the consumer, instantiate an `AsymmetricVerifer` object by passing either a + certificate as a [X509](https://www.openssl.org/docs/man1.0.2/man3/x509.html) + object, an asymmetric public key as a + [EVP_KEY](https://www.openssl.org/docs/man3.0/man3/EVP_PKEY_new.html) object + or a certificate path as a string: + ```cpp + std::shared_ptr<Verifier> verifier = std::make_shared<Verifier>("./rsa.crt"); + ``` +* Pass the verifier object to libtransport: + ```cpp + consumer_socket->setSocketOption(GeneralTransportOptions::VERIFIER, verifier); + ``` + +To enable per-packet signature with symmetric signing, follow the above steps +replacing `AsymmetricSigner` with `SymmetricSigner` and `AsymmetricVerifer` with +`SymmetricSigner`. A `SymmetricSigner` only has one constructor which expects a +`CryptoSuite` and a passphrase. A `SymmetricVerifier` also has a single +constructor which expects a passphrase: +```cpp +std::shared_ptr<Signer> signer = std::make_shared<SymmetricSigner>(CryptoSuite::HMAC_SHA256, "hunter2"); +std::shared_ptr<Verifier> verifier = std::make_shared<SymmetricVerifier>("hunter2"); +``` + +Check [Supported crypto suites](#supported-crypto-suites) for the list of +available suites. + +### Enabling manifests + +* Follow steps 2-5 in [Per-packet signatures](#per-packet-signatures). +* By default, a manifest has a maximum capacity `C_max` of 30 packets. To change + this value: + ```cpp + producer_socket->setSocketOption(GeneralTransportOptions::MANIFEST_MAX_CAPACITY, 20u); + ``` + +In the case of RTC, manifests are sent after the data they contain and on the +consumer side, data packets are immediately forwarded to the application, *even +if they weren't authenticated yet via a manifest*. This is to minimize latency. +The digest of incoming data packets are kept in a buffer while waiting for +manifests to arrive. When the buffer size goes above a threshold `T`, an alert +is raised by the verifier object. That alert threshold is computed as follows: +``` +T = manifest_factor_alert * C_max +``` + +The value of `C_max` is passed by the producer to the consumer at the start of +the connection. `manifest_factor_alert` is a consumer socket option. It +basically acts on the resilience of manifests against networks losses and +reflects the application's tolerance to unverified packets: a higher value gives +the transport the time needed to recover from several manifest losses but +potentially allows a larger number of unverified packet to go the application +before alerts are triggered. It is set to `20` by default and should always be +`>= 1`. To change it: +```cpp +consumer_socket_->setSocketOption(GeneralTransportOptions::MANIFEST_FACTOR_ALERT, 10u); +``` + +The buffer does not keep unverified packets indefinitely. After a certain amount +of packets have been received and processed (and were verified or not), older +packets still unverified are flushed out. This is to prevent the buffer to grow +uncontrollably and to raise alerts for packets that are not relevant to the +application anymore. That threshold of relevance is computed as follows: +``` +T = manifest_factor_relevant * C_max +``` + +`manifest_factor_relevant` is a consumer socket option. It is set to `100` by +default. Its value must be set so that `manifest_factor_relevant > +manifest_factor_alert >= 1`. If `manifest_factor_relevant <= +manifest_factor_alert`, no alert will ever be raised. To change it: +```cpp +consumer_socket_->setSocketOption(GeneralTransportOptions::MANIFEST_FACTOR_RELEVANT, 200u); +``` + +### Handling authentication failures + +When a data packet fails authentication, or when the unverified buffer is full +in the case of RTC, an alert is triggered by the verifier object. By default +libtransport aborts the connection upon reception of that alert. You may want to +intercept authentication failures in your application: +* Define a callback with arguments an `uint32_t` integer, which will be set to + the suffix of the faulty packet, and a `auth::VerificationPolicy`, which will + be set to the action suggested by the verifier object. The callback must + return another `auth::VerificationPolicy` which will be the actual action + taken by libtransport: + ```cpp + auth::VerificationPolicy onAuthFailed(uint32_t suffix, auth::VerificationPolicy policy) { + std::cout << "auth failed for packet " << suffix << std::endl; + return auth::VerificationPolicy::ACCEPT; + } + ``` +* Give that callback to your `Verifier` object as well as a list of + `auth::VerificationPolicy` to intercept (if left empty, will be set by + default to `{ABORT, DROP}`): + ```cpp + verifier->setVerificationFailedCallback(&onAuthFailed, { + auth::VerificationPolicy::ABORT, + auth::VerificationPolicy::DROP, + auth::VerificationPolicy::UNKNOWN, + }); + ``` + +### Supported crypto suites + +The following `CryptoSuite` are supported by libtransport: ``` +ECDSA_BLAKE2B512 +ECDSA_BLAKE2S256 +ECDSA_SHA256 +ECDSA_SHA512 +RSA_BLAKE2B512 +RSA_BLAKE2S256 +RSA_SHA256 +RSA_SHA512 +HMAC_BLAKE2B512 +HMAC_BLAKE2S256 +HMAC_SHA256 +HMAC_SHA512 +DSA_BLAKE2B512 +DSA_BLAKE2S256 +DSA_SHA256 +DSA_SHA512 +``` + + +## Logging + +Internally libtransport uses glog as logging library. If you want to have a more +verbose transport log when launching a test or an app, you can set environment +variables in this way: + +``` +GLOG_v=4 hiperf -S b001::/64 +``` + +For a more exhaustive list of options, please check the instructions in the glog +[README](https://github.com/google/glog#setting-flags). + +Useful options include enabling logging *per module*. Also you can compile out +useless messages in release builds. diff --git a/docs/source/utils.md b/docs/source/utils.md index 79ada8985..42e407ff0 100644 --- a/docs/source/utils.md +++ b/docs/source/utils.md @@ -19,7 +19,6 @@ Basic dependencies: - OpenSSL - pthreads - libevent -- libparc - libhicntransport ## Executables @@ -43,9 +42,6 @@ Options: -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 = quiet, no printing (default false) -d = daemon mode -H = help ``` @@ -75,9 +71,6 @@ Options: -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, no printing (default false) -H = help ``` @@ -92,45 +85,59 @@ 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: ```bash +HIPERF - Instrumentation tool for performing active networkmeasurements with hICN usage: hiperf [-S|-C] [options] [prefix|name] SERVER OR CLIENT: --D = Run as a daemon --R = Run RTC protocol (client or server) --f <filename> = Log file +-D Run as a daemon +-R Run RTC protocol (client or server) +-f <filename> Log file +-z <io_module> IO module to use. Default: hicnlightng_module +-F <conf_file> Path to optional configuration file for libtransport +-a Enables data packet aggregation. Works only in RTC mode +-X <param> Set FEC params. Options are Rely_K#_N# or RS_K#_N# SERVER SPECIFIC: --A <content_size> = Size of the content to publish. This is not the size of the packet (see -s for it). --s <packet_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 packets --k <passphrase> = String from which a 128-bit symmetric key will be derived for signing packets --y <hash_algorithm> = Use the selected hash algorithm for calculating manifest digests --p <password> = Password for p12 keystore --x = Produce a content of <content_size>, then after downloading it produce a new content of <content_size> without resetting the suffix to 0. --B <bitrate> = Bitrate for RTC producer, to be used with the -R option. --I = Interactive mode, start/stop real time content production by pressing return. To be used with the -R option --E = Enable encrypted communication. Requires the path to a p12 file containing the crypto material used for the TLS handshake +-A <content_size> Sends an application data unit in bytes that is published once before exit +-s <packet_size> Data packet payload size. +-r Produce real content of <content_size> bytes +-m <manifest_capacity> 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 packets +-k <passphrase> String from which a 128-bit symmetric key will be derived for signing packets +-p <password> Password for p12 keystore +-y <hash_algorithm> Use the selected hash algorithm for computing manifest digests (default: SHA256) +-x Produces application data units of size <content_size> without resetting the name suffix to 0. +-B <bitrate> RTC producer data bitrate, to be used with the -R option. +-I Interactive mode, start/stop real time content production by pressing return. To be used with the -R option +-T <filename> Trace based mode, hiperf takes as input a file with a trace. Each line of the file indicates the timestamp and the size of the packet to generate. To be used with the -R option. -B and -I will be ignored. +-E Enable encrypted communication. Requires the path to a p12 file containing the crypto material used for the TLS handshake +-G <port> Input stream from localhost at the specified port CLIENT SPECIFIC: --b <beta_parameter> = RAAQM beta parameter --d <drop_factor_parameter> = RAAQM drop factor parameter --L <interest lifetime> = Set interest lifetime. --M <Download for real> = Store the content downloaded. --W <window_size> = Use a fixed congestion window for retrieving the data. --i <stats_interval> = Show the statistics every <stats_interval> milliseconds. --v = Enable verification of received data --c <certificate_path> = Path of the producer certificate to be used for verifying the origin of the packets received. Must be used with -v. --k <passphrase> = String from which is derived the symmetric key used by the producer to sign packets and by the consumer to verify them. Must be used with -v. --t = Test mode, check if the client is receiving the correct data. This is an RTC specific option, to be used with the -R (default false) --P = Prefix of the producer where to do the handshake +-b <beta_parameter> RAAQM beta parameter +-d <drop_factor_parameter> RAAQM drop factor parameter +-L <interest lifetime> Set interest lifetime. +-u <delay> Set max lifetime of unverified packets. +-M <input_buffer_size> Size of consumer input buffer. If 0, reassembly of packets will be disabled. +-W <window_size> Use a fixed congestion window for retrieving the data. +-i <stats_interval> Show the statistics every <stats_interval> milliseconds. +-c <certificate_path> Path of the producer certificate to be used for verifying the origin of the packets received. +-k <passphrase> String from which is derived the symmetric key used by the producer to sign packets and by the consumer to verify them. +-t Test mode, check if the client is receiving the correct data. This is an RTC specific option, to be used with the -R (default: false) +-P Prefix of the producer where to do the handshake +-j <relay_name> Publish received content under the name relay_name.This is an RTC specific option, to be used with the -R (default: false) +-g <port> Output stream to localhost at the specified port +-e <strategy> Enance the network with a realiability strategy. Options 1: unreliable, 2: rtx only, 3: fec only, 4: delay based, 5: low rate, 6: low rate and best path 7: low rate and replication, 8: low rate and best path/replication(default: 2 = rtx only) +-H Disable periodic print headers in stats report. +-n <nb_iterations> Print the stats report <nb_iterations> times and exit. + This option limits the duration of the run to <nb_iterations> * <stats_interval> milliseconds. ``` Example: ``` -hiperf -S c001::/64 +hiperf -S b001::/64 +hiperf -C b001:: ``` ## Client/Server benchmarking using `hiperf` @@ -161,8 +168,7 @@ apt-get install -y git \ build-essential \ libasio-dev \ libcurl4-openssl-dev \ - --no-install-recommends \ - libparc-dev + --no-install-recommends mkdir hicn-suite && cd hicn-suite git clone https://github.com/FDio/hicn.git hicn-src mkdir hicn-build && cd hicn-build @@ -289,8 +295,7 @@ apt-get install -y git \ vpp vpp-dev vpp-plugin-core libvppinfra \ libmemif libmemif-dev \ python3-ply \ - --no-install-recommends \ - libparc-dev + --no-install-recommends mkdir hicn-suite && cd hicn-suite git clone https://github.com/FDio/hicn.git hicn-src mkdir hicn-build && cd hicn-build diff --git a/docs/source/vpp-plugin.md b/docs/source/vpp-plugin.md index 7f49cd8b9..b6b469494 100644 --- a/docs/source/vpp-plugin.md +++ b/docs/source/vpp-plugin.md @@ -22,7 +22,7 @@ mkdir -p build cd build cmake .. -DCMAKE_INSTALL_PREFIX=/usr make -sudo make install +sudo cmake --build . -- install ``` VPP source code - build type `RELEASE`: @@ -32,7 +32,7 @@ mkdir -p build cd build cmake .. -DVPP_HOME=<vpp dir>/build-root/install-vpp-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp-native/vpp make -sudo make install +cmake --build . -- install ``` VPP source code - build type `DEBUG`: @@ -42,7 +42,7 @@ mkdir -p build cd build cmake .. -DCMAKE_BUILD_TYPE=DEBUG -DVPP_HOME=<vpp dir>/build-root/install-vpp_debug-native/vpp -DCMAKE_INSTALL_PREFIX=<vpp src>/build-root/install-vpp_debug-native/vpp make -sudo make install +cmake --build . -- install ``` CMAKE variables: @@ -57,7 +57,7 @@ CMAKE variables: Build dependencies: -- VPP 20.01 +- VPP 22.02 - DEB packages (can be found <https://packagecloud.io/fdio/release/install):> - vpp - libvppinfra-dev @@ -65,11 +65,11 @@ Build dependencies: Runtime dependencies: -- VPP 20.01 +- VPP 22.02 - DEB packages (can be found <https://packagecloud.io/fdio/release/install):> - vpp - vpp-plugin-core - - vpp-plugin-dpdk (only to use DPDK compatible nics) + - vpp-plugin-dpdk (optional - only to use DPDK compatible nics) Hardware support (not mandatory): @@ -91,7 +91,7 @@ Detailed information for configuring VPP can be found at ### Setup the host for VPP -Hugepages must be enabled in the system. +It is preferable to have hugepages enabled in the system, although it is not a requirement: ```bash sudo sysctl -w vm.nr_hugepages=1024 @@ -163,7 +163,7 @@ interface. VPP can be started as a process or a service: -Start VPP as a service in Ubuntu 16.04+: +Start VPP as a service in Ubuntu 20.04+: ```bash sudo systemctl start vpp ``` @@ -299,22 +299,22 @@ vpp# set interface ip address TenGigabitEtherneta/0/1 2001::3/64 vpp# set interface state TenGigabitEtherneta/0/1 up ``` -Once the two forwarder are started, run the `ping_server` application on the +Once the two forwarder are started, run the `hicn-ping-server` application on the host where the forwarder B is running: ```bash -sudo ping_server -n b002::1 +sudo hicn-ping-server -n b002::1/128 -z memif_module ``` -Then `ping_client` on the host where forwarder B is running: +Then `hicn-ping-client` on the host where forwarder B is running: ```bash -sudo ping_client -n b002::1 +sudo hicn-ping-client -n b002::1 -z memif_module ``` ### Example: packet generator -The packet generator can be used to test the performace of the hICN plugin, as +The packet generator can be used to test the performance of the hICN plugin, as well as a tool to inject packet in a forwarder or network for other test use cases It is made of two entities, a client that inject interest into a vpp forwarder and a server that replies to any interest with the corresponding |