VNFs/DPPD-PROX/README

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