aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md189
1 files changed, 179 insertions, 10 deletions
diff --git a/README.md b/README.md
index bb6f9b0..eb41715 100644
--- a/README.md
+++ b/README.md
@@ -6,23 +6,192 @@ UDPI
The UDPI (Universal Deep Packet Inspection) project is a reference framework to build a high performance solution
for Deep Packet Inspection, integrated with the general purpose FD.io VPP stack.
It leverages industry regex matching library to provide a rich set of features,
-which can be used in IPS/IDS, Web Firewall and similar applications.
+ which can be used in IPS/IDS, Web Firewall and similar applications.
-For more information on UDPI and its features please visit the
-[UDPI website](https://wiki.fd.io/view/UDPI)
+ For more information on UDPI and its features please visit the
+ [UDPI website](https://wiki.fd.io/view/UDPI)
## Changes
-Details of the changes leading up to this version of UDPI can be found under
-@ref release notes.
+ Details of the changes leading up to this version of UDPI can be found under
+ @ref release notes.
+## Quick Start ##
+```
+From the code tree root
-## Getting started
+(VPP installed with DEB or RPM pkg)
+$ cd udpi-plugin
+$ mkdir -p build
+$ cd build
+$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr #(add "-DCMKAE_INSTALL_LIBDIR=lib" on centos and it's releated)
+$ make package
-Make sure you have added FD.io repository using https://packagecloud.io/fdio/release/
-installation script.
-You should have a sight on the release package, the package name may be different depending on the distribution.
-(ex: vpp-plugins.deb for VPP 19.01 and vpp-plugin-core.deb and vpp-plugin-dpdk.deb in 19.04)
+(VPP source code -- build type RELEASE)
+$ cd udpi-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 #(add "-DCMKAE_INSTALL_LIBDIR=lib" on centos and it's releated)
+$ make
+$ sudo make install
+(VPP source code -- build type DEBUG)
+$ cd udpi-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 #(add "-DCMKAE_INSTALL_LIBDIR=lib" on centos and it's releated)
+$ make
+$ sudo make install
+CMAKE variables:
+- CMKAE_INSTALL_LIBDIR -- set the library directory. In CentOS, it is lib or lib64, in debian and it's releated, it is lib/x86_64-linux-gnu
+- CMAKE_INSTALL_PREFIX -- set the install directory for the udpi-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 udpi plugin ##
+
+### Platforms ###
+
+udpi-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:
+
+- Hyperscan
+
+- VPP 19.08
+ - DEB packages (can be found https://packagecloud.io/fdio/release/install):
+ - libvppinfra-dev
+ - vpp-dev
+
+Running 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 udpi plugin requires a running instance of VPP
+The steps required to successfully start udpi are:
+
+- Setup the host to run VPP
+- Configure VPP to use DPDK compatible nics
+- Start VPP
+- Configure VPP interfaces
+- Configure and start udpi
+
+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
+
+ ## Enable all plugins by default and then selectively disable specific plugins
+}
+```
+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 udpi plugin ###
+The udpi plugin can be configured either using the VPP command-line interface (CLI), through a configuration file or through the VPP binary api
+
+#### udpi plugin CLI ####
+
+The CLI commands for the udpi plugin start all with the udpi keyword. To see the full list of command available type:
+...(to be added)
+
+## 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.
+
+```