From bdf826f13c9b3b3c0d1b8e0028dad653ef69d9fc Mon Sep 17 00:00:00 2001 From: Deepak S Date: Tue, 17 Oct 2017 19:34:58 -0700 Subject: Updating user guide Change-Id: I80bcbe616b8f2c64151de6e588c892de6c3dc8f1 Signed-off-by: Deepak S --- docs/testing/user/userguide/09-prox.rst | 479 ++++++++++++++++++++++++++++++++ 1 file changed, 479 insertions(+) create mode 100644 docs/testing/user/userguide/09-prox.rst (limited to 'docs/testing/user/userguide/09-prox.rst') diff --git a/docs/testing/user/userguide/09-prox.rst b/docs/testing/user/userguide/09-prox.rst new file mode 100644 index 00000000..4d5444c0 --- /dev/null +++ b/docs/testing/user/userguide/09-prox.rst @@ -0,0 +1,479 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Intel Corporation and others. + +PROX - Packet pROcessing eXecution engine. +========================================== + +Change since previous release, support has been added for the following: + +8 workloads for automated dataplane benchmarking using DATS +Support DPDK 17.05 +L4 stateful traffic generation and flow extraction tool +lua configuration files for easy table population +New modes: impair, lb5tuple, mirror, nat, decapnsh, encapnsh and genl4 +helper script for automated VM core pinning for Qemu +New screens for viewing information regarding DPDK rings (screen 5) and L4 generation (screen 6) +Improved command editing using libedit +Improved ncurses display +Rename of dppd-bng zip file to dppd-prox +Latency histogram collection + +PROX COMMANDS AND SCREENS +------------------------- +:: + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + | **RUNTIME COMMAND** | **DESCRIPTION** | **EXAMPLE** | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |quit | Stop all cores and quit | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |help | Show list of commands that have as a substring. | | + | | If no substring is provided, all commands are shown. | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |verbose | Set the verbosity level of some printed messages. | | + | | Possible values are: 0 (default value, error messages only), | verbose 1 | + | | 1 (+ warnings), 2 (+ info) and 3 (+ debugging) | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |thread info | Show task specific information | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |update interval | Update statistics refresh rate, in msec (must be >=10). | | + | | Default is 1 second | update interval 500 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rx tx info | Print connections between tasks on all cores | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |start |all | Start cores specified in or all cores. | start all | + | | If is not specified, all tasks for the specified cores | start 1 | + | | will be started. | start 1s0-4s0 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |stop |all | Stop cores specified in or all cores. | | + | | If is not specified, all tasks for the specified | stop 1 | + | | cores will be stopped. | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |dump | Create a hex dump of from on | dump 2 1 5 | + | | showing how packets have changed between RX and TX. | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |dump_rx | Create a hex dump of from on at RX | dump_rx 2 1 5 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |dump_tx | Create a hex dump of from on at TX | dump_tx 2 1 5 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rx distr start | Start gathering statistical distribution of received packets | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rx distr stop | Stop gathering statistical distribution of received packets | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rx distr reset | Reset gathered statistical distribution of received packets | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rx distr show | Display gathered statistical distribution of received packets | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rate | Set transmit rate in Mb/s. This does not include preamble, SFD and IFG | rate 0 0 1000 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |count | Generate packets, then pause generating | count 1 0 5 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |pkt_size | Set the packet size to | pkt_size 1 3 255 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |speed | Change the speed to of a | + | | 10 Gbps line at which packets are being generated | speed 1 0 50 | + | | on core in task | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |speed_byte | Change speed to . The speed is specified in units of bytes per sec | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |set value | Set bytes to at offset in packets | | + | | generated on | set value 4 1 14 10 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + | reset values all | Undo all `set value` commands on all cores/tasks | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |reset values | Undo all `set value` commands on specified core/task | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |arp add | | | + | | | | + | | Add a single ARP entry into a CPE table on / | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rule add svlan_id&mask | | | + | cvlan_id&mask ip_proto&mask | | | + | source_ip/prefix destination_ip/prefix | | | + | range dport_range action | Add a rule to the ACL table on / | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |route add | | | + | | Add a route to the routing table on core | route add 10.0.16.0/24 9 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |reset stats | Reset all statistics | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |tot stats | Print total RX and TX packets | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |tot ierrors per sec | Print total number of ierrors per second | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |pps stats | Print RX and TX packet rate in unit of packet per second | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |lat stats | Print min,max,avg latency as measured during last sampling interval | lat stats 1 0 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |lat packets | Print the latency for each of the last set of packets | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |core stats | Print rx/tx/drop for task running on core | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port_stats | Print rate for no_mbufs, ierrors, rx_bytes, tx_bytes, rx_pkts, | | + | | tx_pkts and totals for RX, TX, no_mbufs ierrors for port | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |ring info all | Get information about ring, such as ring size and | | + | | number of elements in the ring | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |ring info | Get information about ring on core | | + | | in task , such as ring size and number of elements in the ring | ring info 1 0 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port info [brief] | Get port related information, such as MAC address, socket, | | + | | number of descriptors..., . Adding `brief` after command | | + | | prints short version of output. | port info 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port up | Set the port up (all ports are up at startup) | port up 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port down | Set the port down | port down 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port xstats | Get extra statistics for the port | port xstats 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |version | Show version | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port_stats | Print rate for no_mbufs, ierrors, rx_bytes, tx_bytes, rx_pkts, | | + | | tx_pkts and totals for RX, TX, no_mbufs ierrors for port | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + +While PROX is running, F1 to F6 change the view on the system. Pressing F1 switches to the main screen showing per core statistics. When PROX is started, +this is the screen shown by default. Pressing F2 switches to show port-based information. Pressing F3 shows information (i.e. occupancy, memory usage, ...) +about memory pools. If there are tasks with mode=lat, F4 displays latency measurements made during the last second by each of those tasks. +F5 displays DPDK ring information. F6 is for L4 generation. If no command has been entered, numbers 1 to 6 can also be used to change the view on the system. +This is provided to allow changing screens in environments that do not pass function keys to PROX. + +Page Up and Page Down can be used to view per core statistics that would otherwise not fit on the screen. Escape quits PROX. +The history of previously entered commands can be navigated using the Up and Down arrows. Statistics can be reset with F12. + +COMMAND LINE OPTIONS +-------------------- +Run PROX with the "--help" argument to display the usage text and the list of supported options as shown below. +PROX supports many compilation flags to enable or disable features. For these flags, refer to the Makefile. +Refer to the README file for more information on how to run PROX for specific use cases. + +:: + + Usage: ./build/prox [-f CONFIG_FILE] [-l LOG_FILE] [-p] [-o DISPLAY] [-v] [-a|-e] [-m|-s|-i] [-n] [-w DEF] [-q] [-k] [-d] [-z] [-r VAL] [-u] [-t] + -f CONFIG_FILE : configuration file to load, ./prox.cfg by default + -l LOG_FILE : log file name, ./prox.log by default + -p : include PID in log file name if default log file is used + -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none' + -v verbosity : initial logging verbosity + -a : autostart all cores (by default) + -e : don't autostart + -n : Create NULL devices instead of using PCI devices, useful together with -i + -m : list supported task modes and exit + -s : check configuration file syntax and exit + -i : check initialization sequence and exit + -u : Listen on UDS /tmp/prox.sock + -t : Listen on TCP port 8474 + -q : Pass argument to Lua interpreter, useful to define variables + -w : define variable using syntax varname=value + takes precedence over variables defined in CONFIG_FILE + -k : Log statistics to file "stats_dump" in current directory + -d : Run as daemon, the parent process will block until PROX is not initialized + -z : Ignore CPU topology, implies -i + -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds, + screen refreshing will be disabled + +CONFIGURATION FILE FORMAT +------------------------- +The configuration file is divided into multiple sections, each of which is used to define some parameters and options. +Sections are created using the [section name] syntax. The list of sections, where # represents an integer, is as follows: + +:: + [eal options] + [port #] + [variables] + [defaults] + [global] + [core #] + +In each section, entries are created using the key=value syntax. +Comments are created using the ; symbol: all characters from the ; +symbol to the end of line are ignored. A # symbol at the beginning of the section name comments +the whole section out: all entries in the section are treated as comments and are ignored. For example: + +:: + [#core 1] + ; this is a comment + parameter name=parameter value ; this entry is ignored because the section is commented out + +[EAL OPTIONS] +The following parameters are supported: + +:: + -m ; Specifies the amount of memory used. If not provided, all hugepages will be used. + -n ; Specifies the number of memory channels. Use -n4 for latest Intel Xeon based platforms + -r ; Specifies the number of memory ranks. + eal ; Specifies DPDK EAL extra options. Those options will be passed blindly to DPDK. + +[PORT #] +DPDK ports are usually referenced by their port_id, i.e. an integer starting from 0. +Using port_id in the configuration file is tedious, since the same port_id can appear at +different places (rx port, tx port, routing tables), +and those ports might change (e.g. if cables are swapped). +In order to make the configuration file easier to read and modify, +DPDK ports are given a name with the name= option. +The name serves as the reference, and in addition, it will show up in the display at runtime. + +:: + PARAMETER EXAMPLE DESCRIPTION + ---------------------------------------------------------------------------- + name inet0 Use inet0 to later refer to this port + mac hardware value can be: hardware, random or a literal MAC address + rx desc 256 number of descriptors to allocate for reception + tx desc 256 number of descriptors to allocate for transmission + promiscuous yes enable promiscuous mode + strip crc yes enable CRC stripping + rss yes enable RSS + lsc no While lsc is disabled for drivers known to not provide support, + this option explicitely overrides these settings. + rx_ring dpdk_ring_name use DPDK ring as an interface (receive side) + tx_ring dpdk_ring_name use DPDK ring as an interface (transmit side) + +[VARIABLES] +Variables can be defined in the configuration file using the $varname=value syntax. +Variables defined on the command line (-w varname=value) take precedence and do not +create conflicts with variables defined in the configuration file. Variables are +used in the configuration file using the $varname syntax: each instance of $varname +is replaced by its associated value. This is typically useful if the same parameter +must be used at several places. For instance, you might want to have multiple load +balancers, all transmitting to the same set of worker cores. +The list of worker cores could then be defined once in a variable: + +:: + [variables] + $wk=1s0-5s0 + +Then, a load balancer definition would use the variable: + +:: + [core 6s0] + name=LB + task=0 + mode=lbnetwork + tx cores=$wk task=0 + ... + +And the section defining the worker cores would be: + +:: + [core $wk] + name=worker + task=0 + mode=qinqencapv4 + ... + +[DEFAULTS] +The default value of some options can be overridden using the [defaults] section: + +:: + PARAMETER EXAMPLE DESCRIPTION + ----------------------------------- + mempool size 16K number of mbufs per task, relevant when task receives from a port. + this is the n argument provided to rte_mempool_create() + qinq tag 0xa888 Set qinq tag for all tasks. The result of adding this option is the + same as adding qinq tag= to each task + memcache size 128 number of mbufs cached per core, default is 256 this is the cache_size + argument provided to rte_mempool_create() + +[GLOBAL] +The following parameters are supported: + +:: + PARAMETER EXAMPLE DESCRIPTION + ------------------------------------------------- + name BNG Name of the configuration, which will be shown in the title box at runtime. + start time 10 Time in seconds after which average statistics will be started. + Default value is 0. + duration time 30 Runtime duration in seconds, counted after start time. + This is typically useful to automate testing using + different parameters: PROX automatically exits when the + runtime duration has elapsed. Initialization and start time + are not included in this runtime duration. + For example, if start time is set to 10 and duration time is set to 30, + the total execution time (after initialization) will be 40 seconds. + Default value is 0, which means infinity and prevents PROX from automatically exiting. + shuffle yes When this parameter is set to yes, the order of mbufs + within mempools is randomized to simulate a system that has + been warmed up. Default value is no. + gre cfg /path/to/file.csv Path to CSV file that provides QinQ-to-GRE mapping. + Default value is gre_table.csv in same directory as + configuration file. Fields are GRE key and QinQ value (computed as SVLAN * 4096 + CVLAN). + pre cmd ls Arbitrary system commands to run while reading cfg. This option can occur multiple times. + user cfg /path/to/file.csv Path to CSV file that provides QinQ-to-User mapping. + Default value is user_table.csv in same directory as configuration file. + Fields are SVLAN, CVLAN and User-Id. + next hop cfg /path/to/file.csv Path to CSV file that provides Next-Hop details. + Default value is next_hop.csv in same directory as configuration file. + Fields are Next-Hop index (as returned by LPM lookup), + Out-Port index, Next-Hop IP (unused), Next-Hop MAC and MPLS label. + ipv4 cfg /path/to/file.csv Path to CSV file that provides IPv4 LPM routing table. + Default value is ipv4.csv in same directory as configuration file. + Fields are IPv4 subnet (in CIDR notation) and Next-Hop index. + dscp cfg /path/to/file.csv Path to CSV file that provides mapping for QoS classification, + from DSCP to Traffic Class and Queue. + Default value is dscp.csv in same directory as configuration file. + Fields are DSCP (0-63), Traffic Class (0-3) and Queue (0-3). + ipv6 tunnel cfg /path/to/file.csv Path to CSV file that provides lwAFTR binding table. + Default value is ipv6_tun_bind.csv in same directory as configuration file. + Fields are lwB4 IPv6 address, next hop MAC address towards lwB4, + IPv4 Public address and IPv4 Public Port Set. + acl cfg /path/to/file.csv Path to CSV file that provides ACL rules. + Default value is rules.csv in same directory as configuration file. + Fields are SVLAN value & mask, CVLAN value & mask, IP protocol value & mask, + source IPv4 subnet (in CIDR notation), destination IPv4 subnet (in CIDR notation), + source port range, destination port range, and action (drop, allow, rate limit). + unique mempool yes + per socket + +[CORE #] +Cores can be configured by means of a set of [core #] sections, where # represents either: + +an absolute core number: e.g. on a 10-core, dual socket system with hyper-threading, cores are numbered from 0 to 39; +a core number, the letter 's', and a socket number: this allows selecting per-socket cores, independently from their interleaved numbering; +a core number and the letter 'h': this allows selecting the hyper-thread sibling of the specified core; +a dash-separated range of core numbers; +a comma-separated list of core numbers; +any combination of the above; +or a variable whose value complies with the above syntax. +The socket and hyper-thread syntax makes it easier to use the same configuration file on several platforms, +even if their core numbering differs (e.g. interleaving rule or number of cores per socket). + +Each core can be assigned with a set of tasks, each running one of the implemented packet processing modes. + +The following parameters are supported: +.. image:: images/prox_core.png + :width: 1024px + :alt: SampleVNF supported topology + +INSTALLATION +------------ + +PREREQUISITES +^^^^^^^^^^^^^ +DPDK must be installed prior to running make in the PROX directory. +The README file shipped with PROX describes what versions of DPDK are supported, +and if any patches are needed for the chosen DPDK version. + +The following packages need to be installed. (Example for destributions that are using rpm) + +:: + sudo yum install net-tools wget gcc unzip libpcap-devel ncurses-devel libedit-devel pciutils lua-devel kernel-devel + Jump Start + +The following instructions are here to help customers to start using PROX. +It's by no means a complete guide, for detailed instructions on how to install and use +DPDK please refer to its documentation. +Your mileage may vary depending on a particular Linux distribution and hardware in use. + +Edit grub default configuration: + +:: + vi /etc/default/grub + +Add the following to the kernel boot parameters + +:: + default_hugepagesz=1G hugepagesz=1G hugepages=8 + +Rebuild grub config and reboot the system: + +:: + grub2-mkconfig -o /boot/grub2/grub.cfg + reboot + +Verify that hugepages are available + +:: + cat /proc/meminfo + ... + HugePages_Total: 8 + HugePages_Free: 8 + Hugepagesize: 1048576 kB + ... + +Re-mount huge pages + +:: + mkdir -p /mnt/huge + umount `awk '/hugetlbfs/ { print $2 }' /proc/mounts` >/dev/null 2>&1 + mount -t hugetlbfs nodev /mnt/huge/ + +Add the following to the end of ~/.bashrc file + +:: + export RTE_SDK=/root/dpdk + export RTE_TARGET=x86_64-native-linuxapp-gcc + export RTE_UNBIND=$RTE_SDK/tools/dpdk_nic_bind.py + +Re-login or source that file + +:: + . ~/.bashrc + +Build DPDK + +:: + git clone http://dpdk.org/git/dpdk + cd dpdk + git checkout v1.8.0 + make install T=$RTE_TARGET + +Load uio module + +:: + lsmod | grep -w "^uio" >/dev/null 2>&1 || sudo modprobe uio + sleep 1 + +Load igb_uio module + +:: + lsmod | grep -w "^igb_uio" >/dev/null 2>&1 || sudo insmod $RTE_SDK/$RTE_TARGET/kmod/igb_uio.ko + +Discover network devices available on the system: + +:: + lspci | grep Ethernet + +Prior launching PROX, ports that are to be used by it must be bound to the igb_uio driver. + +The following command will bind all Intel® Ethernet Converged Network Adapter X710 ports to igb_uio: + +:: + lspci | grep X710 | cut -d' ' -f 1 | sudo xargs -I {} python2.7 $RTE_UNBIND --bind=igb_uio {} + +The following command will bind all Intel® 82599 10 Gigabit Ethernet Controller ports to igb_uio: + +:: + lspci | grep 82599 | cut -d' ' -f 1 | sudo xargs -I {} python2.7 $RTE_UNBIND --bind=igb_uio {} + +COMPILING AND RUNNING PROX +-------------------------- + +Download and extract the PROX archive + +:: + wget https://01.org/sites/default/files/downloads/intel-data-plane-performance-demonstrators/dppd-prox-v021.zip + unzip dppd-prox-v021.zip + cd dppd-prox-v021 + +Build the PROX + +:: + make + +The set of sample configuration files can be found in: + +:: + ./config/* + +PROX generation sample configs are in: + +:: + ./gen/* + +To launch PROX one may use the following command as an example, assuming the current directory is where you've just built PROX: + +:: + ./build/prox -f ./config/handle_none.cfg -- cgit 1.2.3-korg