path: root/src/dpi_plugin_doc.md
diff options
Diffstat (limited to 'src/dpi_plugin_doc.md')
1 files changed, 107 insertions, 0 deletions
diff --git a/src/dpi_plugin_doc.md b/src/dpi_plugin_doc.md
new file mode 100644
index 0000000..fc069c0
--- /dev/null
+++ b/src/dpi_plugin_doc.md
@@ -0,0 +1,107 @@
+# DPI plugin for VPP {#dpi_plugin_doc}
+## Overview
+DPI plugin can identify and analyze the traffic running on networks in real time.
+It can be used on many use cases, such as Web Application Firewall,
+Policy based routing, Intrusion Detection System, Intrusion Prevention System, etc.
+The main use case for current approach would be identification of cooperating traffic
+for an established TCP connection (i.e. traffic that is not intentionally disguised)
+to support application-based QoS.
+## Design
+The DPI plugin leverage Hyperscan to perform regex matching.
+Hyperscan is a high-performance multiple regex matching library.
+Please refer to below for details:
+Below is the brief design:
+1. Provides a default APPID database for detection.
+2. Support TCP connection state tracking.
+3. Support TCP segments reassembly on the fly, which handles out-of-order tcp segments and overlapping segments.
+ It means that we do not need to reassembly segments first, then dedect applicaion,
+ and then fragment segments again, which helps to improve performance.
+4. Support Hyperscan Stream mode, which can detect one rule straddling into some tcp segments.
+ It means that if there is a rule "abcde", then "abc" can be in packet 1,
+ and "de" can be in packet 2.
+5. Configure static dpi flows with 5-tuple and VRF-aware, and supports both ipv4 and ipv6 flows.
+ These flows will first try to HW offload to NIC based on DPDK rte_flow mechanism
+ and vpp/vnet/flow infrastructure.
+ If failed, then will create static SW flow mappings.
+ Each flow configuration will create two HW or SW flow mappings, i.e. for forward and reverse traffic.
+ And both flow mappings will be mapped to the same dpi flow.
+ Dynamically create new SW mapping and aging out mechanism will be added later.
+ "dpi flow [add | del] "
+ "[src-ip <ip-addr>] [dst-ip <ip-addr>] "
+ "[src-port <port>] [dst-port <port>] "
+ "[protocol <protocol>] [vrf-id <nn>]",
+ "dpi tcp reass flow_id <nn> <enable|disable> "
+ "[ <client | server | both> ]",
+ "dpi set flow-offload hw <interface-name> rx <flow-id> [del]",
+ "dpi set ip4 flow-bypass <interface> [del]",
+6. When HW flow offload matched, packets will be redirected to DPI plugin with dpi flow_id in packet descriptor.
+ If not, packets will be bypassed to DPI plugin from ip-input, and then lookup SW flow mapping table.
+7. Then will detect layer 7 applications.
+ This first patch only detect sub protocls within SSL/TLS.
+ 1). Identify SSL/TLS certificate message and subsequent segments.
+ 2). Scan SSL/TLS certificate message through hyperscan, and get application id if matched.
+ 3). If maximum packets for this flow are checked and not found matched application, the detection will end up.
+## Hyperscan Installation
+Hyperscan can be installed from packages directly on below OS:
+ Ubuntu 16.04.03
+ Ubuntu 18.04 and later version
+ Fedora 27 and later version
+ openSUSE rolling-release Tumbleweed and later version
+If you cannot install Hyperscan from packages directly,
+you can build and install it from the source code.
+Below are steps to build and install Hyperscan on Ubuntu 16.04:
+1).Install binary prerequisites
+apt-get install cmake ragel
+apt-get install libboost-dev
+apt-get install python-dev libbz2-dev
+2).Download Hyperscan sources
+wget https://github.com/intel/hyperscan/archive/v5.0.0.tar.gz
+tar -xf v5.0.0.tar.gz
+3).Download boost headers
+wget https://dl.bintray.com/boostorg/release/1.68.0/source/boost_1_68_0.tar.gz
+tar -xf boost_1_68_0.tar.gz
+cp -r boost_1_68_0/boost hyperscan-5.0.0/include
+4).Build and install Hyperscan shared library.
+ Just follow the instruction from here. Compilation can take a long time.
+cd hyperscan-5.0.0
+mkdir build
+cd build
+cmake -DBUILD_SHARED_LIBS=true ..
+make install
+## Multi-Thread Support
+Since generated bytecode database is read only, you can run multiple cores
+to utilize the byte database to scale.