diff options
| -rw-r--r-- | docs/testing/user/userguide/02-methodology.rst | 2 | ||||
| -rwxr-xr-x | docs/testing/user/userguide/03-architecture.rst | 5 | ||||
| -rw-r--r-- | docs/testing/user/userguide/04-installation.rst | 67 | ||||
| -rw-r--r-- | docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst | 465 | ||||
| -rw-r--r-- | docs/testing/user/userguide/06-How_to_use_REST_api.rst | 323 | ||||
| -rw-r--r-- | docs/testing/user/userguide/07-Config_files.rst | 121 | ||||
| -rw-r--r-- | docs/testing/user/userguide/09-prox.rst | 479 | ||||
| -rw-r--r-- | docs/testing/user/userguide/images/prox_core.png | bin | 0 -> 651187 bytes | |||
| -rw-r--r-- | docs/testing/user/userguide/index.rst | 1 |
9 files changed, 1012 insertions, 451 deletions
diff --git a/docs/testing/user/userguide/02-methodology.rst b/docs/testing/user/userguide/02-methodology.rst index 5550fec9..01cbb276 100644 --- a/docs/testing/user/userguide/02-methodology.rst +++ b/docs/testing/user/userguide/02-methodology.rst @@ -11,7 +11,7 @@ Abstract ======== This chapter describes the methodology/overview of SampleVNF project from -the perspective of a :term:`VNF` and verifying the :term:`NFVI` +the perspective of a :term:`VNF` and :term:`NFVI` Characterization Overview ======== diff --git a/docs/testing/user/userguide/03-architecture.rst b/docs/testing/user/userguide/03-architecture.rst index 3654c43a..62a17349 100755 --- a/docs/testing/user/userguide/03-architecture.rst +++ b/docs/testing/user/userguide/03-architecture.rst @@ -9,7 +9,7 @@ Architecture Abstract ======== -This chapter describes the samplevnf software architecture. +This chapter describes the samplevnf software architecture. we will introduce it VNFs. More technical details will be introduced in this chapter. Overview @@ -79,6 +79,7 @@ VNF supported Intel® DPPD - PROX is an application built on top of DPDK which allows creating software architectures, such as the one depicted below, through small and readable configuration files. + This VNF can act as L2FWD, L3FWD, BNG etc. Test Framework -------------- @@ -111,3 +112,5 @@ SampleVNF Directory structure *VNFs/* - all VNF source code directory. *VNF_Catalogue/* - Collection of all Open Source VNFs + +*heat_template/* - Sample HEAT templates for VNFs diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst index 9a31ecdc..3b925759 100644 --- a/docs/testing/user/userguide/04-installation.rst +++ b/docs/testing/user/userguide/04-installation.rst @@ -108,6 +108,11 @@ The connectivity could be TG:port 0 <------> VNF:Port 0 TG:port 1 <------> VNF:Port 1 + For correalted traffic, use below configuration + TG_1:port 0 <------> VNF:Port 0 + VNF:Port 1 <------> TG_2:port 0 (UDP Replay) + (TG_2(UDP_Replay) reflects all the traffic on the given port) + 2) Multi port pair : More than one pair of traffic :: @@ -120,7 +125,9 @@ The connectivity could be For correalted traffic, use below configuration TG_1:port 0 <------> VNF:Port 0 - VNF:Port 1 <------> TG_2:port 0 (UDP Replay) + VNF:Port 1 <------> TG_2:port 0 (UDP Replay) + TG_1:port 1 <------> VNF:Port 2 + VNF:Port 3 <------> TG_2:port 1 (UDP Replay) (TG_2(UDP_Replay) reflects all the traffic on the given port) * Bare-Metal @@ -148,9 +155,7 @@ Build VNFs on the DUT: Auto Build - Using script to build VNFs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Interactive options: - :: - ./tools/vnf_build.sh -i Follow the steps in the screen from option [1] –> [9] and select option [8] to build the vnfs. @@ -179,52 +184,42 @@ Auto Build - Using script to build VNFs [8] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay, DPPD-PROX) [9] Exit Script - * non-Interactive options: + * non-Interactive options: :: - ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> Manual Build ^^^^^^^^^^^^ :: - 1. Download DPDK supported version from dpdk.org - http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip - unzip dpdk-$DPDK_RTE_VER.zip and apply dpdk patches only in case of 16.04 (Not required for other DPDK versions) - cd dpdk - make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc - cd x86_64-native-linuxapp-gcc - make -j - 2. Setup huge pages - For 1G/2M hugepage sizes, for example 1G pages, the size must be specified - explicitly and can also be optionally set as the default hugepage size - for the system. For example, to reserve 8G of hugepage memory in the form - of eight 1G pages, the following options should be passed to the - kernel: * default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048 - 3. Add this to Go to /etc/default/grub configuration file. - Append “default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048”to the GRUB_CMDLINE_LINUX entry. - 4. Setup Environment Variable - export RTE_SDK=<samplevnf>/dpdk - export RTE_TARGET=x86_64-native-linuxapp-gcc - export VNF_CORE=<samplevnf> - or using ./tools/setenv.sh - 5. Build vACL VNFs - cd <samplevnf>/VNFs/vACL - make clean - make - The vACL executable will be created at the following location - <samplevnf>/VNFs/vACL/build/vACL + * http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip + * unzip dpdk-$DPDK_RTE_VER.zip and apply dpdk patches only in case of 16.04 (Not required for other DPDK versions) + * cd dpdk + * make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc + * cd x86_64-native-linuxapp-gcc + * make -j + 2. Add this to Go to /etc/default/grub configuration file to setup hugepages. + * Append “default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048” to the GRUB_CMDLINE_LINUX entry. + 3. Setup Environment Variable + * export RTE_SDK=<samplevnf>/dpdk + * export RTE_TARGET=x86_64-native-linuxapp-gcc + * export VNF_CORE=<samplevnf> or using ./tools/setenv.sh + 4. Build SampleVNFs e.g, vACL + * cd <samplevnf>/VNFs/vACL + * make clean + * make + * The vACL executable will be created at the following location + <samplevnf>/VNFs/vACL/build/vACL 2) Standalone virtualization/Openstack: Build VM image from script in yardstick - :: - - 1) git clone https://git.opnfv.org/yardstick - 2) cd yardstick and run - ./tools/yardstick-img-modify tools/ubuntu-server-cloudimg-samplevnf-modify.sh + 1) git clone https://git.opnfv.org/samplevnf + 2) cd samplevnf and run + ./tools/samplevnf-img-dpdk-samplevnf-modify tools/ubuntu-server-cloudimg-samplevnf-modify.sh + Image available in: /tmp/workspace/samplevnf/xenial-server-cloudimg-amd64-disk1.img To run VNFs. Please refer chapter `05-How_to_run_SampleVNFs.rst` diff --git a/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst b/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst index 29c76e69..3835a439 100644 --- a/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst +++ b/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst @@ -42,7 +42,7 @@ SUT requirements: +-----------+------------------+ | OS | Ubuntu 16.04 LTS | +-----------+------------------+ - | kernel | 4.4.0-34-generic| + | kernel | 4.4.0-34-generic | +-----------+------------------+ | DPDK | 17.02 | +-----------+------------------+ @@ -75,12 +75,19 @@ SRIOV or OVS) setup based on the test profile. The connectivity could be 1) Single port pair : One pair ports used for traffic + :: e.g. Single port pair link0 and link1 of VNF are used TG:port 0 <------> VNF:Port 0 TG:port 1 <------> VNF:Port 1 + For correalted traffic, use below configuration + TG_1:port 0 <------> VNF:Port 0 + VNF:Port 1 <------> TG_2:port 0 (UDP Replay) + (TG_2(UDP_Replay) reflects all the traffic on the given port) + 2) Multi port pair : More than one pair of traffic + :: e.g. Two port pair link 0, link1, link2 and link3 of VNF are used TG:port 0 <------> VNF:Port 0 @@ -90,8 +97,11 @@ The connectivity could be For correalted traffic, use below configuration TG_1:port 0 <------> VNF:Port 0 - VNF:Port 1 <------> TG_2:port 0 (UDP Replay) + VNF:Port 1 <------> TG_2:port 0 (UDP Replay) + TG_1:port 1 <------> VNF:Port 2 + VNF:Port 3 <------> TG_2:port 1 (UDP Replay) (TG_2(UDP_Replay) reflects all the traffic on the given port) + * Bare-Metal Refer: http://fast.dpdk.org/doc/pdf-guides/ to setup the DUT for VNF to run @@ -114,17 +124,19 @@ Setup Traffic generator Step 0: Preparing hardware connection Connect Traffic generator and VNF system back to back as shown in previous section - TRex port 0 ↔ (VNF Port 0) ↔ (VNF Port 1) ↔ TRex port 1 + + :: + TRex port 0 ↔ (VNF Port 0) ↔ (VNF Port 1) ↔ TRex port 1 Step 1: Setting up Traffic generator (TRex) TRex Software preparations - ^^^^^^^^^^^^^^^^^^^^^^^^^^ - * Install the OS (Bare metal Linux, not VM!) - * Obtain the latest TRex package: wget https://trex-tgn.cisco.com/trex/release/latest - * Untar the package: tar -xzf latest - * Change dir to unzipped TRex - * Create config file using command: sudo python dpdk_setup_ports.py -i + ************************** + * Install the OS (Bare metal Linux, not VM!) + * Obtain the latest TRex package: wget https://trex-tgn.cisco.com/trex/release/latest + * Untar the package: tar -xzf latest + * Change dir to unzipped TRex + * Create config file using command: sudo python dpdk_setup_ports.py -i In case of Ubuntu 16 need python3 See paragraph config creation for detailed step-by-step (Refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html) @@ -140,89 +152,87 @@ Step 2: Procedure to build SampleVNFs Auto Build ^^^^^^^^^^ - * Interactive options: :: - - ./tools/vnf_build.sh -i - Follow the steps in the screen from option [1] –> [9] and select option [8] to build the vnfs. - It will automatically download selected DPDK version and any required patches and will setup everything and build VNFs. - Following are the options for setup: - ---------------------------------------------------------- - Step 1: Environment setup. - ---------------------------------------------------------- - [1] Check OS and network connection - [2] Select DPDK RTE version - - ---------------------------------------------------------- - Step 2: Download and Install - ---------------------------------------------------------- - [3] Agree to download - [4] Download packages - [5] Download DPDK zip - [6] Build and Install DPDK - [7] Setup hugepages - [8] Download civetweb - - ---------------------------------------------------------- - Step 3: Build VNFs - ---------------------------------------------------------- - [9] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay, DPPD-PROX) - - [10] Exit Script + ./tools/vnf_build.sh -i + Follow the steps in the screen from option [1] –> [9] and select option [8] to build the vnfs. + It will automatically download selected DPDK version and any required patches and will setup everything and build VNFs. + Following are the options for setup: + ---------------------------------------------------------- + Step 1: Environment setup. + ---------------------------------------------------------- + [1] Check OS and network connection + [2] Select DPDK RTE version + + ---------------------------------------------------------- + Step 2: Download and Install + ---------------------------------------------------------- + [3] Agree to download + [4] Download packages + [5] Download DPDK zip + [6] Build and Install DPDK + [7] Setup hugepages + [8] Download civetweb + + ---------------------------------------------------------- + Step 3: Build VNFs + ---------------------------------------------------------- + [9] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay, DPPD-PROX) + + [10] Exit Script * Non-Interactive options: :: - - ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> + ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> + if system is behind the proxy + ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> -p=<proxy> Manual Build ^^^^^^^^^^^^ :: - - 1) Download DPDK supported version from dpdk.org - http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip - unzip dpdk-$DPDK_RTE_VER.zip and apply dpdk patches only in case of 16.04 (Not required for other DPDK versions) - cd dpdk - make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc - cd x86_64-native-linuxapp-gcc - make - - 2) Download civetweb 1.9 version from the following link - https://sourceforge.net/projects/civetweb/files/1.9/CivetWeb_V1.9.zip - unzip CivetWeb_V1.9.zip - mv civetweb-master civetweb - cd civetweb - make lib - - 3) Setup huge pages - For 1G/2M hugepage sizes, for example 1G pages, the size must be - specified explicitly and can also be optionally set as the - default hugepage size for the system. For example, to reserve 8G - of hugepage memory in the form of eight 1G pages, the following - options should be passed to the kernel: * default_hugepagesz=1G - hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048 - 4) Add this to Go to /etc/default/grub configuration file. - Append “default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048” - to the GRUB_CMDLINE_LINUX entry. - 5) Setup Environment Variable - export RTE_SDK=<samplevnf>/dpdk - export RTE_TARGET=x86_64-native-linuxapp-gcc - export VNF_CORE=<samplevnf> - or using ./tools/setenv.sh - 6) Build VNFs - cd <samplevnf> - make - or to build individual VNFs - cd <samplevnf>/VNFs/ - make clean - make - The vFW executable will be created at the following location - <samplevnf>/VNFs/vFW/build/vFW + 1) Download DPDK supported version from dpdk.org + http://dpdk.org/browse/dpdk/snapshot/dpdk-$DPDK_RTE_VER.zip + unzip dpdk-$DPDK_RTE_VER.zip and apply dpdk patches only in case of 16.04 (Not required for other DPDK versions) + cd dpdk + make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc + cd x86_64-native-linuxapp-gcc + make + + 2) Download civetweb 1.9 version from the following link + https://sourceforge.net/projects/civetweb/files/1.9/CivetWeb_V1.9.zip + unzip CivetWeb_V1.9.zip + mv civetweb-master civetweb + cd civetweb + make lib + + 3) Setup huge pages + For 1G/2M hugepage sizes, for example 1G pages, the size must be + specified explicitly and can also be optionally set as the + default hugepage size for the system. For example, to reserve 8G + of hugepage memory in the form of eight 1G pages, the following + options should be passed to the kernel: * default_hugepagesz=1G + hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048 + 4) Add this to Go to /etc/default/grub configuration file. + Append “default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048” + to the GRUB_CMDLINE_LINUX entry. + 5) Setup Environment Variable + export RTE_SDK=<samplevnf>/dpdk + export RTE_TARGET=x86_64-native-linuxapp-gcc + export VNF_CORE=<samplevnf> + or using ./tools/setenv.sh + 6) Build VNFs + cd <samplevnf> + make + or to build individual VNFs + cd <samplevnf>/VNFs/ + make clean + make + The vFW executable will be created at the following location + <samplevnf>/VNFs/vFW/build/vFW Virtual Firewall - How to run @@ -234,58 +244,57 @@ a) Bind ports to DPDK :: - For DPDK versions 17.xx - 1) cd <samplevnf>/dpdk - 2) ./usertools/dpdk-devbind.py --status <--- List the network device - 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> - .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules + For DPDK versions 17.xx + 1) cd <samplevnf>/dpdk + 2) ./usertools/dpdk-devbind.py --status <--- List the network device + 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> + .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules b) Prepare script to enalble VNF to route the packets :: - cd <samplevnf>/VNFs/vFW/config - Open -> VFW_SWLB_SinglePortPair_script.tc. Replace the bold items based on your setting. - - link 0 config <VNF port 0 IP eg 202.16.100.10> 8 - link 0 up - link 1 down - link 1 config <VNF port 0 IP eg 172.16.40.10> 8 - link 1 up - - ; routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask> - routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000 - routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000 - - ; IPv4 static ARP; disable if dynamic arp is enabled. - p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC> - p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC> - p action add 0 accept - p action add 0 fwd 0 - p action add 0 count - p action add 1 accept - p action add 1 fwd 1 - p action add 1 count - p action add 2 drop - p action add 2 count - p action add 0 conntrack - p action add 1 conntrack - p action add 2 conntrack - p action add 3 conntrack - ; IPv4 rules - 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 - 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 - 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 - p vfw applyruleset - + cd <samplevnf>/VNFs/vFW/config + Open -> VFW_SWLB_SinglePortPair_script.tc. Replace the bold items based on your setting. + + link 0 config <VNF port 0 IP eg 202.16.100.10> 8 + link 0 up + link 1 down + link 1 config <VNF port 0 IP eg 172.16.40.10> 8 + link 1 up + + ; routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask> + routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000 + routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000 + + ; IPv4 static ARP; disable if dynamic arp is enabled. + p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC> + p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC> + p action add 0 accept + p action add 0 fwd 0 + p action add 0 count + p action add 1 accept + p action add 1 fwd 1 + p action add 1 count + p action add 2 drop + p action add 2 count + p action add 0 conntrack + p action add 1 conntrack + p action add 2 conntrack + p action add 3 conntrack + ; IPv4 rules + 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 + 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 + 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 + p vfw applyruleset c) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk. :: - cd <samplevnf>/VNFs/vFW/ - ./build/vFW -p 0x3 -f ./config/VFW_SWLB_SinglePortPair_4Thread.cfg -s ./config/VFW_SWLB_SinglePortPair_script.tc + cd <samplevnf>/VNFs/vFW/ + ./build/vFW -p 0x3 -f ./config/VFW_SWLB_SinglePortPair_4Thread.cfg -s ./config/VFW_SWLB_SinglePortPair_script.tc step 4: Run Test using traffic geneator @@ -319,58 +328,58 @@ a) Bind ports to DPDK :: - For DPDK versions 17.xx - 1) cd <samplevnf>/dpdk - 2) ./usertools/dpdk-devbind.py --status <--- List the network device - 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> - .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules + For DPDK versions 17.xx + 1) cd <samplevnf>/dpdk + 2) ./usertools/dpdk-devbind.py --status <--- List the network device + 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> + .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules b) Prepare script to enalble VNF to route the packets :: - cd <samplevnf>/VNFs/vACL/config - Open -> IPv4_swlb_acl.tc. Replace the bold items based on your setting. - - link 0 config <VNF port 0 IP eg 202.16.100.10> 8 - link 0 up - link 1 down - link 1 config <VNF port 0 IP eg 172.16.40.10> 8 - link 1 up - - ; routeadd <port #> <ipv4 nhip address in decimal> <Mask> - routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000 - routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000 - - ; IPv4 static ARP; disable if dynamic arp is enabled. - p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC> - p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC> - p action add 0 accept - p action add 0 fwd 0 - p action add 0 count - p action add 1 accept - p action add 1 fwd 1 - p action add 1 count - p action add 2 drop - p action add 2 count - p action add 0 conntrack - p action add 1 conntrack - p action add 2 conntrack - p action add 3 conntrack - ; IPv4 rules - 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 - 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 - 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 - p acl applyruleset + cd <samplevnf>/VNFs/vACL/config + Open -> IPv4_swlb_acl.tc. Replace the bold items based on your setting. + + link 0 config <VNF port 0 IP eg 202.16.100.10> 8 + link 0 up + link 1 down + link 1 config <VNF port 0 IP eg 172.16.40.10> 8 + link 1 up + + ; routeadd <port #> <ipv4 nhip address in decimal> <Mask> + routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000 + routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000 + + ; IPv4 static ARP; disable if dynamic arp is enabled. + p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC> + p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC> + p action add 0 accept + p action add 0 fwd 0 + p action add 0 count + p action add 1 accept + p action add 1 fwd 1 + p action add 1 count + p action add 2 drop + p action add 2 count + p action add 0 conntrack + p action add 1 conntrack + p action add 2 conntrack + p action add 3 conntrack + ; IPv4 rules + 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 + 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 + 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 + p acl applyruleset c) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk. :: - cd <samplevnf>/VNFs/vFW/ - ./build/vFW -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg -s ./config/IPv4_swlb_acl.tc. + cd <samplevnf>/VNFs/vFW/ + ./build/vFW -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg -s ./config/IPv4_swlb_acl.tc. step 4: Run Test using traffic geneator @@ -404,70 +413,72 @@ Step 3: Bind the datapath ports to DPDK :: - For DPDK versions 17.xx - 1) cd <samplevnf>/dpdk - 2) ./usertools/dpdk-devbind.py --status <--- List the network device - 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> - .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules + For DPDK versions 17.xx + 1) cd <samplevnf>/dpdk + 2) ./usertools/dpdk-devbind.py --status <--- List the network device + 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> + .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules b) Prepare script to enalble VNF to route the packets :: - cd <samplevnf>/VNFs/vCGNAPT/config - Open -> sample_swlb_2port_2WT.tc Replace the bold items based on your setting. + cd <samplevnf>/VNFs/vCGNAPT/config + Open -> sample_swlb_2port_2WT.tc Replace the bold items based on your setting. - link 0 config <VNF port 0 IP eg 202.16.100.10> 8 - link 0 up - link 1 down - link 1 config <VNF port 0 IP eg 172.16.40.10> 8 - link 1 up + link 0 config <VNF port 0 IP eg 202.16.100.10> 8 + link 0 up + link 1 down + link 1 config <VNF port 0 IP eg 172.16.40.10> 8 + link 1 up - ; uncomment to enable static NAPT - ;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> - ;p 5 entry addm 202.16.100.20 1234 152.16.40.10 1 0 500 65535 1234 65535 + ; uncomment to enable static NAPT + ;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> + ;p 5 entry addm 202.16.100.20 1234 152.16.40.10 1 0 500 65535 1234 65535 - ; routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask> - routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000 - routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000 + ; routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask> + routeadd net 0 <traffic generator port 0 IP eg 202.16.100.20> 0xff000000 + routeadd net 1 <traffic generator port 1 IP eg 172.16.40.20> 0xff000000 - ; IPv4 static ARP; disable if dynamic arp is enabled. - p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC> - p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC> - For dynamic cgnapt. Please use UDP_Replay as one of the traffic generator - (TG1) (port 0) --> (port 0) VNF (CGNAPT) (Port 1) --> (port0)(UDPReplay) + ; IPv4 static ARP; disable if dynamic arp is enabled. + p 1 arpadd 0 <traffic generator port 0 IP eg 202.16.100.20> <traffic generator port 0 MAC> + p 1 arpadd 1 <traffic generator port 1 IP eg 172.16.40.20> <traffic generator port 1 MAC> + For dynamic cgnapt. Please use UDP_Replay as one of the traffic generator + (TG1) (port 0) --> (port 0) VNF (CGNAPT) (Port 1) --> (port0)(UDPReplay) c) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk. :: - cd <samplevnf>/VNFs/vCGNAPT/ - ./build/vCGNAPT -p 0x3 -f ./config/sample_swlb_2port_2WT.cfg -s ./config/sample_swlb_2port_2WT.tc + cd <samplevnf>/VNFs/vCGNAPT/ + ./build/vCGNAPT -p 0x3 -f ./config/sample_swlb_2port_2WT.cfg -s ./config/sample_swlb_2port_2WT.tc + d) Run UDP_replay to reflect the traffic on public side. + cmd: ./build/UDP_Replay -c 0x7 -n 4 -w <pci> -w <pci> -- --no-hw-csum -p <portmask> --config='(port, queue, cpucore)' + 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)' step 4: Run Test using traffic geneator - On traffic generator system: + On traffic generator system: :: + cd <trex eg v2.28/stl> + Update the bench.py to generate the traffic. - cd <trex eg v2.28/stl> - Update the bench.py to generate the traffic. - - class STLBench(object): - ip_range = {} - 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>'} - ip_range['dst'] = {'start': '<traffic generator port 1 IP eg 172.16.40.20>', 'end': '<public ip e.g 152.16.40.10>'} - cd <trex eg v2.28> - Run the TRex server: sudo ./t-rex-64 -i -c 7 - In another shell run TRex console: trex-console - The console can be run from another computer with -s argument, --help for more info. - Other options for TRex client are automation or GUI - In the console, run "tui" command, and then send the traffic with commands like: - start -f stl/bench.py -m 50% --port 0 3 -t size=590,vm=var1 - For more details refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html + class STLBench(object): + ip_range = {} + 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>'} + ip_range['dst'] = {'start': '<traffic generator port 1 IP eg 172.16.40.20>', 'end': '<public ip e.g 152.16.40.10>'} + cd <trex eg v2.28> + Run the TRex server: sudo ./t-rex-64 -i -c 7 + In another shell run TRex console: trex-console + The console can be run from another computer with -s argument, --help for more info. + Other options for TRex client are automation or GUI + In the console, run "tui" command, and then send the traffic with commands like: + start -f stl/bench.py -m 50% --port 0 3 -t size=590,vm=var1 + For more details refer: https://trex-tgn.cisco.com/trex/doc/trex_stateless_bench.html UDP_Replay - How to run @@ -479,19 +490,19 @@ Step 3: Bind the datapath ports to DPDK :: - For DPDK versions 17.xx - 1) cd <samplevnf>/dpdk - 2) ./usertools/dpdk-devbind.py --status <--- List the network device - 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> - .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules + For DPDK versions 17.xx + 1) cd <samplevnf>/dpdk + 2) ./usertools/dpdk-devbind.py --status <--- List the network device + 3) ./usertools/dpdk-devbind.py -b igb_uio <PCI Port 0> <PCI Port 1> + .. _More details: http://dpdk.org/doc/guides-17.05/linux_gsg/build_dpdk.html#binding-and-unbinding-network-ports-to-from-the-kernel-modules b) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk. :: - cd <samplevnf>/VNFs/UDP_Replay/ - cmd: ./build/UDP_Replay -c 0x7 -n 4 -w <pci> -w <pci> -- --no-hw-csum -p <portmask> --config='(port, queue, cpucore)' - 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)' + cd <samplevnf>/VNFs/UDP_Replay/ + cmd: ./build/UDP_Replay -c 0x7 -n 4 -w <pci> -w <pci> -- --no-hw-csum -p <portmask> --config='(port, queue, cpucore)' + 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)' step 4: Run Test using traffic geneator @@ -592,6 +603,7 @@ application is configured using a .cfg file. The core mask and number of channels is derived from this config. For example, to run the application from the source directory execute: +:: user@target:~$ ./build/prox -f ./config/nop.cfg Provided example configurations @@ -604,24 +616,29 @@ A quick description of these example configurations is provided below. Additional details are provided in the example configuration files. Basic configurations, mostly used as sanity check: -- config/nop.cfg -- config/nop-rings.cfg -- gen/nop-gen.cfg + +:: + - config/nop.cfg + - config/nop-rings.cfg + - gen/nop-gen.cfg Simplified BNG (Border Network Gateway) configurations, using different number of ports, with and without QoS, running on the host or in a VM: -- config/bng-4ports.cfg -- config/bng-8ports.cfg -- config/bng-qos-4ports.cfg -- config/bng-qos-8ports.cfg -- config/bng-1q-4ports.cfg -- config/bng-ovs-usv-4ports.cfg -- config/bng-no-cpu-topology-4ports.cfg -- gen/bng-4ports-gen.cfg -- gen/bng-8ports-gen.cfg -- gen/bng-ovs-usv-4ports-gen.cfg + +:: + - config/bng-4ports.cfg + - config/bng-8ports.cfg + - config/bng-qos-4ports.cfg + - config/bng-qos-8ports.cfg + - config/bng-1q-4ports.cfg + - config/bng-ovs-usv-4ports.cfg + - config/bng-no-cpu-topology-4ports.cfg + - gen/bng-4ports-gen.cfg + - gen/bng-8ports-gen.cfg + - gen/bng-ovs-usv-4ports-gen.cfg Light-weight AFTR configurations: -- config/lw_aftr.cfg -- gen/lw_aftr-gen.cfg +:: + - config/lw_aftr.cfg + - gen/lw_aftr-gen.cfg diff --git a/docs/testing/user/userguide/06-How_to_use_REST_api.rst b/docs/testing/user/userguide/06-How_to_use_REST_api.rst index 53726464..658f99d3 100644 --- a/docs/testing/user/userguide/06-How_to_use_REST_api.rst +++ b/docs/testing/user/userguide/06-How_to_use_REST_api.rst @@ -4,7 +4,7 @@ .. (c) opnfv, national center of scientific research "demokritos" and others. ======================================================== -REST API - Readme +REST API ======================================================== Introduction @@ -65,128 +65,81 @@ Civetweb exposes a few functions which are used to resgister custom handlers for different URI’s that are implemented. Typical usage is shown below - -VNF Application init() -========================= - -Initialize the civetweb library -================================ - -mg_init_library(0); - -Start the web server -===================== -ctx = mg_start(NULL, 0, options); - - -Once the civetweb server is started we can register our URI’s as show below -mg_set_request_handler(ctx, "/config", static_cfg_handler, 0); - -In the above example “/config” is the URI & static_cfg_handler() is -the handler that gets called when a user invokes this URI through -the HTTP client. API's have been mostly implemented for existing VNF's -like vCGNAPT, vFW & vACL. you might want to implement custom handlers -for your VNF. - URI definition for different VNF’s -=================================== - - -URI REST Method Arguments Description -=========================================================================================================================== -/vnf GET None Displays top level methods available - -/vnf/config GET None Displays the current config set - POST pci_white_list: Command success/failure - num_worker(o): - vnf_type(o): - pkt_type (o): - num_lb(o): - sw_lb(o): - sock_in(o): - hyperthread(o) : - -/vnf/config/arp GET None Displays ARP/ND info - POST action: <add/del/req> Command success/failure - ipv4/ipv6: <address> - portid: <> - macaddr: <> for add - -/vnf/config/link GET None - POST link_id:<> Command success/failure - state: <1/0> - -/vnf/config/link/<link id> GET None - POST ipv4/ipv6: <address> Command success/failure - depth: <> - - -/vnf/config/route GET None Displays gateway route entries - POST portid: <> Adds route entries for default gateway - nhipv4/nhipv6: <addr> - depth: <> - type:"net/host" - -/vnf/config/rules(vFW/vACL only) GET None Displays the methods /load/clear -/vnf/config/rules/load GET None Displays if file was loaded - PUT <script file - with cmds> Executes each command from script file -/vnf/config/rules/clear GET None Command success/failure clear the stat - -/vnf/config/nat(vCGNAPT only) GET None Displays the methods /load/clear -/vnf/config/nat/load GET None Displays if file was loaded - PUT <script file - with commands> Executes each command from script file - -/vnf/config/nat/clear GET None Command success/failure clear the stats -/vnf/log GET None This needs to be implemented for each VNF - just keeping this as placeholder. - -/vnf/dbg GET None Will display methods supported like /pipelines/cmd -/vnf/dbg/pipelines GET None Displays pipeline information(names) - of each pipelines -/vnf/dbg/pipelines/<pipe id> GET None Displays debug level for particular pipeline - -/vnf/dbg/cmd GET None Last executed command parameters - POST cmd: Command success/failure - dbg: - d1: - d2: +---------------------------------- +:: + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + | **URI** | **REST Method** | **Arguments** |**Description** | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf | GET | None |Displays top level methods available | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config | GET | None |Displays the current config set | + | | POST | pci_white_list: | | + | | | num_worker(o): | | + | | | vnf_type(o): | | + | | | pkt_type (o): | | + | | | num_lb(o): | | + | | | sw_lb(o): | | + | | | sock_in(o): | | + | | | hyperthread(o): | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/arp | GET | None |Displays ARP/ND info | + | | POST | action: <add/del/req> | | + | | | ipv4/ipv6: <address> | | + | | | portid: <> | | + | | | macaddr: <> for add | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/link | GET | None | | + | | POST | link_id:<> | | + | | | state: <1/0> | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/link/<link id> | GET | None | | + | | POST | ipv4/ipv6: <address> | | + | | | depth: <> | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/route | GET | None |Displays gateway route entries | + | | POST | portid: <> |Adds route entries for default gateway | + | | | nhipv4/nhipv6: <addr> | | + | | | depth: <> | | + | | | type:"net/host" | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/rules(vFW/vACL only) | GET | None |Displays the methods /load/clear | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/rules/load | GET | None |Displays if file was loaded | + | | PUT | <script file | | + | | | with cmds> |Executes each command from script file | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/rules/clear | GET | None | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/nat(vCGNAPT only) | GET | None |Displays the methods /load/clear | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/nat/load | GET | None |Displays if file was loaded | + | | PUT | <script file with cmds> | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/config/nat/clear | GET | None | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/log | GET | None |This needs to be implemented for each VNF | + | | | | just keeping this as placeholder. | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/dbg | GET | None |Will display methods supported like /pipelines/cmd | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/dbg/pipelines | GET | None |Displays pipeline information(names) | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/dbg/pipelines/<pipe id> | GET | None |Displays debug level for particular pipeline | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + |/vnf/dbg/cmd | GET | None |Last executed command parameters | + | | POST | cmd: | | + | | | dbg: | | + | | | d1: | | + | | | d2: | | + +---------------------------------+-----------------+--------------------------+----------------------------------------------------+ + + PUT/POST - Command success/failure API Usage =============== -1. Initialization -================ - -In order to integrate to your VNF these are the steps required - -In your VNF application init - - -#ifdef REST_API_SUPPORT - Initialize the rest api - struct mg_context *ctx = rest_api_init(&app); -#endif - - -#ifdef REST_API_SUPPORT - rest api's for cgnapt - rest_api_<vnf>_init(ctx, &app); -#endif - - -void rest_api_<vnf>_init(struct mg_context *ctx, struct app_params *app) -{ - myapp = app; - - VNF specific command registration - mg_set_request_handler(,,,); - -} - - -2. Run time Usage +1. Run time Usage ==================== An application(say vFW) with REST API support is run as follows @@ -194,114 +147,112 @@ with just PORT MASK as input. The following environment variables need to be set before launching the application(To be run from samplevnf directory). -export VNF_CORE=`pwd` -export RTE_SDK=`pwd`/dpdk-16.04 -export RTE_TARGET=x86_64-native-linuxapp-gcc +:: + ./build/vFW (Without the -f & -s option) -./build/vFW (Without the -f & -s option) +1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the /vnf/config REST method. -1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the -/vnf/config REST method. A typical curl command if used will look like below -shown. This with minimal parameter. For more options please refer to above REST -methods table. + :: + e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:08:00.0 0000:08:00.1"}' http://<IP>/vnf/config -e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:08:00.0 - 0000:08:00.1"}' http://<IP>/vnf/config + Note: the config is mostly implemented based on existing VNF's. if new parameters + are required in the config we need to add that as part of the vnf_template. -Note: the config is mostly implemented based on existing VNF's. if new parameters -are required in the config we need to add that as part of the vnf_template. + Once the config is provided the application gets launched. -Once the config is provided the application gets launched. + Note for CGNAPT we can add public_ip_port_range as follows, the following e.g gives + a multiport configuration with 4 ports, 2 load balancers, worker threads 10, multiple + public_ip_port_range being added, please note the "/" being used to seperate multiple + inputs for public_ip_port_range. -Note for CGNAPT we can add public_ip_port_range as follows, the following e.g gives -a multiport configuration with 4 ports, 2 load balancers, worker threads 10, multiple -public_ip_port_range being added, please note the "/" being used to seperate multiple -inputs for public_ip_port_range. - -e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:05:00.0 0000:05:00.2 0000:07:00.0 0000:07:00.2", - "num_lb":"2", "num_worker":"10","public_ip_port_range_0": "04040000:(1, 65535)/04040001:(1, 65535)", - "public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config + e.g curl -X POST -H "Content-Type:application/json" -d '{"pci_white_list": "0000:05:00.0 0000:05:00.2 0000:07:00.0 0000:07:00.2", + "num_lb":"2", "num_worker":"10","public_ip_port_range_0": "04040000:(1, 65535)/04040001:(1, 65535)", + "public_ip_port_range_1": "05050000:(1, 65535)/05050001:(1, 65535)" }' http://10.223.197.179/vnf/config 2. Check the Link IP's using the REST API (vCGNAPT/vACL/vFW) -e.g curl <IP>/vnf/config/link -This would indicate the number of links enabled. You should enable all the links -by using following curl command for links 0 & 1 + :: + e.g curl <IP>/vnf/config/link + + This would indicate the number of links enabled. You should enable all the links + by using following curl command for links 0 & 1 -e.g curl -X POST -H "Content-Type:application/json" -d '{"linkid": "0", "state": "1"}' -http://<IP>/vnf/config/link -curl -X POST -H "Content-Type:application/json" -d '{"linkid": "1", "state": "1"}' -http://<IP>/vnf/config/link + e.g curl -X POST -H "Content-Type:application/json" -d '{"linkid": "0", "state": "1"}' + http://<IP>/vnf/config/link + curl -X POST -H "Content-Type:application/json" -d '{"linkid": "1", "state": "1"}' + http://<IP>/vnf/config/link 3. Now that links are enabled we can configure IP's using link method as follows (vCGNAPT/vACL/vFW) -e.g curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}' -http://<IP>/vnf/config/link/0 -curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"IP to be configured","depth":"24"}' -http://<IP>/vnf/config/link/1 + :: + e.g curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"<IP to be configured>","depth":"24"}' + http://<IP>/vnf/config/link/0 + curl -X POST -H "Content-Type:application/json" -d '{"ipv4":"IP to be configured","depth":"24"}' + http://<IP>/vnf/config/link/1 -Once the IP's are set in place time to add NHIP for ARP Table. This is done using for all the ports -required. -/vnf/config/route + Once the IP's are set in place time to add NHIP for ARP Table. This is done using for all the ports required. + /vnf/config/route -curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address", - "depth":"8", "type":"net"}' http://<IP>/vnf/config/route + curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address", + "depth":"8", "type":"net"}' http://<IP>/vnf/config/route 4. Adding arp entries we can use this method (vCGNAPT/vACL/vFW) -/vnf/config/arp + :: + /vnf/config/arp -e.g - -curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"202.16.100.20", + e.g + curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"202.16.100.20", "portid":"0", "macaddr":"00:00:00:00:00:01"}' http://10.223.166.213/vnf/config/arp -curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"172.16.40.20", + curl -X POST -H "Content-Type:application/json" -d '{"action":"add", "ipv4":"172.16.40.20", "portid":"1", "macaddr":"00:00:00:00:00:02"}' http://10.223.166.213/vnf/config/arp 5. Adding route entries we can use this method (vCGNAPT/vACL/vFW) -vnf/config/route + :: + /vnf/config/route -e.g curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":"8", "nhipv4":"202.16.100.20", + e.g curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":"8", "nhipv4":"202.16.100.20", "portid":"0"}' http://10.223.166.240/vnf/config/route -curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":8", "nhipv4":"172.16.100.20", + curl -X POST -H "Content-Type:application/json" -d '{"type":"net", "depth":8", "nhipv4":"172.16.100.20", "portid":"1"}' http://10.223.166.240/vnf/config/route 5. In order to load the rules a script file needs to be posting a script.(vACL/vFW) -/vnf/config/rules/load + :: + /vnf/config/rules/load -Typical example for loading a script file is shown below -curl -X PUT -F 'image=@<path to file>' http://<IP>/vnf/config/rules/load + Typical example for loading a script file is shown below + curl -X PUT -F 'image=@<path to file>' http://<IP>/vnf/config/rules/load -typically arpadd/routeadd commands can be provided as part of this to -add static arp entries & adding route entries providing the NHIP's. + typically arpadd/routeadd commands can be provided as part of this to + add static arp entries & adding route entries providing the NHIP's. 6. The following REST api's for runtime configuring through a script (vCGNAPT Only) -/vnf/config/rules/clear -/vnf/config/nat -/vnf/config/nat/load + :: + /vnf/config/rules/clear + /vnf/config/nat + /vnf/config/nat/load 7. For debug purpose following REST API's could be used as described above.(vCGNAPT/vACL/vFW) + :: + /vnf/dbg + e.g curl http://10.223.166.240/vnf/config/dbg -/vnf/dbg - -e.g curl http://10.223.166.240/vnf/config/dbg + /vnf/dbg/pipelines + e.g curl http://10.223.166.240/vnf/config/dbg/pipelines -/vnf/dbg/pipelines -e.g curl http://10.223.166.240/vnf/config/dbg/pipelines + /vnf/dbg/pipelines/<pipe id> + e.g curl http://10.223.166.240/vnf/config/dbg/pipelines/<id> -/vnf/dbg/pipelines/<pipe id> -e.g curl http://10.223.166.240/vnf/config/dbg/pipelines/<id> - -/vnf/dbg/cmd + /vnf/dbg/cmd 8. For stats we can use the following method (vCGNAPT/vACL/vFW) - -/vnf/stats -e.g curl <IP>/vnf/stats + :: + /vnf/stats + e.g curl <IP>/vnf/stats 9. For quittiong the application (vCGNAPT/vACL/vFW) -/vnf/quit - -e.g curl <IP>/vnf/quit + :: + /vnf/quit + e.g curl <IP>/vnf/quit diff --git a/docs/testing/user/userguide/07-Config_files.rst b/docs/testing/user/userguide/07-Config_files.rst index 9061ee57..4f3811ec 100644 --- a/docs/testing/user/userguide/07-Config_files.rst +++ b/docs/testing/user/userguide/07-Config_files.rst @@ -20,9 +20,127 @@ Following are the example configuration files for sampleVNFs. vCGNAPT Config files -------------------- +The reference configuration files explained here are for Software and Hardware +loadbalancing with IPv4 traffic type and single port pair. +For other configurations liek IPv6 and Multi-port, refer to example config +files provided as part of the source code in config(VNFs/vCGNAPT/config) folder +of the VNFs. + +1. SWLB, IPv4, Single Port Pair, 1WT: + + :: + [EAL] + w = 05:00.0 + w = 05:00.1 + + [PIPELINE0] + type = MASTER + core = 0 + + [PIPELINE1] + type = ARPICMP + core = 1 + pktq_in = SWQ0 + pktq_out = SWQ7 + + pktq_in_prv = RXQ0.0 + prv_to_pub_map = (0, 1) + + [PIPELINE2] + type = TIMER + core = 2 + n_flows = 1048576 + + [PIPELINE3] + type = TXRX + core = 3 + pipeline_txrx_type = RXRX + dest_if_offset = 176 + pktq_in = RXQ0.0 RXQ1.0 + pktq_out = SWQ1 SWQ2 SWQ0 + [PIPELINE4] + type = LOADB + core = 4 + pktq_in = SWQ1 SWQ2 + pktq_out = SWQ3 SWQ4 + outport_offset = 136; 8 + n_vnf_threads = 1 + prv_que_handler = (0,) + [PIPELINE5] + type = CGNAPT + core = 5 + pktq_in = SWQ3 SWQ4 + pktq_out = SWQ5 SWQ6 + phyport_offset = 204 + n_flows = 1048576 + key_offset = 192;64 + key_size = 8 + hash_offset = 200;72 + timer_period = 100 + max_clients_per_ip = 65535 + max_port_per_client = 10 + public_ip_port_range = 98103214:(1, 65535) + vnf_set = (3,4,5) + pkt_type = ipv4 + cgnapt_meta_offset = 128 + prv_que_handler = (0,) + [PIPELINE6] + type = TXRX + core = 6 + pipeline_txrx_type = TXTX + dest_if_offset = 176 + pktq_in = SWQ5 SWQ6 + pktq_out = TXQ0.0 TXQ1.0 + +2. HWLB, IPv4, Single Port Pair, 1 WT: + +This configuration doesn't require LOADB and TXRX pipelines + +:: + [EAL] + w = 05:00.0 + w = 05:00.1 + + [PIPELINE0] + type = MASTER + core = 0 + + [PIPELINE1] + type = ARPICMP + core = 1 + pktq_in = SWQ0 + pktq_out = TXQ0.0 TXQ1.0 + + + pktq_in_prv = RXQ0.0 + prv_to_pub_map = (0, 1) + + [PIPELINE2] + type = TIMER + core = 2 + n_flows = 1048576 + + [PIPELINE3] + type = CGNAPT + core = 3 + pktq_in = RXQ0.0 RXQ1.0 + pktq_out = TXQ0.1 TXQ1.1 SWQ0 + phyport_offset = 204 + n_flows = 1048576 + key_offset = 192;64 + key_size = 8 + hash_offset = 200;72 + timer_period = 100 + max_clients_per_ip = 65535 + max_port_per_client = 10 + public_ip_port_range = 98103214:(1, 65535) + vnf_set = (3,4,5) + pkt_type = ipv4 + cgnapt_meta_offset = 128 + prv_que_handler = (0,) vFW Config files ---------------- @@ -355,6 +473,3 @@ of the VNFs. n_flows = 1000000 pkt_type = ipv4 traffic_type = 4 - - - 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 <substr> | Show list of commands that have <substr> as a substring. | | + | | If no substring is provided, all commands are shown. | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |verbose <level> | 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 <core_id> <task_id> | Show task specific information | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |update interval <value> | 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 <core list>|all <task_id> | Start cores specified in <core list> or all cores. | start all | + | | If <task_id> is not specified, all tasks for the specified cores | start 1 | + | | will be started. | start 1s0-4s0 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |stop <core list>|all <task_id> | Stop cores specified in <core list> or all cores. | | + | | If <task_id> is not specified, all tasks for the specified | stop 1 | + | | cores will be stopped. | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |dump <coreid> <taskid> <nbpkts> | Create a hex dump of <nb_packets> from <task_id> on <core_id> | dump 2 1 5 | + | | showing how packets have changed between RX and TX. | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |dump_rx <coreid> <taskid> <nbpkts> | Create a hex dump of <nb_packets> from <task_id> on <coreid> at RX | dump_rx 2 1 5 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |dump_tx <coreid> <taskid> <nbpkts> | Create a hex dump of <nb_packets> from <task_id> on <coreid> 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 <port id> <queue id> <rate> | Set transmit rate in Mb/s. This does not include preamble, SFD and IFG | rate 0 0 1000 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |count <core id> <task id> <count> | Generate <count> packets, then pause generating | count 1 0 5 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |pkt_size <coreid> <taskid> <pktsize> | Set the packet size to <pkt_size> | pkt_size 1 3 255 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |speed <core_id> <task_id> <speed percentage> | Change the speed to <speed percentage> of a | + | | 10 Gbps line at which packets are being generated | speed 1 0 50 | + | | on core <core_id> in task <task_id> | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |speed_byte <core_id> <task_id> <speed> | Change speed to <speed>. The speed is specified in units of bytes per sec | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |set value <core_id> <task_id> <offset> | Set <value_len> bytes to <value> at offset <offset> in packets | | + | <value> <value_len> | generated on <core_id> <task_id> | set value 4 1 14 10 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + | reset values all | Undo all `set value` commands on all cores/tasks | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |reset values <core id> <task id> | Undo all `set value` commands on specified core/task | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |arp add <core id> <task id> <port id> | | | + | <gre id> <svlan> <cvlan> <ip addr> | | | + | <mac addr> <user> | Add a single ARP entry into a CPE table on <core id>/<task id> | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |rule add <core id> <task id> 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 <core id>/<task id> | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |route add <core id> <task id> | | | + | <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 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |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 <core id> <task id> | Print min,max,avg latency as measured during last sampling interval | lat stats 1 0 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |lat packets <core id> <task id> | Print the latency for each of the last set of packets | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |core stats <core id> <task id> | Print rx/tx/drop for task <task id> running on core <core id> | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port_stats <port id> | Print rate for no_mbufs, ierrors, rx_bytes, tx_bytes, rx_pkts, | | + | | tx_pkts and totals for RX, TX, no_mbufs ierrors for port <port id> | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |ring info all | Get information about ring, such as ring size and | | + | | number of elements in the ring | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |ring info <core id> <task id> | Get information about ring on core <core id> | | + | | in task <task id>, such as ring size and number of elements in the ring | ring info 1 0 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port info <port id> [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 <port id> | Set the port up (all ports are up at startup) | port up 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port down <port id> | Set the port down | port down 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port xstats <port id> | Get extra statistics for the port | port xstats 1 | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |version | Show version | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + |port_stats <port id> | Print rate for no_mbufs, ierrors, rx_bytes, tx_bytes, rx_pkts, | | + | | tx_pkts and totals for RX, TX, no_mbufs ierrors for port <port id> | | + +----------------------------------------------+---------------------------------------------------------------------------+----------------------------+ + +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 diff --git a/docs/testing/user/userguide/images/prox_core.png b/docs/testing/user/userguide/images/prox_core.png Binary files differnew file mode 100644 index 00000000..5d85454d --- /dev/null +++ b/docs/testing/user/userguide/images/prox_core.png diff --git a/docs/testing/user/userguide/index.rst b/docs/testing/user/userguide/index.rst index 8d797627..e8acf532 100644 --- a/docs/testing/user/userguide/index.rst +++ b/docs/testing/user/userguide/index.rst @@ -20,5 +20,6 @@ SampleVNF User Guide 06-How_to_use_REST_api 07-Config_files 08-CLI_Commands_Reference + 09-Prox glossary references |
