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 and 19.11.
  29
  30 The following commands assume that the following variables have been set:
  31
  32 export RTE_SDK=/path/to/dpdk
  33 export RTE_TARGET=x86_64-native-linuxapp-gcc
  34
  35 IPSec is only supported in PROX starting from DPDK 17.11
  36 It will only be compiled if CONFIG_RTE_LIBRTE_PMD_AESNI_MB is
  37 set in DPDK .config. This also requires AESNI_MULTI_BUFFER_LIB_PATH to point to
  38 the multi-buffer library which can be downloaded from
  39 <https://github.com/01org/intel-ipsec-mb>.
  40 See doc/guides/cryptodevs/aesni_mb.rst within dpdk for more details
  41
  42 Example: DPDK 17.05 installation
  43 --------------------------------
  44 git clone http://dpdk.org/git/dpdk
  45 cd dpdk
  46 git checkout v17.05
  47 make install T=$RTE_TARGET
  48
  49 PROX compilation
  50 ----------------
  51 The Makefile with this application expects RTE_SDK to point to the
  52 root directory of DPDK (e.g. export RTE_SDK=/root/dpdk). If RTE_TARGET
  53 has not been set, x86_64-native-linuxapp-gcc will be assumed.
  54
  55 Running PROX
  56 ------------
  57 After DPDK has been set up, run make from the directory where you have
  58 extracted this application. A build directory will be created
  59 containing the PROX executable. The usage of the application is shown
  60 below. Note that this application assumes that all required ports have
  61 been bound to the DPDK provided igb_uio driver. Refer to the "Getting
  62 Started Guide - DPDK" document for more details.
  63
  64 Usage: ./build/prox [-f CONFIG_FILE] [-l LOG_FILE] [-p] [-o DISPLAY] [-v] [-a|-e] \
  65                 [-m|-s|-i] [-n] [-w DEF] [-q] [-k] [-d] [-z] [-r VAL] [-u] [-t]
  66         -f CONFIG_FILE : configuration file to load, ./prox.cfg by default
  67         -l LOG_FILE : log file name, ./prox.log by default
  68         -p : include PID in log file name if default log file is used
  69         -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none'
  70         -v verbosity : initial logging verbosity
  71         -a : autostart all cores (by default)
  72         -e : don't autostart
  73         -n : Create NULL devices instead of using PCI devices, useful together with -i
  74         -m : list supported task modes and exit
  75         -s : check configuration file syntax and exit
  76         -i : check initialization sequence and exit
  77         -u : Listen on UDS /tmp/prox.sock
  78         -t : Listen on TCP port 8474
  79         -q : Pass argument to Lua interpreter, useful to define variables
  80         -w : define variable using syntax varname=value
  81              takes precedence over variables defined in CONFIG_FILE
  82         -k : Log statistics to file "stats_dump" in current directory
  83         -d : Run as daemon, the parent process will block until PROX is not initialized
  84         -z : Ignore CPU topology, implies -i
  85         -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds,
  86                   screen refreshing will be disabled
  87
  88 While applications using DPDK typically rely on the core mask and the
  89 number of channels to be specified on the command line, this
  90 application is configured using a .cfg file. The core mask and number
  91 of channels is derived from this config. For example, to run the
  92 application from the source directory execute:
  93
  94   user@target:~$ ./build/prox -f ./config/nop.cfg
  95
  96 Provided example configurations
  97 -------------------------------
  98 PROX can be configured either as the SUT (System Under Test) or as the
  99 Traffic Generator. Some example configuration files are provided, both
 100 in the config directory to run PROX as a SUT, and in the gen directory
 101 to run it as a Traffic Generator.
 102 A quick description of these example configurations is provided below.
 103 Additional details are provided in the example configuration files.
 104
 105 Basic configurations, mostly used as sanity check:
 106 - config/nop.cfg
 107 - config/nop-rings.cfg
 108 - gen/nop-gen.cfg
 109
 110 Simplified BNG (Border Network Gateway) configurations, using different
 111 number of ports, with and without QoS, running on the host or in a VM:
 112 - config/bng-4ports.cfg
 113 - config/bng-8ports.cfg
 114 - config/bng-qos-4ports.cfg
 115 - config/bng-qos-8ports.cfg
 116 - config/bng-1q-4ports.cfg
 117 - config/bng-ovs-usv-4ports.cfg
 118 - config/bng-no-cpu-topology-4ports.cfg
 119 - gen/bng-4ports-gen.cfg
 120 - gen/bng-8ports-gen.cfg
 121 - gen/bng-ovs-usv-4ports-gen.cfg
 122
 123 Light-weight AFTR configurations:
 124 - config/lw_aftr.cfg
 125 - gen/lw_aftr-gen.cfg
 126