VNFs/DPPD-PROX/README

   1 ##
   2 ## Copyright (c) 2010-2020 Intel Corporation
   3 ##
   4 ## Licensed under the Apache License, Version 2.0 (the "License");
   5 ## you may not use this file except in compliance with the License.
   6 ## You may obtain a copy of the License at
   7 ##
   8 ##     http://www.apache.org/licenses/LICENSE-2.0
   9 ##
  10 ## Unless required by applicable law or agreed to in writing, software
  11 ## distributed under the License is distributed on an "AS IS" BASIS,
  12 ## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 ## See the License for the specific language governing permissions and
  14 ## limitations under the License.
  15 ##
  16
  17 Description
  18 -----------
  19 This is PROX, the Packet pROcessing eXecution engine, part of Intel(R)
  20 Data Plane Performance Demonstrators, and formerly known as DPPD-BNG.
  21 PROX is a DPDK-based application implementing Telco use-cases such as
  22 a simplified BRAS/BNG, light-weight AFTR... It also allows configuring
  23 finer grained network functions like QoS, Routing, load-balancing...
  24
  25 Compiling and running this application
  26 --------------------------------------
  27 This application supports DPDK 16.04, 16.11, 16.11.1, 17.02, 17.05, 17.08,
  28 17.11, 18.02, 18.05, 18.08, 18.11, 19.02, 19.05, 19.08, 19.11, 20.02 and
  29 20.05.
  30
  31 The following commands assume that the following variables have been set:
  32
  33 export RTE_SDK=/path/to/dpdk
  34 export RTE_TARGET=x86_64-native-linuxapp-gcc
  35
  36 IPSec is only supported in PROX starting from DPDK 17.11
  37 It will only be compiled if CONFIG_RTE_LIBRTE_PMD_AESNI_MB is
  38 set in DPDK .config. This also requires AESNI_MULTI_BUFFER_LIB_PATH to point to
  39 the multi-buffer library which can be downloaded from
  40 <https://github.com/01org/intel-ipsec-mb>.
  41 See doc/guides/cryptodevs/aesni_mb.rst within dpdk for more details
  42
  43 Example: DPDK 17.05 installation
  44 --------------------------------
  45 git clone http://dpdk.org/git/dpdk
  46 cd dpdk
  47 git checkout v17.05
  48 make install T=$RTE_TARGET
  49
  50 PROX compilation
  51 ----------------
  52 The Makefile with this application expects RTE_SDK to point to the
  53 root directory of DPDK (e.g. export RTE_SDK=/root/dpdk). If RTE_TARGET
  54 has not been set, x86_64-native-linuxapp-gcc will be assumed.
  55
  56 Running PROX
  57 ------------
  58 After DPDK has been set up, run make from the directory where you have
  59 extracted this application. A build directory will be created
  60 containing the PROX executable. The usage of the application is shown
  61 below. Note that this application assumes that all required ports have
  62 been bound to the DPDK provided igb_uio driver. Refer to the "Getting
  63 Started Guide - DPDK" document for more details.
  64
  65 Usage: ./build/prox [-f CONFIG_FILE] [-l LOG_FILE] [-p] [-o DISPLAY] [-v] [-a|-e] \
  66                 [-m|-s|-i] [-n] [-w DEF] [-q] [-k] [-d] [-z] [-r VAL] [-u] [-t]
  67         -f CONFIG_FILE : configuration file to load, ./prox.cfg by default
  68         -l LOG_FILE : log file name, ./prox.log by default
  69         -p : include PID in log file name if default log file is used
  70         -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none'
  71         -v verbosity : initial logging verbosity
  72         -a : autostart all cores (by default)
  73         -e : don't autostart
  74         -n : Create NULL devices instead of using PCI devices, useful together with -i
  75         -m : list supported task modes and exit
  76         -s : check configuration file syntax and exit
  77         -i : check initialization sequence and exit
  78         -u : Listen on UDS /tmp/prox.sock
  79         -t : Listen on TCP port 8474
  80         -q : Pass argument to Lua interpreter, useful to define variables
  81         -w : define variable using syntax varname=value
  82              takes precedence over variables defined in CONFIG_FILE
  83         -k : Log statistics to file "stats_dump" in current directory
  84         -d : Run as daemon, the parent process will block until PROX is not initialized
  85         -z : Ignore CPU topology, implies -i
  86         -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds,
  87                   screen refreshing will be disabled
  88
  89 While applications using DPDK typically rely on the core mask and the
  90 number of channels to be specified on the command line, this
  91 application is configured using a .cfg file. The core mask and number
  92 of channels is derived from this config. For example, to run the
  93 application from the source directory execute:
  94
  95   user@target:~$ ./build/prox -f ./config/nop.cfg
  96
  97 Provided example configurations
  98 -------------------------------
  99 PROX can be configured either as the SUT (System Under Test) or as the
 100 Traffic Generator. Some example configuration files are provided, both
 101 in the config directory to run PROX as a SUT, and in the gen directory
 102 to run it as a Traffic Generator.
 103 A quick description of these example configurations is provided below.
 104 Additional details are provided in the example configuration files.
 105
 106 Basic configurations, mostly used as sanity check:
 107 - config/nop.cfg
 108 - config/nop-rings.cfg
 109 - gen/nop-gen.cfg
 110
 111 Simplified BNG (Border Network Gateway) configurations, using different
 112 number of ports, with and without QoS, running on the host or in a VM:
 113 - config/bng-4ports.cfg
 114 - config/bng-8ports.cfg
 115 - config/bng-qos-4ports.cfg
 116 - config/bng-qos-8ports.cfg
 117 - config/bng-1q-4ports.cfg
 118 - config/bng-ovs-usv-4ports.cfg
 119 - config/bng-no-cpu-topology-4ports.cfg
 120 - gen/bng-4ports-gen.cfg
 121 - gen/bng-8ports-gen.cfg
 122 - gen/bng-ovs-usv-4ports-gen.cfg
 123
 124 Light-weight AFTR configurations:
 125 - config/lw_aftr.cfg
 126 - gen/lw_aftr-gen.cfg
 127