aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: cdf793e78691043e0ebbbb74639a7252804c1e36 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
UDPI
========================

## Introduction

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.

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.

## Quick Start ##(in CentOS cmake = cmake3, gcc = devtoolset-7, follow vpp)
```
From the code tree root

(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

(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 related, 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) 2018-2019 Intel 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.

```