summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md221
1 files changed, 221 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..2e155c18
--- /dev/null
+++ b/README.md
@@ -0,0 +1,221 @@
+FD.IO CICN project: VPP plugin
+==============================
+
+The CICN forwarder
+
+## Quick Start ##
+```
+From the code tree root
+
+Using automake
+$ cd cicn-plugin
+$ autoreconf -i -f
+$ mkdir -p build
+$ cd build
+$ ../configure --with-plugin-toolkit
+OR, to omit UT code
+$ ../configure --with-plugin-toolkit --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
+```
+
+## 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.01
+
+Hardware dependencies:
+
+- [DPDK](http://DPDK.org/) 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](https://wiki.fd.io/view/VPP).
+
+##### Setup the host for VPP #####
+
+VPP requires the `uio` and `igb_uio` modules to be loaded in the kernel
+
+```
+$ sudo modprobe uio
+$ sudo modprobe igb_uio
+```
+Hugepages must be enabled in the system
+
+```
+$ sudo sysctl -w vm.nr_hugepages=1024
+```
+
+If the DPDK interface we want to assign to VPP is up, we must bring it down
+
+```
+$ sudo ifconfig <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 {
+ socket-mem 1024
+ dev 0000:08:00.0
+}
+```
+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 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
+
+```
+
+##### Configure VPP interfaces #####
+
+ICN communications run on top of IP and TCP, therefore we need to assign an IP address to the DPDK interface that enables IP connectivity through that interface
+
+``` 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
+```
+`GigabitEthernet0/8/0` is the name that VPP assigned to the DPDK interface. It must be replaced with the actual name of the DPDK interface ([`sudo vppctl show interfaces`](https://doCS.fd.io/vpp/17.01/clicmd_vnet_vnet.html#clicmd_show_interfaces) 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
+
+``` 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
+```
+
+- `10.0.0.1:33302` must be replaced with the IP address assigned to the DPDK interface in the previous step. The tcp port can be chosen as desired.
+- `10.0.0.2:33302` must be replaced with the IP address assigned to the remote host we want to connect to
+- `/cicn` 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:
+
+- `sudo vppctl cicn help`
+
+If `help` 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:
+
+- `sudo vppctl cicn show`
+
+##### 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
+ - `sudo vppctl cicn control param pit size <# of entries>`
+- PIT entry lifetime (default, min and max)
+ - `sudo vppctl cicn control param pit {dfltlife | minlife | maxlife} <seconds>`
+- FIB size
+ - `sudo vppctl cicn control param fib size <# of entries>`
+- CS size
+ - `sudo vppctl cicn control param cs size <# of entries>`
+
+Changes on PIT, FIB and CS can be made only before starting CICN.
+
+
+### License ###
+
+This software is distributed under the following license:
+
+```
+/*
+ * Copyright (c) 2017 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.
+ */
+```
+
+