diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 19 | ||||
| -rw-r--r-- | docs/README.md | 49 | ||||
| -rw-r--r-- | docs/etc/requirements.txt | 27 | ||||
| -rw-r--r-- | docs/source/_static/css/rules.css | 19 | ||||
| -rw-r--r-- | docs/source/_static/fd-io_red_white.png | bin | 0 -> 39010 bytes | |||
| -rw-r--r-- | docs/source/_static/fdio_logo.png | bin | 0 -> 3708 bytes | |||
| -rw-r--r-- | docs/source/apps.md | 304 | ||||
| -rw-r--r-- | docs/source/conf.py | 176 | ||||
| -rw-r--r-- | docs/source/control.md | 241 | ||||
| -rw-r--r-- | docs/source/hicn-light.md | 300 | ||||
| -rw-r--r-- | docs/source/index.rst | 15 | ||||
| -rw-r--r-- | docs/source/interface.md | 358 | ||||
| -rw-r--r-- | docs/source/lib.md | 116 | ||||
| -rw-r--r-- | docs/source/transport.md | 126 | ||||
| -rw-r--r-- | docs/source/utils.md | 325 | ||||
| -rw-r--r-- | docs/source/vpp-plugin.md | 373 |
16 files changed, 2448 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..69fe55ecf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..c99cf879b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,49 @@ + +Building Documents + +These instructions show how documentation sources are built. + +To build your files, you can either Create a Virtual Environment using +virtualenv, which installs all the required applications for you. + +Create a Virtual Environment using virtualenv +============================ + +For more information on how to use the Python virtual environment check +out https://packaging.python.org/guides/installing-using-pip-and-virtualenv + +Get the Documents +------------------------------ + +For example start with a clone of the vpp. + +$ git clone https://gerrit.fd.io/r/hicn +$ cd hicn + +Install the virtual environment +---------------------------------------------- + +$ python3 -m pip install --user virtualenv +$ python3 -m virtualenv env +$ source env/bin/activate +$ pip install -r docs/etc/requirements.txt +$ cd docs + +Which installs all the required applications into it's own, isolated, +virtual environment, so as to not interfere with other builds that may +use different versions of software. + +Build the html files +---------------------------- + +Be sure you are in your hicn/docs directory, since that is where Sphinx will +look for your conf.py file, and build the documents into an index.html file + +$ make html + +View the results +------------------------ + +If there are no errors during the build process, you should now have an +index.html file in your hicn/docs/build/html directory, which you can +then view in your browser. diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt new file mode 100644 index 000000000..5b037c693 --- /dev/null +++ b/docs/etc/requirements.txt @@ -0,0 +1,27 @@ +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 diff --git a/docs/source/_static/css/rules.css b/docs/source/_static/css/rules.css new file mode 100644 index 000000000..ceb0d5abc --- /dev/null +++ b/docs/source/_static/css/rules.css @@ -0,0 +1,19 @@ +/* Allows for tables to be center-aligned */ +table.center-align-table td { + text-align: center; +} + +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + diff --git a/docs/source/_static/fd-io_red_white.png b/docs/source/_static/fd-io_red_white.png Binary files differnew file mode 100644 index 000000000..9cf6d36f9 --- /dev/null +++ b/docs/source/_static/fd-io_red_white.png diff --git a/docs/source/_static/fdio_logo.png b/docs/source/_static/fdio_logo.png Binary files differnew file mode 100644 index 000000000..3c362b278 --- /dev/null +++ b/docs/source/_static/fdio_logo.png diff --git a/docs/source/apps.md b/docs/source/apps.md new file mode 100644 index 000000000..eefb68be1 --- /dev/null +++ b/docs/source/apps.md @@ -0,0 +1,304 @@ +# Application examples using hICN stack + +## Introduction + +higet and hicn-http-proxy are two application examples that use hicn stack. + +## Using hICN Application Examples + +### Dependencies + +Build dependencies: + +- c++14 ( clang++ / g++ ) +- CMake 3.5 or higher + +Basic dependencies: + +- OpenSSL +- pthreads +- libevent +- libparc +- libcurl +- libhicntransport + +## Executables + +### hicn-http-proxy + +`hicn-http-proxy` is a reverse proxy which can be used for augmenting the performance of a legacy HTTP/TCP server +by making use of hICN. It performs the following operations: + +- Receives a HTTP request from a hICN client +- Forwards it to a HTTP server over TCP +- Receives the response from the server and send it back to the client + +```bash +hicn-http-proxy [HTTP_PREFIX] [OPTIONS] + +HTTP_PREFIX: The prefix used for building the hicn names. + +Options: +-a <server_address> = origin server address +-p <server_port> = origin server port +-c <cache_size> = cache size of the proxy, in number of hicn data packets +-m <mtu> = mtu of hicn packets +-P <prefix> = optional most significant 16 bits of hicn prefix, in hexadecimal format + +Example: +./hicn-http-proxy http://webserver -a 127.0.0.1 -p 8080 -c 10000 -m 1200 -P b001 +``` + +The hICN names used by the hicn-http-proxy for naming the HTTP responses are composed in the following way, +starting from the most significant byte: + +- The first 2 bytes are the prefix specified in the -P option +- The next 6 bytes are the hash (Fowler–Noll–Vo non-crypto hash) of the locator (in the example `webserver`, without the `http://` part) +- The last 8 bytes are the hash (Fowler–Noll–Vo non-crypto hash) of the http request corresponding to the response being forwarded back to the client. + +### higet + +Higet is a non-interactive HTTP client working on top oh hICN. + +```bash +higet [option]... [url] +Options: +-O <output_path> = write documents to <output_file>. Use '-' for stdout. +-S = print server response. +-P = optional first 16 bits of hicn prefix, in hexadecimal format + +Example: +./higet -P b001 -O - http://webserver/index.html +``` + +The hICN names used by higet for naming the HTTP requests are composed the same way as described in [hicn-http-proxy](#hicn-http-proxy). + +### How To Setup A Simple HTTP Client-Server Scenario using the hicn-http-proxy + +We consider the following topology, consisting on two linux VM which are able to communicate through an IP network (you can also use containers or physical machines): + +```text +|client (10.0.0.1/24; 9001::1/64)|======|server (10.0.0.2/24; 9001::2/64)| +``` + +Install the hICN suite on two linux VM. This tutorial makes use of Ubuntu 18.04, but it could easily be adapted to other platforms. +You can either install the hICN stack using binaries or compile the code. In this tutorial we will make use of docker container and binaries packages. + +The client will use of the hicn-light forwarder, which is lightweight and tailored for devices such as android and laptops. +The server will use the hicn-plugin of vpp, which guarantees better performances and it is the best choice for server applications. + +Keep in mind that on the same system the stack based on vpp forwarder cannot coexist with the stack based on hicn light. + +For running the hicn-plugin at the server there are two main alternatives: + +- Use a docker container +- Run the hicn-plugin directly in a VM or Bare Metal Server + +#### Docker + +Install docker in the server VM: + +```bash +server$ sudo apt-get update +server$ sudo apt-get install \ + apt-transport-https \ + ca-certificates \ + curl \ + gnupg-agent \ + software-properties-common + +server$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - +server$ sudo add-apt-repository \ + "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ + $(lsb_release -cs) \ + stable" +server$ sudo apt-get update +server$ sudo apt-get install docker-ce docker-ce-cli containerd.io +``` + +Run the hicn-http-proxy container. Here we use a public server [example.com](example.com) as origin: + +```bash +server$ docker run -e ORIGIN_ADDRESS=example.com \ + -e ORIGIN_PORT=80 \ + -e CACHE_SIZE=10000 \ + -e HICN_MTU=1200 \ + -e FIRST_IPV6_WORD=c001 \ + -e HICN_PREFIX=http://webserver \ + --privileged \ + --name vhttpproxy \ + -d icnteam/vhttpproxy +``` + +Create a hicn private network: + +```bash +server$ GATEWAY=192.168.0.254 +server$ docker network create --subnet 192.168.0.0/24 --gateway ${GATEWAY} hicn-network +``` + +Connect the proxy container to the hicn network: + +```bash +server$ docker network connect hicn-network vhttpproxy +``` + +Connect the hicn network to the vpp forwarder: + +```bash +server$ IP_ADDRESS=$(docker inspect -f "{{with index .NetworkSettings.Networks \"hicn-network\"}}{{.IPAddress}}{{end}}" vhttpproxy) +server$ INTERFACE=$(docker exec -it vhttpproxy ifconfig | grep -B 1 ${IP_ADDRESS} | awk 'NR==1 {gsub(":","",$1); print $1}') +server$ docker exec -it vhttpproxy ip addr flush dev ${INTERFACE} +server$ docker exec -it vhttpproxy ethtool -K ${INTERFACE} tx off rx off ufo off gso off gro off tso off +server$ docker exec -it vhttpproxy vppctl create host-interface name ${INTERFACE} +server$ docker exec -it vhttpproxy vppctl set interface state host-${INTERFACE} up +server$ docker exec -it vhttpproxy vppctl set interface ip address host-${INTERFACE} ${IP_ADDRESS}/24 +server$ docker exec -it vhttpproxy vppctl ip route add 10.0.0.0/24 via ${GATEWAY} host-eth1 +``` + +Set the punting: + +```bash +server$ PORT=12345 +server$ docker exec -it vhttpproxy vppctl hicn punting add prefix c001::/16 intfc host-${INTERFACE} type udp4 src_port ${PORT} dst_port ${PORT} +``` + +Docker containers are cool, but sometimes they do not allow you to do simple operations like expose ports while the container is already running. But we have a workaround for this :) + +```bash +server$ sudo iptables -t nat -A DOCKER -p udp --dport ${PORT} -j DNAT --to-destination ${IP_ADDRESS}:${PORT} +server$ sudo iptables -t nat -A POSTROUTING -j MASQUERADE -p udp --source ${IP_ADDRESS} --destination ${IP_ADDRESS} --dport ${PORT} +server$ sudo iptables -A DOCKER -j ACCEPT -p udp --destination ${IP_ADDRESS} --dport ${PORT} +``` + +In the client, install the hicn stack: + +```bash +client$ sudo apt-get install -y hicn-light hicn-apps +``` + +Create a configuration file for the hicn-light forwarder. Here we are configuring UDP faces: + +```bash +client$ mkdir -p ${HOME}/etc +client$ LOCAL_IP="10.0.0.2" # Put here the actual IPv4 of the local interface +client$ LOCAL_PORT="12345" +client$ REMOTE_IP="10.0.0.1" # Put here the actual IPv4 of the remote interface +client$ REMOTE_PORT="12345" +client$ cat << EOF > ${HOME}/etc/hicn-light.conf +add listener udp list0 ${LOCAL_IP} ${LOCAL_PORT} +add connection udp conn0 ${REMOTE_IP} ${REMOTE_PORT} ${LOCAL_IP} ${LOCAL_PORT} +add route conn0 c001::/16 1 +EOF +``` + +Run the hicn-light forwarder + +```bash +client$ sudo /usr/bin/hicn-light-daemon --daemon --capacity 1000 --log-file ${HOME}/hicn-light.log --config ${HOME}/etc/hicn-light.conf +``` + +Run the http client [higet](#higet) and print the http response on stdout: + +```bash +client$ /usr/bin/higet -O - http://webserver/index.html -P c001 +``` + +#### Host/VM + +You can install the hicn-plugin of vpp on your VM and directly use DPDK compatible nics, forwarding hicn packets directly over the network. DPDK compatible nics can be used inside a container as well. + +```bash +server$ sudo apt-get install -y hicn-plugin vpp-plugin-dpdk hicn-apps-memif +``` + +It will install all the required deps (vpp, hicn apps and libraries compiled for communicating with vpp using shared memories). Configure VPP following the steps described [here](https://github.com/FDio/hicn/blob/master/hicn-plugin/README.md#configure-vpp). + +This tutorial assumes you configured two interfaces in your server VM: + +- One interface which uses the DPDK driver, to be used by VPP +- One interface which is still owned by the kernel + +The DPDK interface will be used for connecting the server with the hicn client, while the other interface will guarantee connectivity to the applications running in the VM, including the hicn-http-proxy. If you run the commands: + +```bash +server$ sudo systemctl restart vpp +server$ vppctl show int +``` + +The output must show the dpdk interface owned by VPP: + +```text + Name Idx State MTU (L3/IP4/IP6/MPLS) Counter Count +GigabitEthernetb/0/0 1 down 9000/0/0/0 +local0 0 down 0/0/0/0 +``` + +If the interface is down, bring it up and assign the correct ip address to it: + +```bash +server$ vppctl set int state GigabitEthernetb/0/0 up +server$ vppctl set interface ip address GigabitEthernetb/0/0 9001::1/64 +``` + +Take care of replacing the interface name (`GigabitEthernetb/0/0`) with the actual name of your interface. + +Now enable the hicn plugin and set the punting for the hicn packets: + +```bash +server$ vppctl hicn control start +server$ vppctl hicn punting add prefix c001::/16 intfc GigabitEthernetb/0/0 type ip +``` + +Run the hicn-http-proxy app: + +```bash +server$ sudo /usr/bin/hicn-http-proxy -a example.com -p 80 -c 10000 -m 1200 -P c001 http://webserver +``` + +Configure the client for sending hicn packets without any udp encapsulation: + +```bash +client$ mkdir -p ${HOME}/etc +client$ LOCAL_IP="9001::2" +client$ REMOTE_IP="9001::1" +client$ cat << EOF > ${HOME}/etc/hicn-light.conf +add listener hicn lst 0::0 +add punting lst c001::/16 +add listener hicn list0 ${LOCAL_IP} +add connection hicn conn0 ${REMOTE_IP} ${LOCAL_IP} +add route conn0 c001::/16 1 +EOF +``` + +Restart the forwarder: + +```bash +client$ sudo killall -INT hicn-light-daemon +client$ sudo /usr/bin/hicn-light-daemon --daemon --capacity 1000 --log-file ${HOME}/hicn-light.log --config ${HOME}/etc/hicn-light.conf +``` + +Retrieve a web page: + +```bash +client$ /usr/bin/higet -O - http://webserver/index.html -P c001 +``` + +## License + +This software is distributed under the following license: + +```text +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. +``` diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..bb6715564 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,176 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# -- Project information ----------------------------------------------------- + +project = u'Hybrid ICN' +copyright = u'(c) 2017-2020 Cisco and/or its affiliates.' +author = u'Luca Muscariello' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'20.01' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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'] + +# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading' +# rather than 'path/to/file:heading' +autosectionlabel_prefix_document = True +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None +html_logo = '_static/fd-io_red_white.png' + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +def setup(app): + app.add_stylesheet('css/rules.css') + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'hicndoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'hicn.tex', u'hicn Documentation', + u'Luca Muscariello', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'hicn', u'hicn Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'hicn', u'hicn Documentation', + author, 'hicn', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] diff --git a/docs/source/control.md b/docs/source/control.md new file mode 100644 index 000000000..0940fff67 --- /dev/null +++ b/docs/source/control.md @@ -0,0 +1,241 @@ +# Sysrepo plugin for hicn-plugin (2019) + +These plugins serve as a data management agent. They provide yang models via +NETCONF to allow the management of hicn-light, and hicn-plugin which runs in VPP +instance from out-of-box. + +## Software Requirement + +- VPP + +- sysrepo + +- hicn-plugin + +- hicn-light + +## hICN yang model + +You can install the yang model using the following bash script: +``` +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 +``` +hicn.yang can be found in the yang-model. It consists of two container nodes: +hicn-conf and hicn-state. One is used to hold the configuration data (i.e., +hicn-conf) and one for providing the state data (i.e., hicn-state). The +hicn-conf has one node, params, which contains the hICN configuration +parameters. 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. + +To setup the startup configuration you can use the following script: +``` +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: +``` +<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> +``` +As can be seen, it contains the leaves of the params 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: +``` +<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> + +<route-del xmlns="urn:sysrepo:hicn"> + <prefix0>10</prefix0> + <prefix1>20</prefix1> + <len>30</len> +</route-del> + +<route-nhops-add xmlns="urn:sysrepo:hicn"> + <prefix0>10</prefix0> + <prefix1>20</prefix1> + <len>30</len> + <face_ids0>40</face_ids0> + <face_ids1>50</face_ids1> + <face_ids2>60</face_ids2> + <face_ids3>70</face_ids3> + <face_ids4>80</face_ids4> + <face_ids5>90</face_ids5> + <face_ids6>100</face_ids6> + <n_faces>110</n_faces> +</route-nhops-add> + +<route-nhops-del xmlns="urn:sysrepo:hicn"> + <prefix0>10</prefix0> + <prefix1>20</prefix1> + <len>30</len> + <faceid>40</faceid> +</route-nhops-del> + +<face-ip-params-get xmlns="urn:sysrepo:hicn"> + <faceid>10</faceid> +</face-ip-params-get> + +<face-ip-add xmlns="urn:sysrepo:hicn"> + <nh_addr0>10</nh_addr0> + <nh_addr1>20</nh_addr1> + <swif>30</swif> +</face-ip-add> + +<face-ip-del xmlns="urn:sysrepo:hicn"> + <faceid>0</faceid> +</face-ip-del> + +<punting-add xmlns="urn:sysrepo:hicn"> + <prefix0>10</prefix0> + <prefix1>20</prefix1> + <len>30</len> + <swif>40</swif> +</punting-add> + +<punting-del xmlns="urn:sysrepo:hicn"> + <prefix0>10</prefix0> + <prefix1>20</prefix1> + <len>30</len> + <swif>40</swif> +</punting-del> +``` + +## Run the plugin + +Firstly, verify the plugin and binary libraries are located correctly, then run +the vpp through (service vpp start). Next, run the sysrepo daemon (sysrepod), +for debug mode: sysrepo -d -l 4 which runs with high verbosity. Then, run the +sysrepo plugin (sysrepo-plugind), for debug mode: sysrep-plugind -d -l 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 + you can modify the configuration but it needs an xml configuration input +``` +<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 +``` + <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 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 19.01 VPP stable and sysrepo 0.7.7.
\ No newline at end of file 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. +``` diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..43a380b5f --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,15 @@ +Hybrid ICN software distribution +================================= + +.. toctree:: + + lib + vpp-plugin + transport + hicn-light + interface + control + utils + apps + + diff --git a/docs/source/interface.md b/docs/source/interface.md new file mode 100644 index 000000000..c7168ef23 --- /dev/null +++ b/docs/source/interface.md @@ -0,0 +1,358 @@ +# Face manager : Interfaces + +## Overview + +The architecture of the face manager is built around the concept of interfaces, +which allows for a modular and extensible deployment. + +Interfaces are used to implement in isolation various sources of information +which help with the construction of faces (such as network interface and service +discovery), and with handling the heterogeneity of host platforms. + + +### Platform and supported interfaces + +Currently, Android, Linux and MacOS are supported through the following +interfaces: + +- hicn-light [Linux, Android, MacOS, iOS] + An interface to the hicn-light forwarder, and more specifically to the Face + Table and FIB data structures. This component is responsible to effectively + create, update and delete faces in the forwarder, based on the information + provided by third party interfaces, plus adding default routes for each of + the newly created face. The communication with the forwarder is based on the + hicn control library (`libhicnctrl`). + +- netlink [Linux, Android] + The default interface on Linux systems (including Android) to communicate + with the kernel and receive information from various sources, including link + and address information (both IPv4 and IPv6) about network interfaces. + +- android\_utility [Android only] + Information available through Netlink is limited with respect to cellular + interfaces. This component allows querying the Android layer through SDK + functions to get the type of a given network interface (Wired, WiFi or + Cellular). + +- bonjour [Linux, Android] + This component performs remote service discovery based on the bonjour + protocol to discover a remote hICN forwarder that might be needed to + establish overlay faces. + +- network\_framework [MacOS, iOS] + + This component uses the recommended Network framework on Apple devices, + which provided all required information to query faces in a unified API: + link and address information, interface types, and bonjour service + discovery. + + +### Architectural overview + +#### Facelets + +TODO: +- Key attributes (netdevice and protocol family) +- Facelet API + +#### Events + +TODO + +#### Facelet cache & event scheduling + +TODO: + - Facelet cache + - Joins + - How synchronization work + +### Interface API + +TODO + +## Developing a new interface + +### Dummy template + +The face manager source code includes a template that can be used as a skeleton +to develop new faces. It can be found in `src/interface/dummy/dummy.{h,c}`. Both +include guard and specific interface functions are prefixed by a (short) +identifier which acts as a namespace for interface specific code (in our case +the string 'dummy\_'). + +Registration and instanciation of the different interfaces is currently done at +compile time in the file `src/api.c`, and the appropriate hooks to use the dummy +interface are avaialble in the code between `#if 0/#endif` tags. + +#### Interface template header; configuration parameters + +All interfaces have a standard interface defined in `src/interface.{h,c}`, and +as such the header file is only used to specify the configuration parameters of +the interface, if any. + +In the template, these configuration options are empty: +``` +/* + * Configuration data + */ +typedef struct { + /* ... */ +} dummy_cfg_t; +``` + +#### Overview of the interface template + +The file starts with useful includes: +- the global include `<hicn/facemgr.h>` : this provides public facing elements + of the face manager, such the standard definition of faces (`face_t` from + `libhicnctrl`), helper classes (such as `ip_address_t` from `libhicn`), etc. +- common.h +- facelet.h : facelets are the basic unit of communication between the face +manager and the different interfaces. They are used to construct the faces +incrementally. +- interface.h : the parent class of interfaces, such as the current dummy +interface. + +Each interface can hold a pointer to an internal data structure, which is +declared as follows: +``` +/* + * Internal data + */ +typedef struct { + /* The configuration data will likely be allocated on the stack (or should + * be freed) by the caller, we recommend to make a copy of this data. + * This copy can further be altered with default values. + */ + dummy_cfg_t cfg; + + /* ... */ + + int fd; /* Sample internal data: file descriptor */ +} dummy_data_t; +``` + +We find here a copy of the configuration settings (which allows the called to +instanciate the structure on the stack), as well as a file descriptor +(assuming most interfaces will react on events on a file descriptor). + +The rest of the file consists in the implementation of the interface, in +particular the different function required by the registration of a new +interface to the system. They are grouped as part of the `interface_ops_t` data +structure declared at the end of the file: + +``` +interface\_ops\_t dummy\_ops = { + .type = "dummy", + .initialize = dummy_initialize, + .finalize = dummy_finalize, + .callback = dummy_callback, + .on_event = dummy_on_event, +}; +``` + +The structure itself is declared and documented in `src/interface.h` +``` +/** + * \brief Interface operations + */ +typedef struct { + /** The type given to the interfaces */ + char * type; + /* Constructor */ + int (*initialize)(struct interface\_s * interface, void * cfg); + /* Destructor */ + int (*finalize)(struct interface_s * interface); + /* Callback upon file descriptor event (iif previously registered) */ + int (*callback)(struct interface_s * interface); + /* Callback upon facelet events coming from the face manager */ + int (*on_event)(struct interface_s * interface, const struct facelet_s * facelet); +} interface\_ops\_t; +``` + +Such an interface has to be registered first, then one (or multiple) instance(s) +can be created (see `src/interface.c` for the function prototypes, and +`src/api.c` for their usage). + +- interface registration: + +``` +extern interface\_ops\_t dummy\_ops; + +/* [...] */ + +rc = interface\_register(&dummy\_ops); +if (rc < 0) + goto ERR_REGISTER; +``` + +- interface instanciation: + +``` +#include "interfaces/dummy/dummy.h" + +/* [...] */ + +rc = facemgr_create_interface(facemgr, "dummy0", "dummy", &facemgr->dummy); +if (rc < 0) { + ERROR("Error creating 'Dummy' interface\n"); + goto ERR_DUMMY_CREATE; +} +``` + +#### Implementation of the interface API + +We now quickly go other the different functions, but their usage will be better +understood through the hands-on example treated in the following section. + +In the template, the constructor is the most involved as it need to: + +- initialize the internal data structure: + +``` + dummy_data_t * data = malloc(sizeof(dummy_data_t)); + if (!data) + goto ERR_MALLOC; + interface->data = data; +``` + +- process configuration parameters, eventually setting some default values: + +``` + /* Use default values for unspecified configuration parameters */ + if (cfg) { + data->cfg = *(dummy_cfg_t *)cfg; + } else { + memset(&data->cfg, 0, sizeof(data->cfg)); + } +``` + +- open an eventually required file descriptor + +For the sake of simplicity, the current API only supports a single file +descriptor per-interface, and it has to be created in the constructor, and +set as the return value so as to be registered by the system, and added to the +event loop for read events. A return value of 0 means the interface does not +require any file descriptor. As usual, a negative return value indicates an +error. + +``` + data->fd = 0; + + /* ... */ + + /* + * We should return a negative value in case of error, and a positive value + * otherwise: + * - a file descriptor (>0) will be added to the event loop; or + * - 0 if we don't use any file descriptor + */ + return data->fd; +``` + +While support for multiple file descriptors might be added in the future, an +alternative short-term implementation might consider the instanciation of +multiple interface, as is done for Bonjour in the current codebase, in +`src/api.c`. + +Data reception on the file descriptor will get the callback function called, in +our case `dummy_callback`. Finally, the destructor `dummy_finalize` should close +an eventual open file descriptor. + +In order to retrieve the internal data structure, that should in particular +store such a file descriptor, all other function but the constructor can +dereference it from the interface pointer they receive as parameter: + +``` +dummy\_data\_t * data = (dummy\_data\_t*)interface->data; +``` + +#### Raising and receiving events + +An interface will receive events in the form of a facelet through the `*_on_event` +function. It can then use the facelet API we have describe above to read +information about the face. + +As this information is declared const, the interface can either create a new +facelet (identified by the same netdevice and protocol family), or eventually +clone it. + +The facelet event can then be defined and raised to the face maanger for further +processing through the following code: +``` + facelet_set_event(facelet, EVENT_TYPE_CREATE); + interface_raise_event(interface, facelet); +``` + +Here the event is a facelet creation (`EVENT_TYPE_CREATE`). The full facelet API +and the list of possible event types is available in `src/facelet.h` + + +#### Integration in the build system + +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 example + +#### Overview + +In order to better illustrate the development of a new interface, we will +consider the integration of a sample server providing a signal instructing the +face manager to alternatively use either the WiFi or the LTE interface. The code +of this server is available in the folder `examples/updownsrv/`, and the +corresponding client code in `examples/updowncli`. + +Communication between client and server is done through unix sockets over an +abstract namespace (thereby not using the file system, which would cause issues +on Android). The server listens for client connections, and periodically +broadcast a binary information to all connected clients, in the form of one byte +equal to either \0 (which we might interpret as enable LTE, disable WiFi), or \1 +(enable WiFi, disable LTE). + +Our objective is to develop a new face manager interface that would listen to +such event in order to update the administrative status of the current faces. +This would thus alternatively set the different interfaces admnistratively up +and down (which takes precedence over the actual status of the interface when +the forwarder establishes the set of available next hops for a given prefix). +The actual realization of such queries will be ultimately performed by the +hicn-light interface. + +#### Sample server and client + +In the folder containing the source code of hICN, the following commands allow +to run the sample server: + +``` +cd ctrl/facemgr/examples/updownsrv +make +./updownsrv +``` + +The server should display "Waiting for clients..." + +Similar commands allow to run the sample client: +``` +cd ctrl/facemgr/examples/updowncli +make +./updowncli +``` + +The client should display "Waiting for server data...", then every couple of +seconds display either "WiFi" or "LTE". + +#### Facemanager interface + +An example illustrating how to connect to the dummy service from `updownsrv` is +provided as the `updown` interface in the facemgr source code. + +This interface periodically swaps the status of the LTE interface up and down. +It is instanciated as part of the facemgr codebase when the code is compiled +with the ``-DWITH_EXAMPLE_UPDOWN` cmake option. + + + diff --git a/docs/source/lib.md b/docs/source/lib.md new file mode 100644 index 000000000..58f23b510 --- /dev/null +++ b/docs/source/lib.md @@ -0,0 +1,116 @@ + +The Hybrid ICN Core Library +============================== + +## Introduction + +libhicn provides a support library coded in C designed to help developers embed +Hybrid ICN (hICN) functionalities in their applications (eg. forwarder, socket +API, etc.). Its purpose is to follow the hICN specification for which it +provides a reference implementation, abstracting the user from all internal +mechanisms, and offering an API independent of the packet format (eg. IPv4 or +IPv6). The library is designed to be portable across both desktop and +mobile platforms, and we currently aim at supporting Linux, Android, OSX and +iOS, by writing the necessary adapters to realize hICN functionality in +userspace according to the available APIs and permissions that each system +offers. + +The library consists in several layers: +- the core library (hicn.h) provides a standard hICN packet format, as well as +an API allowing manipulation of packet headers; +- an hICN helper, allowing an hICN stack to be built in userspace in a portable +way, based on TUN devices and accessible though file descriptors; +- a network layer allow the sending an receiving of hICN packets on those file +descriptors, implementing both source and destination address translation as +required by the hICN mechanisms; +- finally, a "transport" API allows the forging of dummy interest and data +packets. + +A commandline interface (hicnc) is also provided that uses the library and can +for instance be used as a test traffic generator. This interface can be run as +either a consumer, a producer, or a simple forwarder. + +## Folder content + +CMakeLists.txt CMkake global build file +doc Package documentation +README.md This file +src + base.h Base definitions for hICN implementation + CMakeLists.txt CMake library build file + common.{h,c} Harmonization layer across supported platforms + compat.{h,c} Compatibility layer for former API + error.{h,c} Error management files + header.h hICN header definitions + hicn.h Master include file + mapme.{h,c} MAP-Me : anchorless producer mobility mechanisms + name.{h,c} hICN naming conventions and name processing + IP helpers + ops.{h,c} Protocol-independent hICN operations + protocol/* Protocol headers + protocol-dependent implementations + protocol.h Common file for protocols + +## Using libhicn + +### Platforms ### + +libhicn has 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 +- Android 8 +- iOS 12 +- macOS 10.12 +- Windows 10 + +Other platforms and architectures may work. + +### Dependencies + +Build dependencies: + +- c11 ( clang / gcc ) +- CMake 3.4 + +Basic dependencies: None + +## Installation + +You can either use released packages, or compile libhicn from sources. + +### Release mode + +mkdir build +cd build +cmake .. +make +sudo make install + +### Debug mode + +mkdir debug +cd debug +cmake .. -DCMAKE_BUILD_TYPE=Debug +make +sudo make install + +## 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. +``` diff --git a/docs/source/transport.md b/docs/source/transport.md new file mode 100644 index 000000000..e7fc267ee --- /dev/null +++ b/docs/source/transport.md @@ -0,0 +1,126 @@ +Libtransport: data transport library for hICN +==================================================== + +## Introduction ## + +This 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. +- Transport protocols (RAAQM, CBR, RTP) +- 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 ## + +- libparc +- libmemif (linux only, if compiling with VPP support) +- libasio + +### Ubuntu 16.04 and Ubuntu 18.04 ### + +```bash + $ echo "deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.master.ubuntu.$(lsb_release -sc).main/ ./" \ + | sudo tee -a /etc/apt/sources.list.d/99fd.io.list + $ sudo apt-get install libparc libasio-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: + +- DEB packages: + - vpp + - vpp-lib + - vpp-dev + +You can get them either from from the vpp packages ot the source code. Check the [VPP wiki](https://wiki.fd.io/view/VPP) for instructions. + +Libmemif is in the vpp-lib and vpp-dev packages. + +### Mac OSX ### + +We recommend to use [HomeBrew](https://brew.sh/) for installing the libasio dependency: + +```bash + $ brew install asio +``` + +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 +``` + +Libparc will be installed by default under `/usr/local/lib` and `/usr/local/include`. + +Since VPP does not support MAC OS, the hicn-plugin connector is not built. + +## Build The library ## + +From the project root folder: + +```bash + $ cd libtransport + $ mkdir build && cd build + $ cmake .. + $ make +``` +### Compile options ### + +The build process can be customized with the following options: + +- `CMAKE_INSTALL_PREFIX`: The path where you want to install the library. +- `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`. + +Install the library +------------------- + +For installing the library, from the cmake build folder: + +```bash + $ sudo make install +``` + +## Supported platforms + +- Ubuntu 16.04 LTS (x86_64) +- Ubuntu 18.04 LTS (x86_64) +- Debian Stable/Testing +- Red Hat Enterprise Linux 7 +- CentOS 7 +- Android 8 +- iOS 12 +- macOS 10.12 +- Windows 10 + +## 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. +```
\ No newline at end of file diff --git a/docs/source/utils.md b/docs/source/utils.md new file mode 100644 index 000000000..0d81ea426 --- /dev/null +++ b/docs/source/utils.md @@ -0,0 +1,325 @@ +# Utility applications + +## Introduction + +hicn-ping-server, hicn-ping-client and hiperf are three utility applications for testing and benchmarking stack. + +## Using hICN Utils applications + +### Platforms + +hicn-light has been tested in: + +- Ubuntu 16.04 / 18.04 (x86_64) +- Debian Testing +- Centos 7 +- MacOSX 10.12 +- Android +- iOS + +### Dependencies + +Build dependencies: + +- c++14 ( clang++ / g++ ) +- CMake 3.4 + +Basic dependencies: + +- ppenSSL +- pthreads +- libevent +- libparc +- libhicntransport + +## Executables + +The utility applications are a set of binary executables consisting of a client/server ping applications (hicn-ping-server and hicn-ping-client) and a hicn implementation of hicn (hiperf). + +### hicn-ping-server + +The command `hicn-ping-server` runs the server side ping application. hicn-ping-server can be executed +with the following options: + +``` +usage: hicn-ping-server [options] + +Options: +-s <content_size> = object content size (default 1350B) +-n <hicn_name> = hicn name (default b001::/64) +-f = set tcp flags according to the flag received (default false) +-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 = quite, not prints (default false) +-d = daemon mode +-H = help + +Example: +hicn-ping-server -n c001::/64 +``` + +### hicn-ping-client + +The command `hicn-ping-client` runs the client side ping application. hicn-ping-client can be executed +with the following options: + +``` +usage: hicn-ping-client [options] + +Options: +-i <ping_interval> = ping interval in microseconds (default 1000000ms) +-m <max_pings> = maximum number of pings to send (default 10) +-s <source_port> = source port (default 9695) +-d <destination_port> = destination port (default 8080) +-t <ttl> = set packet ttl (default 64) +-O = open tcp connection (three way handshake) (default false) +-S = send always syn messages (default false) +-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, not prints (default false) +-H = help + +Example: +hicn-ping-client -n c001::1 +``` + +### hiperf + +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: + +``` +usage: hiperf [-S|-C] [options] [prefix|name] + +Options: +-D = run as a daemon +-R = run RTC protocol (client or server) +-f <ouptup_log_file> = output log file path + +Server specific: +-A <download_size> = size of the content to publish. This is not the size of the packet (see -s for it) +-s <payload_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 the packets +-y <hash_algorithm> = use the selected hash algorithm for calculating manifest digests +-p <password> = password for p12 keystore +-x = produce a content of <download_size>, then after downloading it produces a new content of + <download_size> without resetting the suffix to 0 +-B <bitrate> = bitrate for RTC producer, to be used with the -R option, in kbps (example: 64kbps) + +Client specific: +-b <beta_parameter> = RAAQM beta parameter +-d <drop_factor_parameter> = RAAQM drop factor parameter +-M = store the content downloaded (default false) +-W <window_size> = use a fixed congestion window for retrieving the data +-c <certificate_path> = path of the producer certificate to be used for verifying the origin of the packets received +-i <stats_interval> = show the statistics every <stats_interval> milliseconds +-v = Enable verification of received data + +Example: +hiperf -S c001::/64 +``` + +## How To Benchmark Client-Server Throughput using hiperf + +### hicn-light-daemon + +This tutorial will explain how to configure a simple client-server topology and retrieve network measurements using the hiperf utility. + +We consider this simple topology, consisting on two linux VM which are able to communicate through an IP network (you can also use containers or physical machines): + +```text +|client (10.0.0.1/24; 9001::1/64)|======|server (10.0.0.2/24; 9001::2/64)| +``` + +Install the hICN suite on two linux VM. This tutorial makes use of Ubuntu 18.04, but it could easily be adapted to other platforms. +You can either install the hICN stack using binaries or compile the code. In this tutorial we will build the code from source. + +```bash +$ curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash +$ apt-get install -y git \ + cmake \ + build-essential \ + libasio-dev \ + libcurl4-openssl-dev \ + libparc-dev \ + --no-install-recommends + +$ mkdir hicn-suite && cd hicn-suite +$ git clone https://github.com/FDio/hicn hicn-src +$ mkdir hicn-build && cd hicn-build +$ cmake ../hicn-src -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../hicn-install -DBUILD_APPS=ON +$ make -j 4 install +$ export HICN_ROOT=${PWD}/../hicn-install +``` + +It should install the hICN suite under hicn-install. + +#### hICN stack based on hicn-light forwarder with UDP faces + +##### Server Configuration + +Create a configuration file for the hicn-light forwarder. Here we are configuring UDP faces. + +```bash +server$ mkdir -p ${HICN_ROOT}/etc +server$ LOCAL_IP="10.0.0.1" # Put here the actual IPv4 of the local interface +server$ LOCAL_PORT="12345" +server$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf +add listener udp list0 ${LOCAL_IP} ${LOCAL_PORT} +EOF +``` + +Start the hicn-light forwarder + +```bash +server$ sudo ${HICN_ROOT}/bin/hicn-light-daemon --daemon --capacity 0 --log-file ${HICN_ROOT}/hicn-light.log --config ${HICN_ROOT}/etc/hicn-light.conf +``` + +We set the forwarder capacity to 0 because we want to measure the end-to-end performance without retrieving any data packet from intermediate caches. + +Run the [hiperf](#hiperf) server. + +```bash +server$ ${HICN_ROOT}/bin/hiperf -S b001::/64 +``` + +The hiperf server will register the prefix b001::/64 on the local forwarder and will reply with pre-allocated data packet. In this test we won't consider segmentation and reassembly cost. + +##### Client Configuration + +Create a configuration file for the hicn-light forwarder at the client. Here we are configuring UDP faces. + +```bash +client$ mkdir -p ${HICN_ROOT}/etc +client$ LOCAL_IP="10.0.0.2" # Put here the actual IPv4 of the local interface +client$ LOCAL_PORT="12345" +client$ REMOTE_IP="10.0.0.1" # Put here the actual IPv4 of the remote interface +client$ REMOTE_PORT="12345" +client$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf +add listener udp list0 ${LOCAL_IP} ${LOCAL_PORT} +add connection udp conn0 ${REMOTE_IP} ${REMOTE_PORT} ${LOCAL_IP} ${LOCAL_PORT} +add route conn0 b001::/16 1 +EOF +``` + +Run the hicn-light forwarder + +```bash +client$ sudo ${HICN_ROOT}/bin/hicn-light-daemon --daemon --capacity 1000 --log-file ${HICN_ROOT}/hicn-light.log --config ${HICN_ROOT}/etc/hicn-light.conf +``` + +Run the [hiperf](#hiperf) client: + +```bash +client$ ${HICN_ROOT}/bin/hiperf -C b001::1 -W 50 +EOF +``` + +This will run the client with a fixed window of 50 interests. + +#### Using hicn-light forwarder with hICN faces + +For sending hICN packets directly over the network, using hicn faces, change the configuration of the two forwarders and restart them. + +##### Server Configuration + +```bash +server$ mkdir -p ${HICN_ROOT}/etc +server$ LOCAL_IP="9001::1" +server$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf +add listener hicn lst 0::0 +add punting lst b001::/16 +add listener hicn list0 ${LOCAL_IP} +EOF +``` + +#### Client Configuration + +```bash +client$ mkdir -p ${HICN_ROOT}/etc +client$ LOCAL_IP="9001::2" +client$ REMOTE_IP="9001::1" +client$ cat << EOF > ${HICN_ROOT}/etc/hicn-light.conf +add listener hicn lst 0::0 +add punting lst b001::/16 +add listener hicn list0 ${LOCAL_IP} +add connection hicn conn0 ${REMOTE_IP} ${LOCAL_IP} +add route conn0 b001::/16 1 +EOF +``` + +### vpp based hicn-plugin + +Compile the hicn stack enabling the [vpp](https://github.com/FDio/vpp) support. + +In this example we will do a local hiperf client-server communication. + +```bash +$ curl -s https://packagecloud.io/install/repositories/fdio/release/script.deb.sh | sudo bash +$ apt-get install -y git \ + cmake \ + build-essential \ + libasio-dev \ + libcurl4-openssl-dev \ + libparc-dev \ + vpp libvppinfra vpp-plugin-core vpp-dev python3-ply python python-ply \ + --no-install-recommends + +$ mkdir hicn-suite && cd hicn-suite +$ git clone https://github.com/FDio/hicn hicn-src +$ mkdir hicn-build && cd hicn-build +$ cmake ../hicn-src -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_APPS=ON -DBUILD_HICNPLUGIN=ON +$ sudo make -j 4 install +$ export HICN_ROOT=${PWD}/../hicn-install +``` + +Make sure vpp is running: + +```bash +$ sudo systemctl restart vpp +``` + +Run the hicn-plugin: + +```bash +$ vppctl hicn control start +``` + +Run hiperf server: + +```bash +$ hiperf -S b001::/64 +``` + +Run hiperf client: + +```bash +$ hiperf -C b001::1 -W 300 +``` + +## 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. +``` diff --git a/docs/source/vpp-plugin.md b/docs/source/vpp-plugin.md new file mode 100644 index 000000000..ed9d122d6 --- /dev/null +++ b/docs/source/vpp-plugin.md @@ -0,0 +1,373 @@ +VPP plugin +============================== + +The hICN-plugin forwarder + +## Introduction ## + +A high-performance Hybrid ICN forwarder as a plugin to VPP. + +The plugin provides the following functionalities: + + - Fast packet processing + - Interest aggregation + - Content caching + - Forwarding strategies + +## Quick Start ## +``` +From the code tree root + +(VPP installed with DEB pkg) +$ cd hicn-plugin +$ mkdir -p build +$ cd build +$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr +$ make +$ sudo make install + +(VPP source code -- build type RELEASE) +$ cd hicn-plugin +$ 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 + +(VPP source code -- build type DEBUG) +$ cd hicn-plugin +$ 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 variables: +- CMAKE_INSTALL_PREFIX -- set the install directory for the hicn-plugin. This is the common path to the lib folder containing vpp_plugins and vpp_api_test_plugins folders. Default is /usr/local. +- VPP_HOME -- set the directory containing the include and lib directories of vpp. +``` + +## Using hICN plugin ## + +### Platforms ### + +hICN-plugin has 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 + + +### Dependencies ### + +Build dependencies: + +- VPP 19.08 + - DEB packages (can be found https://packagecloud.io/fdio/release/install): + - vpp + - libvppinfra-dev + - vpp-dev + +Runtime dependencies: + +- VPP 19.08 + - DEB packages (can be found https://packagecloud.io/fdio/release/install): + - vpp + - vpp-plugin-core + - vpp-plugin-dpdk (only to use DPDK compatible nics) + +Hardware support (not mandatory): + +- [DPDK](http://DPDK.org/) compatible nics + +## Getting started ## +In order to start, the hICN plugin requires a running instance of VPP +The steps required to successfully start hICN are: + +- Setup the host to run VPP +- Configure VPP to use DPDK compatible nics +- Start VPP +- Configure VPP interfaces +- Configure and start hICN + +Detailed information for configuring VPP can be found at [https://wiki.fd.io/view/VPP](https://wiki.fd.io/view/VPP). + +### Setup the host for VPP ### + +Hugepages must be enabled in the system + +``` +$ sudo sysctl -w vm.nr_hugepages=1024 +``` + +In order to use a DPDK interface, the `uio` and `uio_pci_generic` or `vfio_pci` modules need to be loaded in the kernel + +``` +$ sudo modprobe uio +$ sudo modprobe uio_pci_generic +$ sudo modprobe vfio_pci +``` + +If the DPDK interface we want to assign to VPP is up, we must bring it down + +``` +$ sudo ifconfig <interface_name> down +``` +or +``` +$ sudo ip link set <interface_name> down +``` + +### Configure VPP ### +The file /etc/VPP/startup.conf contains a set of parameters to setup VPP at startup. +The following example sets up VPP to use a DPDK interfaces: + +``` shell +unix { + nodaemon + log /tmp/vpp.log + full-coredump +} + +api-trace { + on +} + +api-segment { + gid vpp +} + +dpdk { + dev 0000:08:00.0 +} + +plugins { + ## Disable all plugins by default and then selectively enable specific plugins + plugin default { disable } + plugin dpdk_plugin.so { enable } + plugin acl_plugin.so { enable } + plugin memif_plugin.so { enable } + plugin hicn_plugin.so { enable } + + ## Enable all plugins by default and then selectively disable specific plugins + # plugin dpdk_plugin.so { disable } + # plugin acl_plugin.so { disable } +} +``` +Where `0000:08:00.0` must be replaced with the actual PCI address of the DPDK interface + +### Start VPP ### + +VPP can be started as a process or a service: + +``` shell +Start VPP as a service in Ubuntu 16.04 +$ sudo systemctl start vpp + +Start VPP as a process in both 16.04 +$ sudo vpp -c /etc/vpp/startup.conf + +``` + +### Configure hICN plugin ### +The hICN plugin can be configured either using the VPP command-line interface (CLI), through a configuration file or through the VPP binary api + +#### hICN plugin CLI #### + +The CLI commands for the hICN plugin start all with the hicn keyword. To see the full list of command available type: + +``` shell +$ sudo vppctl +vpp# hicn ? +``` + +`hicn control param`: configures the internal parameter of the hICN plugin. This command must be run before hicn control start. + +``` +hicn control param { pit { size <entries> | { dfltlife | minlife | maxlife } <seconds> } | cs {size <entries> | app <portion to reserved to app>} } + <entries> :set the maximum number of entry in the PIT or CS. Default for PIT is 131072, for CS is 4096. CS size cannot be grater than PIT size. Moreover CS size must be smaller than (# of vlib buffer - 8196). + <seconds> :set the default, maximum or minimum lifetime of pit entries. Default value 2s (default), 0.2s (minumum), 20s (maximum) + <portion to reserved to app> :set the portion of CS to reserve to application running locally on the forwarder. Default is 30% of the cs size. +``` + +`hicn control start`: starts the hICN plugin in VPP. + +`hicn control stop` : stops the hICN plugin in VPP. Currently not supported. + +`hicn face app` : manipulates producer and consumer application faces in the forwarder. + +``` +hicn face app {add intfc <sw_if> {prod prefix <hicn_prefix> cs_size <size_in_packets>} {cons}} | {del <face_id>} + <sw_if> :software interface existing in vpp on top of which to create an application face + <hicn_prefix> :prefix to bound to the producer application face. Only content matching the prefix will be allowed through such face. + <size_in_packets> :content store size associated to the producer face. + <face_id> :id of the face to remove + +``` + +`hicn face ip`: manipulates ip application faces in the forwarder. + +``` +hicn face ip {add [local <src_address>] remote <dst_address> intfc <sw_if>} | {del id <face_id>} + <src_address> :the IPv4 or IPv6 local IP address to bind to (not mandatory, if not specified the local address is one of the address assigned to sw_if) + <dst_address> :the IPv4 or IPv6 address of the remote system + <sw_if> :software interface on thop of which we create the face + <face_id> :id of the face to remove +``` + + +`hicn face show`: list the available faces in the forwarder. + +``` +hicn face show [<face_id>| type <ip/udp>] + <face_id> :face id of which we want to display the informations + <ip/udp> :shows all the ip or udp faces available +``` + +`hicn face udp`: manipulates udp application faces in the forwarder. + +``` +hicn face udp {add src_addr <src_address> port <src_port > dst_addr <dst_address> port <dst_port>} intfc <sw_if> | {del id <face_id>} + <src_address> :the IPv4 or IPv6 local IP address to bind to + <src_port> :the local UDP port + <dst_address> :the IPv4 or IPv6 address of the remote system + <dst_port> :the remote UDP port + <sw_if> :software interface on thop of which we create the face + <face_id> :id of the face to remove + +``` + +`hicn fib`: manipulates hicn fib entries. + +``` +hicn fib {{add | delete } prefix <prefix> face <face_id> } | set strategy <strategy_id> prefix <prefix> + <prefix> :prefix to add to the FIB + <face_id> :face id to add as nexto hop in the FIB entry + <strategy_id> :set a strategy for the corresponding prefix +``` + +`hicn pgen client`: set an vpp forwarder as an hicn packet generator client + +``` +hicn pgen client fwd <ip|hicn> src <addr> n_ifaces <n_ifaces> name <prefix> lifetime <interest-lifetime> intfc <data in-interface> max_seq <max sequence number> n_flows <number of flows> + <ip|hicn> :set if the underlying forwarder is configured as ip or hicn + <src_addr> :source address to use in the interests, i.e., the locator for routing the data packet back + <n_ifaces> :set the number of ifaces (consumer faces) to emulate. If more than one, each interest is sent <n_ifaces> times, each of it with a different source address calculated from <src_addr> + <prefix> :prefix to use to generate hICN names + <interest-lifetime> :lifetime of the interests + <data in-interface> :interface through which the forwarder receives data + <max sequence number> :max the sequence number to use in the interest. Cycling between 0 and this value + <number of flows> :emulate multiple flows downloaded in parallel +``` + +`hicn pgen server`: set an vpp forwarder as an hicn packet generator client + +``` +hicn pgen server fwd <ip|hicn> name <prefix> intfc <interest in-interface> size <payload_size> + <ip|hicn> :set if the underlying forwarder is configured as ip or hicn + <prefix> :prefix to use to reply to interest + <interest in-interface> :interface through which the forwarder receives interest + <payload_size> :size of the data payload +``` + +`hicn punting`: manipulates punting rules + +``` +hicn punting {add|delete} prefix <prefix> intfc <sw_if> {type ip | type <udp4|udp6> src_port <src_port> dst_port <dst_port>} + <prefix> :prefix to punt to the hICN plugin + <sw_if> :software interface where to apply the punting + <ip|udp4|udp6> :creates a punting rule for hICN packet encapsulated into a ip4/6|udp tunnel or for regular hicn packet + <src_port> :source port of the udp4/6 tunnel + <dst_port> :destination port of the udp4/6 tunnel +``` + +`hicn show`: show forwarder information. +``` +hicn show [detail] [strategies] + <detail> :shows additional details as pit,cs entries allocation/deallocation + <strategies> :shows only the available strategies int he forwarder +``` + +`hicn strategy mw set`: set the weight for a face. + +``` +hicn strategy mw set prefix <prefix> face <face_id> weight <weight> + <prefix> :prefix to which the strategy applies + <face_id> :id of the face to set the weight + <weight> :weight +``` + +#### hICN plugin configuration file #### + +A configuration can be use to setup the hicn plugin when vpp starts. The configuration file is made of a list of CLI commands. In order to set vpp to read the configuration file, the file /etc/vpp/startup.conf needs to be modified as follows: + +``` +unix { + nodaemon + log /tmp/vpp.log + full-coredump + startup-config <path to configuration file> +} +``` +#### hICN plugin binary api #### + +The binary api, or the vapi, can be used as well to configure the hicn plugin. For each cli command there is a corresponding message in the binary api. The list of messages is available in the file hicn.api (located in hicn/hicn-plugin/src/) + +### Example: consumer and producer Ping ### + +In this example, we connect two vpp forwarders, A and B, each of them running the hicn plugin. On top of forwarder A we run the ping_client application, on top of forwarder B we run the ping_server application. Each application connects to the underlying forwarder through a memif-interface. The two forwarders are connected through a dpdk link. + +#### Forwarder A #### + +```shell +$ sudo vppctl +vpp# set interface ip address TenGigabitEtherneta/0/0 2001::2/64 +vpp# set interface state TenGigabitEtherneta/0/0 up +vpp# hicn control start +vpp# hicn face ip add local 2001::2 remote 2001::3 intfc TenGigabitEtherneta/0/0 +vpp# hicn fib add prefix b002::1/64 face 0 +vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/0 type ip +``` + +#### Forwarder B #### + +```shell +$ sudo vppctl +vpp# set interface ip address TenGigabitEtherneta/0/1 2001::3/64 +vpp# set interface state TenGigabitEtherneta/0/1 up +vpp# hicn control start +vpp# hicn punting add prefix b002::1/64 intfc TenGigabitEtherneta/0/1 type ip +``` + +Once the two forwarder are started, run the ping_server application on the host where the forwarder B is running + +```shell +$ sudo ping_server -n b002::1 +``` + +and the client on the host where forwarder B is running + +```shell +$ sudo ping_client -n b002::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. +``` |
