View source for Cicn-plugin

= FD.IO CICN project: VPP plugin =

The CICN forwarder.

== Quick Start ==

=== Install the dependencies ===
For the CICN plugin, you need VPP 17.04. For that do the following:

==== Ubuntu ====
Add the repositories for VPP 17.04 and for the fd.io master branch. Edit the /etc/apt/sources.list.d/99fd.io.list file by running the following commands in a shell:
 $ echo "deb [trusted=yes] https://nexus.fd.io/content/repositories/fd.io.stable.1704.ubuntu.$(lsb_release -sc).main/ ./" \
          | sudo tee -a /etc/apt/sources.list.d/99fd.io.list
 $ 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


Set 17.04 as the priority version for CICN: edit the /etc/apt/preferences.d/99fd.io.pref file with your favorite editor and write the following:
 Package: vpp*
 Pin: version 17.04.2-release
 Pin-Priority: 1001

 Package: vpp-dpdk*
 Pin: version 17.02-vpp2
 Pin-Priority: 1001

Then update your repositories:
 $ sudo apt-get update


You now have two possibilities for installing the CICN plugin: from the packages or from source.

=== Install from repositories ===
 $ sudo apt-get install cicn-plugin


=== Compile the plugin from source ===
<pre>Pull the code from fd.io
$ git clone -b cicn-plugin/master  https://gerrit.fd.io/r/cicn cicn-plugin
$ cd cicn-plugin

Using automake 
$ cd cicn-plugin 
$ autoreconf -i -f
$ mkdir -p build 
$ cd build
$ ../configure
OR, to omit UT code
$ ../configure --without-cicn-test
$ make
$ sudo make install

Using cmake
$ cd cicn-plugin
$ mkdir -p build
$ cd build
$ cmake ..
Or, to omit UT code
$ cmake .. -DNO_UNIT_TEST=TRUE
$ make
$ sudo make install</pre>

== Introduction ==

The high-performance CCNx ICN forwarder as a plugin to VPP.

The plugin provides the following functionalities:

* Fast packet processing
* Interest aggregation
* Content caching

== Using CICN plugin ==

=== Platforms ===

CICN has been tested in:

* Ubuntu 16.04 LTS (x86_64)
* Ubuntu 14.04 LTS (x86_64)
* Debian Stable/Testing (2017-03-01)
* Red Hat Enterprise Linux 7
* CentOS 7

=== Dependencies ===

Build dependencies:

* VPP 17.04

Hardware dependencies:

* [http://DPDK.org/ DPDK] compatible nic

=== Getting started ===

In order to start, the CICN plugin requires a running instance of VPP and at least one DPDK compatible nic. The steps required to successfully start CICN are:

* Setup the host to run VPP
* Configure VPP to use DPDK compatible nics
* Start VPP
* Configure VPP interfaces
* Configure and start CICN

Detailed information for configuring VPP can be found at https://wiki.fd.io/view/VPP.

===== Setup the host for VPP =====

VPP requires the <code>uio</code> and <code>igb_uio</code> modules to be loaded in the kernel:

<pre>$ sudo modprobe uio
$ sudo modprobe igb_uio</pre>
Hugepages must be enabled in the system:

<pre>$ sudo sysctl -w vm.nr_hugepages=1024</pre>
If the DPDK interface we want to assign to VPP is up, we must bring it down:

<pre>$ sudo ifconfig &lt;interface_name&gt; down</pre>
===== 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:

<pre class="shell">unix {
  nodaemon
  log /tmp/vpp.log
  full-coredump
}

api-trace {
  on
}

api-segment {
  gid vpp
}

dpdk {
  socket-mem 1024
  dev 0000:08:00.0
}</pre>
Where <code>0000:08:00.0</code> must be replaced with the actual PCI address of the DPDK interface.

===== Start VPP =====

VPP can be started as a process or a service:

<pre class="shell">Start VPP as a service in Ubuntu 16.04
$ sudo systemctl start vpp

Start VPP as a service in Ubuntu 14.04
$ sudo service vpp start

Start VPP as a process in both 16.04 and 14.04
$ sudo vpp -c /etc/vpp/startup.conf
</pre>
===== Configure VPP interfaces =====

ICN communications run on top of IP and UDP (encap), therefore we need to assign an IP address to the DPDK interface that enables IP connectivity through that interface:

<pre class="shell">Set an IP address on the DPDK interface
$ sudo vppctl set int ip address GigabitEthernet0/8/0 10.0.0.1/24

Bring the interface up
$ sudo vppctl set int state GigabitEthernet0/8/0 up</pre>
<code>GigabitEthernet0/8/0</code> is the name that VPP assigned to the DPDK interface. It must be replaced with the actual name of the DPDK interface ([https://docs.fd.io/vpp/17.04/clicmd_vnet_vnet.html#clicmd_show_interfaces <code>sudo vppctl show interfaces</code>] shows the available interfaces in VPP).

===== Configure and start CICN =====

The following three commands enable CICN, set a face pointing to a remote host and add an entry in the FIB:

<pre class="shell">Start CICN plugin
$ sudo vppctl cicn enable

Create a face for the DPDK interface
$ sudo vppctl cicn cfg face add local 10.0.0.1:33302 remote 10.0.0.2:33302
Face ID: 1

Add a FIB entry
$ sudo vppctl cicn cfg fib add prefix /cicn face 1</pre>
* <code>10.0.0.1:33302</code> must be replaced with the IP address assigned to the DPDK interface in the previous step. The UDP port can be chosen as desired.
* <code>10.0.0.2:33302</code> must be replaced with the IP address assigned to the remote host we want to connect to.
* <code>/cicn</code> must be replaced with the ICN prefix to forward through face 1.

=== CICN commands ===

A full list of the available commands for CICN is available through:

* <code>sudo vppctl cicn help</code>

If <code>help</code> is passed as a paramenter to a CICN command, the output will display information about the syntax of the command.

===== CICN statistics =====

A fine grained set of statistic for the ongoing communication is available through:

* <code>sudo vppctl cicn show</code>

===== Setting PIT, FIB and CS parameters =====

If needed, it is possible to change the default values for the three CICN internal structures. The customizable parameters and the corresponding commands are:

* PIT size:
** <code>sudo vppctl cicn control param pit size &lt;# of entries&gt;</code>
* PIT entry lifetime (default, min and max):
** <code>sudo vppctl cicn control param pit {dfltlife | minlife | maxlife} &lt;seconds&gt;</code>
* FIB size:
** <code>sudo vppctl cicn control param fib size &lt;# of entries&gt;</code>
* CS size:
** <code>sudo vppctl cicn control param cs size &lt;# of entries&gt;</code>

Changes on PIT, FIB and CS can be made only before starting CICN.

== License ==

This software is distributed under the following license:

<pre>/*
 * Copyright (c) 2017 Cisco and/or its affiliates.
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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 &quot;AS IS&quot; 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.
 */</pre>