diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 221 |
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. + */ +``` + + |