************************************************************************
Overview
************************************************************************

  This is an integration example of ixEngine with VPP as data-plane.
  It contains two nodes:  "flowtable" and "dpi" and its architecture
  is depicted in the below diagram.

                                   ___
                                  /   \
                                 /     \
                                |  NIC  |
                                 \     /
                                  \___/
                                    |
                                    |
                                    v
                      +----------------------------+
                      |         DPDK-input         |
                      +----------------------------+
                                    |
                                    |
                                    v
                              +------------+
                        +-----| Flow Table |
                        |     +------------+
                        |           |
                        |           | (non-offloaded)
    (offloaded packets) |           v
                        |        +-----+
                        |        | DPI |
                        |        +-----+
                        |           |
                        +---------->|
                                    |
                                    v
                      +----------------------------+
                      |        ethernet-input      |
                      +----------------------------+
                                    |
                                    |
                                    v
                                   ...

************************************************************************
VPP Version
************************************************************************

  This example was written and tested using VPP 21.10 version on
  UBUNTU 20.04 LTS, with additional flowtable and dpi plugins support.

  VPP example is divided into:
    flowtable node:     examples/vpp_integration/vpp_plugins/flowtable
    dpi node:           examples/vpp_integration/vpp_plugins/dpi


************************************************************************
Flowtable node
************************************************************************

* Description:
  The flowtable plugin uses ixEngine flow-level API to construct a
  stateful flow management functionality in a VPP node.

* Objective:
  Provides flow classification and associates to each identified flow a
  context that can be further enriched by another node or an external
  application.

  The objective is to be adaptable and suitable for any stateful
  use-case such as load-balancing, firewall, etc.

  Compared to a basic classifier, it also provides:
    * A flow context which can be updated with external information
    * Flow traffic offload
    * Flow lifetime management

************************************************************************
dpi node
************************************************************************

* Description:
  The dpi plugin integrates the ixEngine libraries in stream mode and
  provide flow classification results for the processed packets.

************************************************************************
Build
************************************************************************

* Get the VPP source code from git repository:
  $ git clone https://gerrit.fd.io/r/vpp -b stable/2110
  $ cd vpp

* Expose the SDK directory:
  $ export DPI_SDK=<PATH_TO_IXENGINE_SDK>

* Patching the dpdk:
 To ensure all packets from a same flow are dispatched to the same
 DPI worker, symmetric RSS hardware hash feature should be enabled.
 To activate it, we have to patch the code of the dpdk vpp plugin
 in vpp/src/plugins/dpdk.

  $ git apply $DPI_SDK/src/examples/vpp_integration/dpdk.patch

* Build VPP dependencies and packages (see vpp/README.txt):
  $ ./extras/vagrant/build.sh

* Install the Mandatory Packages on the system (including dev packages):
  $ sudo apt-get install \
            ./build-root/vpp-plugin-core_21.10.*.deb \
            ./build-root/vpp-plugin-dpdk_21.10.*.deb \
            ./build-root/vpp_21.10.*.deb \
            ./build-root/libvppinfra_21.10*.deb \
            ./build-root/libvppinfra-dev_21.10*.deb \
            ./build-root/vpp-dev_21.10.*.deb \
            ./build-root/python3-vpp-api_21.10.*.deb

* Build flowtable and dpi plugins
  $ cd $DPI_SDK/src/examples/vpp_integration/vpp_plugins
  $ make

* Install flowtable and dpi plugins
  $ cd $DPI_SDK/src/examples/vpp_integration/vpp_plugins
  $ sudo make install

************************************************************************
Build cleanup
************************************************************************
* Uninstall the Packages:
  $ sudo apt-get remove --purge vpp* libvppinfra*

* Cleanup flowtable and dpi plugins
  $ cd $DPI_SDK/src/examples/vpp_integration/vpp_plugins
  $ make clean

************************************************************************
Simple VPP Configuration
************************************************************************

* Configuration files:
  After VPP installation, the VPP configuration file can be found in:
    $ ls /etc/vpp/startup.conf

* Choosing monothreaded or multithreaded mode.
  By default, VPP runs in monothreaded mode. To run in multithreaded
  mode, the following lines should be added to the "cpu" section of
  the vpp configuration file:

    cpu {
        ...
        main-core 1
        workers 4
        ...
    }

  In this case, vpp will use 1 core for the management and four for
  running the nodes.

* Maximum number of flows
  The maximum number of flows managed by the flowtable plugin (default
  16777216) can be configured through the configuration file:

    flowtable {
        max-flows 33554432
    }

* Memory heap size
  The size of the memory heap required to store the plugins structures
  depends greatly on the maximum number of flows and the number of
  workers:
    * 7GB for the default number of flows (16777216) and 8 workers
    * 12GB for 33554432 flows and 8 workers

    memory {
        ## Set the main heap size, default is 1G
        main-heap-size 12G
    }

************************************************************************
Running VPP example
************************************************************************

* Set shared libraries path
  The flowtable and dpi plugins are using ixEngine shared libraries to
  performe packet classification.
    $ export DPI_SDK=<PATH_TO_IXENGINE_SDK>
    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$DPI_SDK/lib

* Launching the vpp application:
  To run the application from the instalation directory:
    $ sudo vpp -c /etc/vpp/startup.conf

* Create Routes between the subnets:
    $ sudo vppctl
  vpp# set interface ip address FortyGigabitEthernet3b/0/0 192.168.1.1/24
  vpp# set interface ip address FortyGigabitEthernet3b/0/1 192.168.2.1/24

  vpp# set interface state FortyGigabitEthernet3b/0/0 up
  vpp# set interface state FortyGigabitEthernet3b/0/1 up

  vpp# ip route add 16.0.0.0/8 via 192.168.1.3 FortyGigabitEthernet3b/0/0
  vpp# ip route add 48.0.0.0/8 via 192.168.2.3 FortyGigabitEthernet3b/0/1

* Configure both flowtable and dpi nodes:
  Use CLI to establishe the graph, that is the linking between the
  flowtable node and the input interfaces, between flowtable and dpi
  nodes and the linking with the next node in the graph. By default,
  flowtable is linked with dpi node and the next node is ethernet-input
  but no input interface is configured.

  vpp# flowtable add interface FortyGigabitEthernet3b/0/0
  vpp# flowtable add interface FortyGigabitEthernet3b/0/1

************************************************************************
CLI commands
************************************************************************

  For the flowtable node:
    vpp# flowtable add interface <Interface> [next-node <Node>]
      Adds an interface as packet source (input node) for this node
      and/or configures the next node in the graph.

    vpp# flowtable delete interface <Interface>
      Removes an interface from being a packet source (input node) for
      this node.

    vpp# flowtable dpi [enable|disable]
      Enable/Disable the forwarding of packets to the DPI node. Default
      enabled.

    vpp# flowtable stats [enable|disable]
      Enable/Disable statistic aggregations. Default disabled.

    vpp# flowtable show-stats
      Print current statistic aggregations.

    vpp# flowtable info
      Shows Flowtable plugin related informations.

    vpp# flowtable log [enable|disable]
      Enable/disable debug information logging for the flowtable module.
      By default, the Logging is disabled by the DEBUG compilation
      directive.

  For the dpi node:
    vpp# dpi add next-node <Node>
      Configures the next node in the graph. Default is "ethernet-input".

    vpp# dpi info
      Shows DPI plugin related informations.

    vpp# dpi log [enable|disable]
      Enable or disable debug information logging for the dpi module.
      By default, the Logging is disabled by the DEBUG compilation
      directive.
