1 .. This work is licensed under a Creative Commons Attribution 4.0 International
3 .. http://creativecommons.org/licenses/by/4.0
4 .. (c) OPNFV, Intel Corporation and others.
14 The device under test (DUT) consists of a system following;
15 * A single or dual processor and PCH chip, except for System on Chip (SoC) cases
16 * DRAM memory size and frequency (normally single DIMM per channel)
17 * Specific Intel Network Interface Cards (NICs)
18 * BIOS settings noting those that updated from the basic settings
19 * DPDK build configuration settings, and commands used for tests
20 Connected to the DUT is an IXIA* or Software Traffic generator like pktgen or TRex,
21 simulation platform to generate packet traffic to the DUT ports and
22 determine the throughput/latency at the tester side.
24 Below are the supported/tested (:term:`VNF`) deployment type.
26 .. image:: images/deploy_type.png
28 :alt: SampleVNF supported topology
30 Hardware & Software Ingredients
31 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
35 +-----------+------------------+
36 | Item | Description |
37 +-----------+------------------+
39 +-----------+------------------+
41 +-----------+------------------+
42 | OS | Ubuntu 16.04 LTS |
43 +-----------+------------------+
44 | kernel | 4.4.0-34-generic |
45 +-----------+------------------+
47 +-----------+------------------+
49 Boot and BIOS settings:
51 +------------------+---------------------------------------------------+
52 | Boot settings | default_hugepagesz=1G hugepagesz=1G hugepages=16 |
53 | | hugepagesz=2M hugepages=2048 isolcpus=1-11,22-33 |
54 | | nohz_full=1-11,22-33 rcu_nocbs=1-11,22-33 |
55 | | Note: nohz_full and rcu_nocbs is to disable Linux*|
56 | | kernel interrupts, and it’s import |
57 +------------------+---------------------------------------------------+
58 | BIOS | CPU Power and Performance Policy <Performance> |
59 | | CPU C-state Disabled |
60 | | CPU P-state Disabled |
61 | | Enhanced Intel® Speedstep® Tech Disabled |
62 | | Hyper-Threading Technology (If supported) Enable |
63 | | Virtualization Techology Enable |
64 | | Coherency Enable |
65 | | Turbo Boost Disabled |
66 +------------------+---------------------------------------------------+
68 Network Topology for testing VNFs
69 ---------------------------------
70 The ethernet cables should be connected between traffic generator and the VNF server (BM,
71 SRIOV or OVS) setup based on the test profile.
73 The connectivity could be
75 1) Single port pair : One pair ports used for traffic
79 e.g. Single port pair link0 and link1 of VNF are used
80 TG:port 0 <------> VNF:Port 0
81 TG:port 1 <------> VNF:Port 1
83 For correalted traffic, use below configuration
84 TG_1:port 0 <------> VNF:Port 0
85 VNF:Port 1 <------> TG_2:port 0 (UDP Replay)
86 (TG_2(UDP_Replay) reflects all the traffic on the given port)
88 2) Multi port pair : More than one pair of traffic
92 e.g. Two port pair link 0, link1, link2 and link3 of VNF are used
93 TG:port 0 <------> VNF:Port 0
94 TG:port 1 <------> VNF:Port 1
95 TG:port 2 <------> VNF:Port 2
96 TG:port 3 <------> VNF:Port 3
98 For correalted traffic, use below configuration
99 TG_1:port 0 <------> VNF:Port 0
100 VNF:Port 1 <------> TG_2:port 0 (UDP Replay)
101 TG_1:port 1 <------> VNF:Port 2
102 VNF:Port 3 <------> TG_2:port 1 (UDP Replay)
103 (TG_2(UDP_Replay) reflects all the traffic on the given port)
106 Refer: http://fast.dpdk.org/doc/pdf-guides/ to setup the DUT for VNF to run
108 * Standalone Virtualization - PHY-VM-PHY
110 Refer below link to setup sriov
111 https://software.intel.com/en-us/articles/using-sr-iov-to-share-an-ethernet-port-among-multiple-vms
114 Refer below link to setup ovs-dpdk
115 http://docs.openvswitch.org/en/latest/intro/install/general/
116 http://docs.openvswitch.org/en/latest/intro/install/dpdk/
119 Use any OPNFV installer to deploy the openstack.
121 Setup Traffic generator
122 -----------------------
124 Step 0: Preparing hardware connection
126 Connect Traffic generator and VNF system back to back as shown in previous section
129 TRex port 0 ↔ (VNF Port 0) ↔ (VNF Port 1) ↔ TRex port 1
131 Step 1: Setting up Traffic generator (TRex)
133 TRex Software preparations
134 **************************
135 * Install the OS (Bare metal Linux, not VM!)
136 * Obtain the latest TRex package: wget https://trex-tgn.cisco.com/trex/release/latest
137 * Untar the package: tar -xzf latest
138 * Change dir to unzipped TRex
139 * Create config file using command: sudo python dpdk_setup_ports.py -i
140 In case of Ubuntu 16 need python3
141 See paragraph config creation for detailed step-by-step
142 (Refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html)
148 Step 2: Procedure to build SampleVNFs
150 a) Clone sampleVNF project repository - git clone https://git.opnfv.org/samplevnf
155 * Interactive options:
158 ./tools/vnf_build.sh -i
159 Follow the steps in the screen from option [1] –> [9] and select option [8] to build the vnfs.
160 It will automatically download selected DPDK version and any required patches and will setup everything and build VNFs.
161 Following are the options for setup:
162 ----------------------------------------------------------
163 Step 1: Environment setup.
164 ----------------------------------------------------------
165 [1] Check OS and network connection
166 [2] Select DPDK RTE version
168 ----------------------------------------------------------
169 Step 2: Download and Install
170 ----------------------------------------------------------
171 [3] Agree to download
172 [4] Download packages
173 [5] Download DPDK zip
174 [6] Build and Install DPDK
176 [8] Download civetweb
178 ----------------------------------------------------------
180 ----------------------------------------------------------
181 [9] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay, DPPD-PROX)
186 * Non-Interactive options:
189 ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02>
190 if system is behind the proxy
191 ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> -p=<proxy>
197 1) Download DPDK supported version from dpdk.org
198 http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip
199 unzip dpdk-$DPDK_RTE_VER.zip and apply dpdk patches only in case of 16.04 (Not required for other DPDK versions)
201 make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc
202 cd x86_64-native-linuxapp-gcc
205 2) Download civetweb 1.9 version from the following link
206 https://sourceforge.net/projects/civetweb/files/1.9/CivetWeb_V1.9.zip
207 unzip CivetWeb_V1.9.zip
208 mv civetweb-master civetweb
213 For 1G/2M hugepage sizes, for example 1G pages, the size must be
214 specified explicitly and can also be optionally set as the
215 default hugepage size for the system. For example, to reserve 8G
216 of hugepage memory in the form of eight 1G pages, the following
217 options should be passed to the kernel: * default_hugepagesz=1G
218 hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048
219 4) Add this to Go to /etc/default/grub configuration file.
220 Append “default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048”
221 to the GRUB_CMDLINE_LINUX entry.
222 5) Setup Environment Variable
223 export RTE_SDK=<samplevnf>/dpdk
224 export RTE_TARGET=x86_64-native-linuxapp-gcc
225 export VNF_CORE=<samplevnf>
226 or using ./tools/setenv.sh
230 or to build individual VNFs
234 The vFW executable will be created at the following location
235 <samplevnf>/VNFs/vFW/build/vFW
238 Virtual Firewall - How to run
239 -----------------------------
241 Step 3: Bind the datapath ports to DPDK
243 a) Bind ports to DPDK
247 For DPDK versions 17.xx
248 1) cd <samplevnf>/dpdk
249 2) ./usertools/dpdk-devbind.py --status <--- List the network device
250 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
251 .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
254 b) Prepare script to enalble VNF to route the packets
258 cd <samplevnf>/VNFs/vFW/config
259 Open -> VFW_SWLB_SinglePortPair_script.tc. Replace the bold items based on your setting.
261 link 0 config <VNF port 0 IP eg 202.16.100.10> 8
264 link 1 config <VNF port 0 IP eg 172.16.40.10> 8
267 ; routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask>
268 routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000
269 routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000
271 ; IPv4 static ARP; disable if dynamic arp is enabled.
272 p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC>
273 p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC>
274 p action add 0 accept
277 p action add 1 accept
282 p action add 0 conntrack
283 p action add 1 conntrack
284 p action add 2 conntrack
285 p action add 3 conntrack
287 p vfw add 1 <traffic generator port 0 IP eg 202.16.100.20> 8 <traffic generator port 1 IP eg 172.16.40.20> 8 0 65535 67 69 0 0 2
288 p vfw add 2 <traffic generator port 0 IP eg 202.16.100.20> 8 <traffic generator port 1 IP eg 172.16.40.20> 8 0 65535 0 65535 0 0 1
289 p vfw add 2 <traffic generator port 1 IP eg 172.16.40.20> 8 <traffic generator port 0 IP eg 202.16.100.20> 8 0 65535 0 65535 0 0 0
292 c) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk.
296 cd <samplevnf>/VNFs/vFW/
297 ./build/vFW -p 0x3 -f ./config/VFW_SWLB_SinglePortPair_4Thread.cfg -s ./config/VFW_SWLB_SinglePortPair_script.tc
300 step 4: Run Test using traffic geneator
304 On traffic generator system:
305 cd <trex eg v2.28/stl>
306 Update the bench.py to generate the traffic.
308 class STLBench(object):
310 ip_range['src'] = {'start': '<traffic generator port 0 IP eg 202.16.100.20>', 'end': '<traffic generator port 0 IP eg 202.16.100.20>'}
311 ip_range['dst'] = {'start': '<traffic generator port 1 IP eg 172.16.40.20>', 'end': '<traffic generator port 1 IP eg 172.16.40.20>'}
313 Run the TRex server: sudo ./t-rex-64 -i -c 7
314 In another shell run TRex console: trex-console
315 The console can be run from another computer with -s argument, --help for more info.
316 Other options for TRex client are automation or GUI
317 In the console, run "tui" command, and then send the traffic with commands like:
318 start -f stl/bench.py -m 50% --port 0 3 -t size=590,vm=var1
319 For more details refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html
322 Virtual Access Control list - How to run
323 ----------------------------------------
325 Step 3: Bind the datapath ports to DPDK
327 a) Bind ports to DPDK
331 For DPDK versions 17.xx
332 1) cd <samplevnf>/dpdk
333 2) ./usertools/dpdk-devbind.py --status <--- List the network device
334 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
335 .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
338 b) Prepare script to enalble VNF to route the packets
342 cd <samplevnf>/VNFs/vACL/config
343 Open -> IPv4_swlb_acl.tc. Replace the bold items based on your setting.
345 link 0 config <VNF port 0 IP eg 202.16.100.10> 8
348 link 1 config <VNF port 0 IP eg 172.16.40.10> 8
351 ; routeadd <port #> <ipv4 nhip address in decimal> <Mask>
352 routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000
353 routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000
355 ; IPv4 static ARP; disable if dynamic arp is enabled.
356 p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC>
357 p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC>
358 p action add 0 accept
361 p action add 1 accept
366 p action add 0 conntrack
367 p action add 1 conntrack
368 p action add 2 conntrack
369 p action add 3 conntrack
371 p acl add 1 <traffic generator port 0 IP eg 202.16.100.20> 8 <traffic generator port 1 IP eg 172.16.40.20> 8 0 65535 67 69 0 0 2
372 p acl add 2 <traffic generator port 0 IP eg 202.16.100.20> 8 <traffic generator port 1 IP eg 172.16.40.20> 8 0 65535 0 65535 0 0 1
373 p acl add 2 <traffic generator port 1 IP eg 172.16.40.20> 8 <traffic generator port 0 IP eg 202.16.100.20> 8 0 65535 0 65535 0 0 0
377 c) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk.
381 cd <samplevnf>/VNFs/vFW/
382 ./build/vFW -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg -s ./config/IPv4_swlb_acl.tc.
385 step 4: Run Test using traffic geneator
389 On traffic generator system:
390 cd <trex eg v2.28/stl>
391 Update the bench.py to generate the traffic.
393 class STLBench(object):
395 ip_range['src'] = {'start': '<traffic generator port 0 IP eg 202.16.100.20>', 'end': '<traffic generator port 0 IP eg 202.16.100.20>'}
396 ip_range['dst'] = {'start': '<traffic generator port 1 IP eg 172.16.40.20>', 'end': '<traffic generator port 1 IP eg 172.16.40.20>'}
398 Run the TRex server: sudo ./t-rex-64 -i -c 7
399 In another shell run TRex console: trex-console
400 The console can be run from another computer with -s argument, --help for more info.
401 Other options for TRex client are automation or GUI
402 In the console, run "tui" command, and then send the traffic with commands like:
403 start -f stl/bench.py -m 50% --port 0 3 -t size=590,vm=var1
404 For more details refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html
410 Step 3: Bind the datapath ports to DPDK
412 a) Bind ports to DPDK
416 For DPDK versions 17.xx
417 1) cd <samplevnf>/dpdk
418 2) ./usertools/dpdk-devbind.py --status <--- List the network device
419 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
420 .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
423 b) Prepare script to enalble VNF to route the packets
427 cd <samplevnf>/VNFs/vCGNAPT/config
428 Open -> sample_swlb_2port_2WT.tc Replace the bold items based on your setting.
430 link 0 config <VNF port 0 IP eg 202.16.100.10> 8
433 link 1 config <VNF port 0 IP eg 172.16.40.10> 8
436 ; uncomment to enable static NAPT
437 ;p <cgnapt pipeline id> entry addm <prv_ipv4/6> prvport> <pub_ip> <pub_port> <phy_port> <ttl> <no_of_entries> <end_prv_port> <end_pub_port>
438 ;p 5 entry addm 202.16.100.20 1234 152.16.40.10 1 0 500 65535 1234 65535
440 ; routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask>
441 routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000
442 routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000
444 ; IPv4 static ARP; disable if dynamic arp is enabled.
445 p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC>
446 p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC>
448 For dynamic cgnapt. Please use UDP_Replay as one of the traffic generator
449 (TG1) (port 0) --> (port 0) VNF (CGNAPT) (Port 1) --> (port0)(UDPReplay)
451 c) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk.
455 cd <samplevnf>/VNFs/vCGNAPT/
456 ./build/vCGNAPT -p 0x3 -f ./config/sample_swlb_2port_2WT.cfg -s ./config/sample_swlb_2port_2WT.tc
458 d) Run UDP_replay to reflect the traffic on public side.
459 cmd: ./build/UDP_Replay -c 0x7 -n 4 -w <pci> -w <pci> -- --no-hw-csum -p <portmask> --config='(port, queue, cpucore)'
460 e.g ./build/UDP_Replay -c 0x7 -n 4 -w 0000:07:00.0 -w 0000:07:00.1 -- --no-hw-csum -p 0x3 --config='(0, 0, 1)(1, 0, 2)'
462 step 4: Run Test using traffic geneator
464 On traffic generator system:
467 cd <trex eg v2.28/stl>
468 Update the bench.py to generate the traffic.
470 class STLBench(object):
472 ip_range['src'] = {'start': '<traffic generator port 0 IP eg 202.16.100.20>', 'end': '<traffic generator port 0 IP eg 202.16.100.20>'}
473 ip_range['dst'] = {'start': '<traffic generator port 1 IP eg 172.16.40.20>', 'end': '<public ip e.g 152.16.40.10>'}
475 Run the TRex server: sudo ./t-rex-64 -i -c 7
476 In another shell run TRex console: trex-console
477 The console can be run from another computer with -s argument, --help for more info.
478 Other options for TRex client are automation or GUI
479 In the console, run "tui" command, and then send the traffic with commands like:
480 start -f stl/bench.py -m 50% --port 0 3 -t size=590,vm=var1
481 For more details refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html
484 UDP_Replay - How to run
485 ----------------------------------------
487 Step 3: Bind the datapath ports to DPDK
489 a) Bind ports to DPDK
493 For DPDK versions 17.xx
494 1) cd <samplevnf>/dpdk
495 2) ./usertools/dpdk-devbind.py --status <--- List the network device
496 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1>
497 .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules
499 b) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk.
503 cd <samplevnf>/VNFs/UDP_Replay/
504 cmd: ./build/UDP_Replay -c 0x7 -n 4 -w <pci> -w <pci> -- --no-hw-csum -p <portmask> --config='(port, queue, cpucore)'
505 e.g ./build/UDP_Replay -c 0x7 -n 4 -w 0000:07:00.0 -w 0000:07:00.1 -- --no-hw-csum -p 0x3 --config='(0, 0, 1)(1, 0, 2)'
508 step 4: Run Test using traffic geneator
512 On traffic generator system:
513 cd <trex eg v2.28/stl>
514 Update the bench.py to generate the traffic.
516 class STLBench(object):
518 ip_range['src'] = {'start': '<traffic generator port 0 IP eg 202.16.100.20>', 'end': '<traffic generator port 0 IP eg 202.16.100.20>'}
519 ip_range['dst'] = {'start': '<traffic generator port 1 IP eg 172.16.40.20>', 'end': '<public ip e.g 152.16.40.10>'}
521 Run the TRex server: sudo ./t-rex-64 -i -c 7
522 In another shell run TRex console: trex-console
523 The console can be run from another computer with -s argument, --help for more info.
524 Other options for TRex client are automation or GUI
525 In the console, run "tui" command, and then send the traffic with commands like:
526 start -f stl/bench.py -m 50% --port 0 3 -t size=590,vm=var1
527 For more details refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html
535 This is PROX, the Packet pROcessing eXecution engine, part of Intel(R)
536 Data Plane Performance Demonstrators, and formerly known as DPPD-BNG.
537 PROX is a DPDK-based application implementing Telco use-cases such as
538 a simplified BRAS/BNG, light-weight AFTR... It also allows configuring
539 finer grained network functions like QoS, Routing, load-balancing...
541 PROX COMMANDS AND SCREENS
542 -------------------------
544 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
545 | *RUNTIME COMMAND* | *DESCRIPTION* | *EXAMPLE* |
546 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
547 | quit | Stop all cores and quit | |
548 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
549 | help <substr> | Show list of commands that have <substr> as a substring. | |
550 | | If no substring is provided, all commands are shown. | |
551 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
552 | verbose <level> | Set the verbosity level of some printed messages. | |
553 | | Possible values are: 0 (default value, error messages only), | verbose 1 |
554 | | 1 (+ warnings), 2 (+ info) and 3 (+ debugging) | |
555 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
556 | thread info <core_id> <task_id> | Show task specific information | |
557 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
558 | update interval <value> | Update statistics refresh rate, in msec (must be >=10). | |
559 | | Default is 1 second | update interval 500 |
560 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
561 | rx tx info | Print connections between tasks on all cores | |
562 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
563 | start <core list>|all <task_id> | Start cores specified in <core list> or all cores. | start all |
564 | | If <task_id> is not specified, all tasks for the specified cores | start 1 |
565 | | will be started. | start 1s0-4s0 |
566 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
567 | stop <core list>|all <task_id> | Stop cores specified in <core list> or all cores. | |
568 | | If <task_id> is not specified, all tasks for the specified | stop 1 |
569 | | cores will be stopped. | |
570 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
571 | dump <coreid> <taskid> <nbpkts> | Create a hex dump of <nb_packets> from <task_id> on <core_id> | dump 2 1 5 |
572 | | showing how packets have changed between RX and TX. | |
573 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
574 | dump_rx <coreid> <taskid> <nbpkts> | Create a hex dump of <nb_packets> from <task_id> on <coreid> at RX | dump_rx 2 1 5 |
575 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
576 | dump_tx <coreid> <taskid> <nbpkts> | Create a hex dump of <nb_packets> from <task_id> on <coreid> at TX | dump_tx 2 1 5 |
577 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
578 | rx distr start | Start gathering statistical distribution of received packets | |
579 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
580 | rx distr stop | Stop gathering statistical distribution of received packets | |
581 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
582 | rx distr reset | Reset gathered statistical distribution of received packets | |
583 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
584 | rx distr show | Display gathered statistical distribution of received packets | |
585 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
586 | rate <port id> <queue id> <rate> | Set transmit rate in Mb/s. This does not include preamble, SFD and IFG | rate 0 0 1000 |
587 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
588 | count <core id> <task id> <count> | Generate <count> packets, then pause generating | count 1 0 5 |
589 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
590 | pkt_size <coreid> <taskid> <pktsize> | Set the packet size to <pkt_size> | pkt_size 1 3 255 |
591 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
592 | speed <core_id> <task_id> <speed percentage> | Change the speed to <speed percentage> of a | |
593 | | 10 Gbps line at which packets are being generated | speed 1 0 50 |
594 | | on core <core_id> in task <task_id> | |
595 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
596 | speed_byte <core_id> <task_id> <speed> | Change speed to <speed>. The speed is specified in units of bytes per sec | |
597 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
598 | set value <core_id> <task_id> <offset> | Set <value_len> bytes to <value> at offset <offset> in packets | |
599 | <value> <value_len> | generated on <core_id> <task_id> | set value 4 1 14 10 1 |
600 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
601 | reset values all | Undo all `set value` commands on all cores/tasks | |
602 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
603 | reset values <core id> <task id> | Undo all `set value` commands on specified core/task | |
604 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
605 | arp add <core id> <task id> <port id> | | |
606 | <gre id> <svlan> <cvlan> <ip addr> | | |
607 | <mac addr> <user> | Add a single ARP entry into a CPE table on <core id>/<task id> | |
608 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
609 | rule add <core id> <task id> svlan_id&mask | | |
610 | cvlan_id&mask ip_proto&mask | | |
611 | source_ip/prefix destination_ip/prefix | | |
612 | range dport_range action | Add a rule to the ACL table on <core id>/<task id> | |
613 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
614 | route add <core id> <task id> | | |
615 | <ip/prefix> <next hop id> | Add a route to the routing table on core <core id> <task id> | route add 10.0.16.0/24 9 |
616 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
617 | reset stats | Reset all statistics | |
618 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
619 | tot stats | Print total RX and TX packets | |
620 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
621 | tot ierrors per sec | Print total number of ierrors per second | |
622 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
623 | pps stats | Print RX and TX packet rate in unit of packet per second | |
624 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
625 | lat stats <core id> <task id> | Print min,max,avg latency as measured during last sampling interval | lat stats 1 0 |
626 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
627 | lat packets <core id> <task id> | Print the latency for each of the last set of packets | |
628 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
629 | core stats <core id> <task id> | Print rx/tx/drop for task <task id> running on core <core id> | |
630 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
631 | port_stats <port id> | Print rate for no_mbufs, ierrors, rx_bytes, tx_bytes, rx_pkts, | |
632 | | tx_pkts and totals for RX, TX, no_mbufs ierrors for port <port id> | |
633 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
634 | ring info all | Get information about ring, such as ring size and | |
635 | | number of elements in the ring | |
636 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
637 | ring info <core id> <task id> | Get information about ring on core <core id> | |
638 | | in task <task id>, such as ring size and number of elements in the ring | ring info 1 0 |
639 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
640 | port info <port id> [brief] | Get port related information, such as MAC address, socket, | |
641 | | number of descriptors..., . Adding `brief` after command | |
642 | | prints short version of output. | port info 1 |
643 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
644 | port up <port id> | Set the port up (all ports are up at startup) | port up 1 |
645 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
646 | port down <port id> | Set the port down | port down 1 |
647 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
648 | port xstats <port id> | Get extra statistics for the port | port xstats 1 |
649 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
650 | version | Show version | |
651 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
652 | port_stats <port id> | Print rate for no_mbufs, ierrors, rx_bytes, tx_bytes, rx_pkts, | |
653 | | tx_pkts and totals for RX, TX, no_mbufs ierrors for port <port id> | |
654 +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+
656 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,
657 this is the screen shown by default. Pressing F2 switches to show port-based information. Pressing F3 shows information (i.e. occupancy, memory usage, ...)
658 about memory pools. If there are tasks with mode=lat, F4 displays latency measurements made during the last second by each of those tasks.
659 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.
660 This is provided to allow changing screens in environments that do not pass function keys to PROX.
662 Page Up and Page Down can be used to view per core statistics that would otherwise not fit on the screen. Escape quits PROX.
663 The history of previously entered commands can be navigated using the Up and Down arrows. Statistics can be reset with F12.
667 Run PROX with the "--help" argument to display the usage text and the list of supported options as shown below.
668 PROX supports many compilation flags to enable or disable features. For these flags, refer to the Makefile.
669 Refer to the README file for more information on how to run PROX for specific use cases.
673 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]
674 -f CONFIG_FILE : configuration file to load, ./prox.cfg by default
675 -l LOG_FILE : log file name, ./prox.log by default
676 -p : include PID in log file name if default log file is used
677 -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none'
678 -v verbosity : initial logging verbosity
679 -a : autostart all cores (by default)
681 -n : Create NULL devices instead of using PCI devices, useful together with -i
682 -m : list supported task modes and exit
683 -s : check configuration file syntax and exit
684 -i : check initialization sequence and exit
685 -u : Listen on UDS /tmp/prox.sock
686 -t : Listen on TCP port 8474
687 -q : Pass argument to Lua interpreter, useful to define variables
688 -w : define variable using syntax varname=value
689 takes precedence over variables defined in CONFIG_FILE
690 -k : Log statistics to file "stats_dump" in current directory
691 -d : Run as daemon, the parent process will block until PROX is not initialized
692 -z : Ignore CPU topology, implies -i
693 -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds,
694 screen refreshing will be disabled
696 CONFIGURATION FILE FORMAT
697 -------------------------
698 The configuration file is divided into multiple sections, each of which is used to define some parameters and options.
699 Sections are created using the [section name] syntax. The list of sections, where # represents an integer, is as follows:
710 In each section, entries are created using the key=value syntax.
711 Comments are created using the ; symbol: all characters from the ;
712 symbol to the end of line are ignored. A # symbol at the beginning of the section name comments
713 the whole section out: all entries in the section are treated as comments and are ignored. For example:
719 parameter name=parameter value ; this entry is ignored because the section is commented out
721 * [EAL OPTIONS]: The following parameters are supported:
725 -m ; Specifies the amount of memory used. If not provided, all hugepages will be used.
726 -n ; Specifies the number of memory channels. Use -n4 for latest Intel Xeon based platforms
727 -r ; Specifies the number of memory ranks.
728 eal ; Specifies DPDK EAL extra options. Those options will be passed blindly to DPDK.
730 * [PORT #]: DPDK ports are usually referenced by their port_id, i.e. an integer starting from 0.
731 Using port_id in the configuration file is tedious, since the same port_id can appear at
732 different places (rx port, tx port, routing tables), and those ports might change (e.g. if cables are swapped).
733 In order to make the configuration file easier to read and modify, DPDK ports are given a name with the name= option.
734 The name serves as the reference, and in addition, it will show up in the display at runtime.
738 PARAMETER EXAMPLE DESCRIPTION
739 ----------------------------------------------------------------------------
740 name inet0 Use inet0 to later refer to this port
741 mac hardware value can be: hardware, random or a literal MAC address
742 rx desc 256 number of descriptors to allocate for reception
743 tx desc 256 number of descriptors to allocate for transmission
744 promiscuous yes enable promiscuous mode
745 strip crc yes enable CRC stripping
747 lsc no While lsc is disabled for drivers known to not provide support,
748 this option explicitely overrides these settings.
749 rx_ring dpdk_ring_name use DPDK ring as an interface (receive side)
750 tx_ring dpdk_ring_name use DPDK ring as an interface (transmit side)
752 * [VARIABLES]: Variables can be defined in the configuration file using the $varname=value syntax.
753 Variables defined on the command line (-w varname=value) take precedence and do not create
754 conflicts with variables defined in the configuration file. Variables are used in the
755 configuration file using the $varname syntax: each instance of $varname is replaced by its
756 associated value. This is typically useful if the same parameter must be used at several places.
757 For instance, you might want to have multiple load balancers, all transmitting to the same set
758 of worker cores. The list of worker cores could then be defined once in a variable:
765 Then, a load balancer definition would use the variable:
776 And the section defining the worker cores would be:
786 * [DEFAULTS]: The default value of some options can be overridden using the [defaults] section:
790 PARAMETER EXAMPLE DESCRIPTION
791 -----------------------------------
792 mempool size 16K number of mbufs per task, relevant when task receives from a port.
793 this is the n argument provided to rte_mempool_create()
794 qinq tag 0xa888 Set qinq tag for all tasks. The result of adding this option is the
795 same as adding qinq tag= to each task
796 memcache size 128 number of mbufs cached per core, default is 256 this is the cache_size
797 argument provided to rte_mempool_create()
799 * [GLOBAL]: The following parameters are supported:
803 PARAMETER EXAMPLE DESCRIPTION
804 -------------------------------------------------
805 name BNG Name of the configuration, which will be shown in the title box at runtime.
806 start time 10 Time in seconds after which average statistics will be started.
808 duration time 30 Runtime duration in seconds, counted after start time.
809 This is typically useful to automate testing using
810 different parameters: PROX automatically exits when the
811 runtime duration has elapsed. Initialization and start time
812 are not included in this runtime duration.
813 For example, if start time is set to 10 and duration time is set to 30,
814 the total execution time (after initialization) will be 40 seconds.
815 Default value is 0, which means infinity and prevents PROX from automatically exiting.
816 shuffle yes When this parameter is set to yes, the order of mbufs
817 within mempools is randomized to simulate a system that has
818 been warmed up. Default value is no.
819 gre cfg /path/to/file.csv Path to CSV file that provides QinQ-to-GRE mapping.
820 Default value is gre_table.csv in same directory as
821 configuration file. Fields are GRE key and QinQ value (computed as SVLAN * 4096 + CVLAN).
822 pre cmd ls Arbitrary system commands to run while reading cfg. This option can occur multiple times.
823 user cfg /path/to/file.csv Path to CSV file that provides QinQ-to-User mapping.
824 Default value is user_table.csv in same directory as configuration file.
825 Fields are SVLAN, CVLAN and User-Id.
826 next hop cfg /path/to/file.csv Path to CSV file that provides Next-Hop details.
827 Default value is next_hop.csv in same directory as configuration file.
828 Fields are Next-Hop index (as returned by LPM lookup),
829 Out-Port index, Next-Hop IP (unused), Next-Hop MAC and MPLS label.
830 ipv4 cfg /path/to/file.csv Path to CSV file that provides IPv4 LPM routing table.
831 Default value is ipv4.csv in same directory as configuration file.
832 Fields are IPv4 subnet (in CIDR notation) and Next-Hop index.
833 dscp cfg /path/to/file.csv Path to CSV file that provides mapping for QoS classification,
834 from DSCP to Traffic Class and Queue.
835 Default value is dscp.csv in same directory as configuration file.
836 Fields are DSCP (0-63), Traffic Class (0-3) and Queue (0-3).
837 ipv6 tunnel cfg /path/to/file.csv Path to CSV file that provides lwAFTR binding table.
838 Default value is ipv6_tun_bind.csv in same directory as configuration file.
839 Fields are lwB4 IPv6 address, next hop MAC address towards lwB4,
840 IPv4 Public address and IPv4 Public Port Set.
841 acl cfg /path/to/file.csv Path to CSV file that provides ACL rules.
842 Default value is rules.csv in same directory as configuration file.
843 Fields are SVLAN value & mask, CVLAN value & mask, IP protocol value & mask,
844 source IPv4 subnet (in CIDR notation), destination IPv4 subnet (in CIDR notation),
845 source port range, destination port range, and action (drop, allow, rate limit).
849 * [CORE #]: Cores can be configured by means of a set of [core #] sections, where # represents either:
851 an absolute core number: e.g. on a 10-core, dual socket system with hyper-threading, cores are numbered from 0 to 39;
852 a core number, the letter 's', and a socket number: this allows selecting per-socket cores, independently from their interleaved numbering;
853 a core number and the letter 'h': this allows selecting the hyper-thread sibling of the specified core;
854 a dash-separated range of core numbers; a comma-separated list of core numbers; any combination of the above;
855 or a variable whose value complies with the above syntax.
856 The socket and hyper-thread syntax makes it easier to use the same configuration file on several platforms,
857 even if their core numbering differs (e.g. interleaving rule or number of cores per socket).
859 Each core can be assigned with a set of tasks, each running one of the implemented packet processing modes.
861 The following parameters are supported:
863 .. image:: images/prox_core.png
865 :alt: SampleVNF supported topology
867 Compiling and running this application
868 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
872 DPDK must be installed prior to running make in the PROX directory.
873 The README file shipped with PROX describes what versions of DPDK are supported,
874 and if any patches are needed for the chosen DPDK version.
876 The following packages need to be installed. (Example for destributions that are using rpm)
880 sudo yum install net-tools wget gcc unzip libpcap-devel ncurses-devel libedit-devel pciutils lua-devel kernel-devel
883 The following instructions are here to help customers to start using PROX.
884 It's by no means a complete guide, for detailed instructions on how to install and use
885 DPDK please refer to its documentation.
886 Your mileage may vary depending on a particular Linux distribution and hardware in use.
888 Edit grub default configuration:
894 Add the following to the kernel boot parameters
898 default_hugepagesz=1G hugepagesz=1G hugepages=8
900 Rebuild grub config and reboot the system:
904 grub2-mkconfig -o /boot/grub2/grub.cfg
907 Verify that hugepages are available
915 Hugepagesize: 1048576 kB
923 umount `awk '/hugetlbfs/ { print $2 }' /proc/mounts` >/dev/null 2>&1
924 mount -t hugetlbfs nodev /mnt/huge/
926 This application supports DPDK 16.04, 16.11, 17.02 and 17.05.
927 The following commands assume that the following variables have been set:
929 export RTE_SDK=/path/to/dpdk
930 export RTE_TARGET=x86_64-native-linuxapp-gcc
932 PROX Compiation installation
933 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
935 * git clone https://git.opnfv.org/samplevnf
937 * export RTE_SDK=`pwd`/dpdk
938 * export RTE_TARGET=x86_64-native-linuxapp-gcc
939 * git clone http://dpdk.org/git/dpdk
941 * git checkout v17.05
942 * make install T=$RTE_TARGET
943 * cd <samplevnf>/VNFs/DPPD-PROX
950 * git clone https://git.opnfv.org/samplevnf
952 * ./tools/vnf_build.sh -s -d='17.05' [-p=<proxy> if behind the proxy]
958 lsmod | grep -w "^uio" >/dev/null 2>&1 || sudo modprobe uio
965 lsmod | grep -w "^igb_uio" >/dev/null 2>&1 || sudo insmod $RTE_SDK/$RTE_TARGET/kmod/igb_uio.ko
967 Discover network devices available on the system:
971 lspci | grep Ethernet
973 Prior launching PROX, ports that are to be used by it must be bound to the igb_uio driver.
975 The following command will bind all Intel® Ethernet Converged Network Adapter X710 ports to igb_uio:
979 lspci | grep X710 | cut -d' ' -f 1 | sudo xargs -I {} python2.7 $RTE_UNBIND --bind=igb_uio {}
981 The following command will bind all Intel® 82599 10 Gigabit Ethernet Controller ports to igb_uio:
985 lspci | grep 82599 | cut -d' ' -f 1 | sudo xargs -I {} python2.7 $RTE_UNBIND --bind=igb_uio {}
990 The Makefile with this application expects RTE_SDK to point to the
991 root directory of DPDK (e.g. export RTE_SDK=/root/dpdk). If RTE_TARGET
992 has not been set, x86_64-native-linuxapp-gcc will be assumed.
997 After DPDK has been set up, run make from the directory where you have
998 extracted this application. A build directory will be created
999 containing the PROX executable. The usage of the application is shown
1000 below. Note that this application assumes that all required ports have
1001 been bound to the DPDK provided igb_uio driver. Refer to the "Getting
1002 Started Guide - DPDK" document for more details.
1006 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]
1007 -f CONFIG_FILE : configuration file to load, ./prox.cfg by default
1008 -l LOG_FILE : log file name, ./prox.log by default
1009 -p : include PID in log file name if default log file is used
1010 -o DISPLAY: Set display to use, can be 'curses' (default), 'cli' or 'none'
1011 -v verbosity : initial logging verbosity
1012 -a : autostart all cores (by default)
1013 -e : don't autostart
1014 -n : Create NULL devices instead of using PCI devices, useful together with -i
1015 -m : list supported task modes and exit
1016 -s : check configuration file syntax and exit
1017 -i : check initialization sequence and exit
1018 -u : Listen on UDS /tmp/prox.sock
1019 -t : Listen on TCP port 8474
1020 -q : Pass argument to Lua interpreter, useful to define variables
1021 -w : define variable using syntax varname=value
1022 takes precedence over variables defined in CONFIG_FILE
1023 -k : Log statistics to file "stats_dump" in current directory
1024 -d : Run as daemon, the parent process will block until PROX is not initialized
1025 -z : Ignore CPU topology, implies -i
1026 -r : Change initial screen refresh rate. If set to a lower than 0.001 seconds,
1027 screen refreshing will be disabled
1029 While applications using DPDK typically rely on the core mask and the
1030 number of channels to be specified on the command line, this
1031 application is configured using a .cfg file. The core mask and number
1032 of channels is derived from this config. For example, to run the
1033 application from the source directory execute:
1037 user@target:~$ ./build/prox -f ./config/nop.cfg
1039 Provided example configurations
1040 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1041 PROX can be configured either as the SUT (System Under Test) or as the
1042 Traffic Generator. Some example configuration files are provided, both
1043 in the config directory to run PROX as a SUT, and in the gen directory
1044 to run it as a Traffic Generator.
1045 A quick description of these example configurations is provided below.
1046 Additional details are provided in the example configuration files.
1048 Basic configurations, mostly used as sanity check:
1053 * config/nop-rings.cfg
1056 Simplified BNG (Border Network Gateway) configurations, using different
1057 number of ports, with and without QoS, running on the host or in a VM:
1061 * config/bng-4ports.cfg
1062 * config/bng-8ports.cfg
1063 * config/bng-qos-4ports.cfg
1064 * config/bng-qos-8ports.cfg
1065 * config/bng-1q-4ports.cfg
1066 * config/bng-ovs-usv-4ports.cfg
1067 * config/bng-no-cpu-topology-4ports.cfg
1068 * gen/bng-4ports-gen.cfg
1069 * gen/bng-8ports-gen.cfg
1070 * gen/bng-ovs-usv-4ports-gen.cfg
1072 Light-weight AFTR configurations:
1076 * config/lw_aftr.cfg
1077 * gen/lw_aftr-gen.cfg