diff options
| -rw-r--r-- | docs/release/release-notes/release-notes.rst | 17 | ||||
| -rw-r--r-- | docs/release/results/results.rst | 30 | ||||
| -rw-r--r-- | docs/testing/developer/design/01-Overview.rst | 4 | ||||
| -rw-r--r-- | docs/testing/developer/design/02-Get_started_Guide.rst | 14 | ||||
| -rw-r--r-- | docs/testing/developer/requirements/03-Requirements.rst | 19 | ||||
| -rwxr-xr-x | docs/testing/user/userguide/01-introduction.rst | 11 | ||||
| -rw-r--r-- | docs/testing/user/userguide/02-methodology.rst | 2 | ||||
| -rwxr-xr-x | docs/testing/user/userguide/03-architecture.rst | 10 | ||||
| -rw-r--r-- | docs/testing/user/userguide/04-installation.rst | 73 | ||||
| -rw-r--r-- | docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst | 239 | ||||
| -rw-r--r-- | docs/testing/user/userguide/06-How_to_use_REST_api.rst | 280 | ||||
| -rw-r--r-- | docs/testing/user/userguide/07-Config_files.rst | 360 | ||||
| -rw-r--r-- | docs/testing/user/userguide/index.rst | 2 |
13 files changed, 876 insertions, 185 deletions
diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index 5d9abc25..192e82e5 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -12,12 +12,13 @@ are licensed under a Creative Commons Attribution 4.0 International License. You should have received a copy of the license along with this. If not, see <http://creativecommons.org/licenses/by/4.0/>. : + The *SampleVNFs*, the *SampleVNF test cases* are opensource software, - licensed under the terms of the Apache License, Version 2.0. +licensed under the terms of the Apache License, Version 2.0. -=========================================== +========================================== OPNFV Euphrates Release Note for SampleVNF -=========================================== +========================================== .. toctree:: :maxdepth: 2 @@ -78,12 +79,12 @@ OPNFV platform, including: * SampleVNF source code -For Euphrates release, the *SampleVNF * is used for the following +For Euphrates release, the *SampleVNF* is used for the following testing: * OPNFV platform testing - generic test cases to measure the categories: - * NFVi Characterization: + * NFVI Characterization: * Network @@ -131,9 +132,9 @@ Deliverables Documents --------- - - User Guide: To be added + - User Guide - - Developer Guide: To be added + - Developer Guide Software Deliverables @@ -183,7 +184,7 @@ Feature additions Known Issues/Faults ------------- +------------------- diff --git a/docs/release/results/results.rst b/docs/release/results/results.rst index f64f3422..11fd1aff 100644 --- a/docs/release/results/results.rst +++ b/docs/release/results/results.rst @@ -15,18 +15,20 @@ Feature Test Results The following features were verified by SampleVNF test cases: - * vFirewall - * Basic Packet filter dropping malformed, invalid packets based on L3/L4 packet headers - * Policy based filtering - * Dynamic Packet filtering through Connection Tracker for TCP and UDP - * SYN-flood protection via synproxy for TCP - * UDP, TCP and ICMP protocol pass-through - * CLI based enable/disable connection tracking, synproxy, basic packet filtering - * Multithread support - * Multiple physical port support - * Providing statistics on traffic traversing the VNF + - vFW - Virtual Firewall + + * Basic Packet filter dropping malformed, invalid packets based on L3/L4 packet headers + * Policy based filtering + * Dynamic Packet filtering through Connection Tracker for TCP and UDP + * SYN-flood protection via synproxy for TCP + * UDP, TCP and ICMP protocol pass-through + * CLI based enable/disable connection tracking, synproxy, basic packet filtering + * Multithread support + * Multiple physical port support + * Providing statistics on traffic traversing the VNF + + - vCG-NAPT - Carrier Grade Network Address and port Translation - * vCG-NAPT- Carrier Grade Network Address and port Translation * Static and dynamic Network address translation. * Static and dynamic Network address and port translation * ARP (request, response, gratuitous) @@ -38,7 +40,8 @@ The following features were verified by SampleVNF test cases: * Live Session tracking to NAT flow * NAT64 – connectivity between IPv6 access network to IPv4 data network. - * vACL - Access Control List + - vACL - Access Control List + * CLI based Run-time rule configuration (Add, Delete, List, Display, Clear, Modify) * IPv4 and IPv6 5 tuple packet Selector support * Counting packets and bytes per rule @@ -47,7 +50,8 @@ The following features were verified by SampleVNF test cases: * Forwarding packets to specific ports on base of rules * Rules definition on base TCP/UDP connection tracking - * Prox - Packet pROcessing eXecution engine. + - Prox - Packet pROcessing eXecution engine. + * Classify * Drop * Basic Forwarding (no touch) diff --git a/docs/testing/developer/design/01-Overview.rst b/docs/testing/developer/design/01-Overview.rst index e4c7a984..a1ae66af 100644 --- a/docs/testing/developer/design/01-Overview.rst +++ b/docs/testing/developer/design/01-Overview.rst @@ -26,7 +26,7 @@ real life use-case based testing and NFVi characterization for the same. The sample VNFs are Open Source approximations* of Telco grade VNF’s using optimized VNF + NFVi Infrastructure libraries, with Performance Characterization of Sample† Traffic Flows. * * Not a commercial product. Encourage the community to contribute and close the feature gaps. - * † No Vendor/Proprietary Workloads + * † No Vendor/Proprietary Workloads It helps to facilitate deterministic & repeatable bench-marking on Industry standard high volume Servers. It augments well with a Test Infrastructure @@ -46,6 +46,6 @@ Integrate into CI tool chain and existing test frameworks for VNF feature and de Testability: ----------- Network Service Testing framework added into the Yardstick will be used as a test -tool for Functional/Performance verification of all the sample VNFs. +tool for Functional/Performance verification of all the sample VNFs. Planning to extend the same to FuncTest and Models project to include the testcases related to sample VNFs. diff --git a/docs/testing/developer/design/02-Get_started_Guide.rst b/docs/testing/developer/design/02-Get_started_Guide.rst index 4bcff899..995a2270 100644 --- a/docs/testing/developer/design/02-Get_started_Guide.rst +++ b/docs/testing/developer/design/02-Get_started_Guide.rst @@ -59,11 +59,11 @@ In this way, individual commits can be traced to JIRA issues and we also know wh commits were used to resolve a JIRA issue. If you want to contribute to samplevnf, you can pick a issue from SampleVNF's JIRA dashboard or you can create you own issue and submit it to JIRA. - + Submitting code to Gerrit Installing and configuring Git and Git-Review is necessary in order to submit code to Gerrit. The Getting to the code page will provide you with some help for that. - + Comitting the code with Git Open a terminal window and set the project's directory to the working directory using the cd command. In this case "/home/opnfv/samplevnf" is the path to the samplevnf project folder on my computer. @@ -97,11 +97,11 @@ it is time to actually commit your work to your local Git repository. :: git commit --signoff -m "Title of change - + Test of change that describes in high level what was done. There is a lot of documentation in code so you do not need to repeat it here. - + JIRA: SAMPLEVNF-XXX" The message that is required for the commit should follow a specific set of rules. @@ -122,7 +122,7 @@ This will automatically push your local commit into Gerrit. Code review You can add Samplevnf committers and contributors to review your codes. - + Modifying the code under review in Gerrit At the same time the code is being reviewed in Gerrit, you may need to edit it to make some changes and then send it back for review. The following steps go through the procedure. @@ -132,7 +132,7 @@ The 'status' command is very helpful at this point as it provides an overview of :: git status The output of the command provides us with the files that have been modified after the latest commit. - + You can now stage the files that have been modified as part of the Gerrit code review edition/modification/improvement using git add command. It is now time to commit the newly modified files, but the objective here is not to @@ -144,7 +144,7 @@ You can achieve that with the '--amend' option on the 'commit' command: If the commit was successful, the 'status' command should not return the updated files as about to be commited. - + The final step consists in pushing the newly modified commit to Gerrit. :: diff --git a/docs/testing/developer/requirements/03-Requirements.rst b/docs/testing/developer/requirements/03-Requirements.rst index ce43e06a..dab07a6e 100644 --- a/docs/testing/developer/requirements/03-Requirements.rst +++ b/docs/testing/developer/requirements/03-Requirements.rst @@ -25,7 +25,7 @@ Connected to the DUT is an IXIA* or Software Traffic generator like pktgen or TR simulation platform to generate packet traffic to the DUT ports and determine the throughput/latency at the tester side. -Below are the supported/tested (:term `VNF`) deployment type. +Below are the supported/tested (:term:`VNF`) deployment type. .. image:: images/deploy_type.png :width: 800px :alt: SampleVNF supported topology @@ -67,22 +67,27 @@ Hardware & Software Ingredients Network Topology for testing VNFs --------------------------------- + The ethernet cables should be connected between traffic generator and the VNF server (BM, SRIOV or OVS) setup based on the test profile. The connectivity could be -1. Single port pair : One pair ports used for traffic - :: + +- 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 -2. Multi port pair : More than one pair of traffic - :: +- 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 TG:port 1 <------> VNF:Port 1 - TG:port 2 <------> VNF:Port 2 + TG:port 2 <------> VNF:Port 2 TG:port 3 <------> VNF:Port 3 -For openstack/Standalone virtualization, installation please refer the openstack guide and ovs-dpdk/sriov github. +For openstack/Standalone virtualization, installation please refer the openstack guide and ovs-dpdk/sriov github. (TBA - Add link to guide) diff --git a/docs/testing/user/userguide/01-introduction.rst b/docs/testing/user/userguide/01-introduction.rst index 1a60fb58..ab79e931 100755 --- a/docs/testing/user/userguide/01-introduction.rst +++ b/docs/testing/user/userguide/01-introduction.rst @@ -20,16 +20,15 @@ The project's goal is to provides a placeholder for various sample VNF reference architecture and optimization methods related to VNF/Network service for high performance VNFs. This project provides benefits to other OPNFV projects like Functest, Models, yardstick etc to perform real life -use-case based testing and VNF/NFVi characterization for the same. +use-case based testing and VNF/ Network Function Virtualization Infrastructure +(:term:`NFVI`) characterization for the same. The Project's scope to create a repository of sample VNFs to help VNF -benchmarking and NFVi characterization with real world traffic and host a +benchmarking and NFVI characterization with real world traffic and host a common development environment for developing the VNF using optimized libraries. -Also, Develop a test framework in yardstick to enable -Virtual Network Function (:term:`VNF`) / Network Function Virtualization Infrastructure -(:term:`NFVI`) verification. +Also, develop a test framework in yardstick to enable VNF/NFVI verification. -*SampleVNF* is used in OPNFV for characterization of NFVi/VNF on OPNFV infrastructure +*SampleVNF* is used in OPNFV for characterization of NFVI/VNF on OPNFV infrastructure and some of the OPNFV features. .. seealso:: Pharos_ for information on OPNFV community labs and this diff --git a/docs/testing/user/userguide/02-methodology.rst b/docs/testing/user/userguide/02-methodology.rst index 07e9e7ce..5550fec9 100644 --- a/docs/testing/user/userguide/02-methodology.rst +++ b/docs/testing/user/userguide/02-methodology.rst @@ -22,7 +22,7 @@ related to VNF/Network service for high performance VNFs. The sample VNFs are Open Source approximations* of Telco grade :term:`VNF` using optimized VNF + NFVi Infrastructure libraries, with Performance Characterization of Sample† Traffic Flows. • * Not a commercial product. Encourage the community to contribute and close the feature gaps. -• † No Vendor/Proprietary Workloads +• † No Vendor/Proprietary Workloads ETSI-NFV ======== diff --git a/docs/testing/user/userguide/03-architecture.rst b/docs/testing/user/userguide/03-architecture.rst index d8b81c60..3654c43a 100755 --- a/docs/testing/user/userguide/03-architecture.rst +++ b/docs/testing/user/userguide/03-architecture.rst @@ -30,8 +30,8 @@ of Sample† Traffic Flows. * Not a commercial product. Encourage the community to contribute and close the feature gaps. † No Vendor/Proprietary Workloads -t helpsIt helps to facilitate deterministic & repeatable bench-marking on Industry -standard high volume Servers. It augments well with a Test Infrastructure to +It helps to facilitate deterministic & repeatable bench-marking on Industry +standard high volume Servers. It augments well with a Test infrastructure to help facilitate consistent/repeatable methodologies for characterizing & validating the sample VNFs through OPEN SOURCE VNF approximations and test tools. The VNFs belongs to this project are never meant for field deployment. @@ -40,7 +40,7 @@ All the VNF source code part of this project requires Apache License Version 2.0 Supported deployment: ---------------------- * Bare-Metal - All VNFs can run on a Bare-Metal DUT -* Standalone Virtualization: All VNFs can run on SV like VPP as switch, ovs, +* Standalone Virtualization(SV): All VNFs can run on SV like VPP as switch, ovs, ovs-dpdk, srioc * Openstack: Latest Openstack supported @@ -75,7 +75,7 @@ VNF supported Packet pROcessing eXecution Engine (PROX) which is a DPDK application. PROX can do operations on packets in a highly configurable manner. The PROX application is also displaying performance statistics that can - be used for performance investigations. + be used for performance investigations. 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. @@ -106,7 +106,7 @@ SampleVNF Directory structure user guides and SampleVNF descriptions. *tools/* - Currently contains tools to build image for VMs which are deployed - by Heat. Currently contains helper scripts like install, setup env + by Heat. Currently contains helper scripts like install, setup env *VNFs/* - all VNF source code directory. diff --git a/docs/testing/user/userguide/04-installation.rst b/docs/testing/user/userguide/04-installation.rst index d7c26c9d..9a31ecdc 100644 --- a/docs/testing/user/userguide/04-installation.rst +++ b/docs/testing/user/userguide/04-installation.rst @@ -10,7 +10,7 @@ Abstract -------- This project provides a placeholder for various sample VNF -(Virtual Network Function (:term `VNF`)) development which includes example +(Virtual Network Function (:term:`VNF`)) development which includes example reference architecture and optimization methods related to VNF/Network service for high performance VNFs. The sample VNFs are Open Source approximations* of Telco grade VNF’s using @@ -20,21 +20,21 @@ of Sample† Traffic Flows. :: * Not a commercial product. Encourage the community to contribute and close the feature gaps. - † No Vendor/Proprietary Workloads + † No Vendor/Proprietary Workloads SampleVNF supports installation directly in Ubuntu. The installation procedure are detailed in the sections below. The steps needed to run SampleVNF are: 1) Install and Build SampleVNF. - 2) deploy the VNF on the target and modify the config based on the Network under test + 2) Deploy the VNF on the target and modify the config based on the Network under test 3) Run the traffic generator to generate the traffic. Prerequisites ------------- -Supported Test setup: --------------------- +Supported Test setup +^^^^^^^^^^^^^^^^^^^^^ The device under test (DUT) consists of a system following; * A single or dual processor and PCH chip, except for System on Chip (SoC) cases * DRAM memory size and frequency (normally single DIMM per channel) @@ -45,18 +45,19 @@ Connected to the DUT is an IXIA* or Software Traffic generator like pktgen or TR simulation platform to generate packet traffic to the DUT ports and determine the throughput/latency at the tester side. -Below are the supported/tested (:term `VNF`) deployment type. +Below are the supported/tested (:term:`VNF`) deployment type. .. image:: images/deploy_type.png :width: 800px :alt: SampleVNF supported topology Hardware & Software Ingredients -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SUT requirements: -^^^^^^^^^^^^^^^^ + :: + +-----------+------------------+ | Item | Description | +-----------+------------------+ @@ -72,8 +73,9 @@ SUT requirements: +-----------+------------------+ Boot and BIOS settings: -^^^^^^^^^^^^^^^^^^^^^^ + :: + +------------------+---------------------------------------------------+ | Boot settings | default_hugepagesz=1G hugepagesz=1G hugepages=16 | | | hugepagesz=2M hugepages=2048 isolcpus=1-11,22-33 | @@ -97,49 +99,58 @@ The ethernet cables should be connected between traffic generator and the VNF se SRIOV or OVS) setup based on the test profile. The connectivity could be -1) Single port pair : One pair ports used for traffic - :: + +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 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 TG:port 1 <------> VNF:Port 1 - TG:port 2 <------> VNF:Port 2 + TG:port 2 <------> VNF:Port 2 TG:port 3 <------> VNF:Port 3 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) - * Bare-Metal - Refer: http://fast.dpdk.org/doc/pdf-guides/ to setup the DUT for VNF to run - * Standalone Virtualization - PHY-VM-PHY +* Bare-Metal + Refer: http://fast.dpdk.org/doc/pdf-guides/ to setup the DUT for VNF to run + +* Standalone Virtualization - PHY-VM-PHY * SRIOV Refer below link to setup sriov https://software.intel.com/en-us/articles/using-sr-iov-to-share-an-ethernet-port-among-multiple-vms - * OVS_DPDK + * OVS_DPDK Refer below link to setup ovs-dpdk http://docs.openvswitch.org/en/latest/intro/install/general/ http://docs.openvswitch.org/en/latest/intro/install/dpdk/ * Openstack Use any OPNFV installer to deploy the openstack. - + Build VNFs on the DUT: ---------------------- + 1) Clone sampleVNF project repository - git clone https://git.opnfv.org/samplevnf - Auto Build - Using script to build VNFs - ^^^^^^^^^^ - * Interactive options: +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. @@ -169,33 +180,37 @@ Build VNFs on the DUT: [9] Exit Script * non-Interactive options: + :: + ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> - Manual Build - ^^^^^^^^^^^^ +Manual Build +^^^^^^^^^^^^ + :: - 1.Download DPDK supported version from dpdk.org + + 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 + 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. + 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 + 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 + 5. Build vACL VNFs cd <samplevnf>/VNFs/vACL make clean make @@ -205,7 +220,9 @@ Build VNFs on the DUT: 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 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 b5880645..29c76e69 100644 --- a/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst +++ b/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst @@ -9,8 +9,8 @@ SampleVNF - How to run Prerequisites ------------- -Supported Test setup: --------------------- +Supported Test setup +^^^^^^^^^^^^^^^^^^^^ The device under test (DUT) consists of a system following; * A single or dual processor and PCH chip, except for System on Chip (SoC) cases * DRAM memory size and frequency (normally single DIMM per channel) @@ -21,18 +21,18 @@ Connected to the DUT is an IXIA* or Software Traffic generator like pktgen or TR simulation platform to generate packet traffic to the DUT ports and determine the throughput/latency at the tester side. -Below are the supported/tested (:term `VNF`) deployment type. +Below are the supported/tested (:term:`VNF`) deployment type. .. image:: images/deploy_type.png :width: 800px :alt: SampleVNF supported topology Hardware & Software Ingredients -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ SUT requirements: -^^^^^^^^^^^^^^^^ -:: + + +-----------+------------------+ | Item | Description | +-----------+------------------+ @@ -48,8 +48,8 @@ SUT requirements: +-----------+------------------+ Boot and BIOS settings: -^^^^^^^^^^^^^^^^^^^^^^ -:: + + +------------------+---------------------------------------------------+ | Boot settings | default_hugepagesz=1G hugepagesz=1G hugepages=16 | | | hugepagesz=2M hugepages=2048 isolcpus=1-11,22-33 | @@ -73,7 +73,8 @@ The ethernet cables should be connected between traffic generator and the VNF se SRIOV or OVS) setup based on the test profile. The connectivity could be -1) Single port pair : One pair ports used for traffic + +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 @@ -84,7 +85,7 @@ The connectivity could be e.g. Two port pair link 0, link1, link2 and link3 of VNF are used TG:port 0 <------> VNF:Port 0 TG:port 1 <------> VNF:Port 1 - TG:port 2 <------> VNF:Port 2 + TG:port 2 <------> VNF:Port 2 TG:port 3 <------> VNF:Port 3 For correalted traffic, use below configuration @@ -92,7 +93,7 @@ The connectivity could be VNF:Port 1 <------> TG_2:port 0 (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 + Refer: http://fast.dpdk.org/doc/pdf-guides/ to setup the DUT for VNF to run * Standalone Virtualization - PHY-VM-PHY * SRIOV @@ -111,12 +112,12 @@ 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 Step 1: Setting up Traffic generator (TRex) - :: + TRex Software preparations ^^^^^^^^^^^^^^^^^^^^^^^^^^ * Install the OS (Bare metal Linux, not VM!) @@ -131,13 +132,19 @@ Step 1: Setting up Traffic generator (TRex) Build SampleVNFs ----------------- + Step 2: Procedure to build SampleVNFs - :: + a) Clone sampleVNF project repository - git clone https://git.opnfv.org/samplevnf b) Build VNFs - Auto Build - ^^^^^^^^^^ - * Interactive options: + +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. @@ -156,18 +163,27 @@ Step 2: Procedure to build SampleVNFs [5] Download DPDK zip [6] Build and Install DPDK [7] Setup hugepages + [8] Download civetweb ---------------------------------------------------------- Step 3: Build VNFs ---------------------------------------------------------- - [8] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay, DPPD-PROX) + [9] Build all VNFs (vACL, vCGNAPT, vFW, UDP_Replay, DPPD-PROX) + + [10] Exit Script + + +* Non-Interactive options: + +:: - [9] Exit Script - * non-Interactive options: ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> - Manual Build - ^^^^^^^^^^^^ +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) @@ -175,22 +191,30 @@ Step 2: Procedure to build SampleVNFs make config T=x86_64-native-linuxapp-gcc O=x86_64-native-linuxapp-gcc cd x86_64-native-linuxapp-gcc make - 2) Setup huge pages + + 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 - 3) Add this to Go to /etc/default/grub configuration file. + 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. - 4) Setup Environment Variable + 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 - 5) Build VNFs + 6) Build VNFs cd <samplevnf> make or to build individual VNFs @@ -200,18 +224,27 @@ Step 2: Procedure to build SampleVNFs The vFW executable will be created at the following location <samplevnf>/VNFs/vFW/build/vFW + Virtual Firewall - How to run ----------------------------- Step 3: Bind the datapath ports to DPDK + +a) Bind ports to DPDK + :: - 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 - b) Prepare script to enalble VNF to route the packets + .. _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. @@ -245,12 +278,20 @@ Step 3: Bind the datapath ports to DPDK 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. + + +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 + step 4: Run Test using traffic geneator + :: + On traffic generator system: cd <trex eg v2.28/stl> Update the bench.py to generate the traffic. @@ -268,18 +309,27 @@ step 4: Run Test using traffic geneator 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 + Virtual Access Control list - How to run ---------------------------------------- Step 3: Bind the datapath ports to DPDK + +a) Bind ports to DPDK + :: - 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 - b) Prepare script to enalble VNF to route the packets + + +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. @@ -313,80 +363,20 @@ Step 3: Bind the datapath ports to DPDK 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. -step 4: Run Test using traffic geneator - :: - On traffic generator system: - 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': '<traffic generator port 1 IP eg 172.16.40.20>'} - 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 +c) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk. -Virtual Access Control list - How to run ----------------------------------------- - -Step 3: Bind the datapath ports to DPDK :: - 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 - 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 <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 + cd <samplevnf>/VNFs/vFW/ + ./build/vFW -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg -s ./config/IPv4_swlb_acl.tc. - ; 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/vACL/ - ./build/vACL -p 0x3 -f ./config/IPv4_swlb_acl_1LB_1t.cfg -s ./config/IPv4_swlb_acl.tc. step 4: Run Test using traffic geneator + :: + On traffic generator system: cd <trex eg v2.28/stl> Update the bench.py to generate the traffic. @@ -404,18 +394,27 @@ step 4: Run Test using traffic geneator 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 + vCGNAPT - How to run ----------------------------------------- +-------------------- Step 3: Bind the datapath ports to DPDK + + a) Bind ports to DPDK + :: - 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 - b) Prepare script to enalble VNF to route the packets + .. _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. @@ -436,17 +435,24 @@ Step 3: Bind the datapath ports to DPDK ; 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 + 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. + + 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 step 4: Run Test using traffic geneator - :: + On traffic generator system: + + :: + cd <trex eg v2.28/stl> Update the bench.py to generate the traffic. @@ -463,24 +469,35 @@ step 4: Run Test using traffic geneator 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 ---------------------------------------- Step 3: Bind the datapath ports to DPDK + + a) Bind ports to DPDK + :: - 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 - b) Run below cmd to launch the VNF. Please make sure both hugepages and ports to be used are bind to dpdk. + .. _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)' + step 4: Run Test using traffic geneator - :: + + :: + On traffic generator system: cd <trex eg v2.28/stl> Update the bench.py to generate the traffic. @@ -503,6 +520,7 @@ PROX - How to run Description ^^^^^^^^^^^ + This is PROX, the Packet pROcessing eXecution engine, part of Intel(R) Data Plane Performance Demonstrators, and formerly known as DPPD-BNG. PROX is a DPDK-based application implementing Telco use-cases such as @@ -511,6 +529,7 @@ finer grained network functions like QoS, Routing, load-balancing... Compiling and running this application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + This application supports DPDK 16.04, 16.11, 17.02 and 17.05. The following commands assume that the following variables have been set: @@ -519,6 +538,7 @@ export RTE_TARGET=x86_64-native-linuxapp-gcc Example: DPDK 17.05 installation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + * git clone http://dpdk.org/git/dpdk * cd dpdk * git checkout v17.05 @@ -526,12 +546,14 @@ Example: DPDK 17.05 installation PROX compilation ^^^^^^^^^^^^^^^^ + The Makefile with this application expects RTE_SDK to point to the root directory of DPDK (e.g. export RTE_SDK=/root/dpdk). If RTE_TARGET has not been set, x86_64-native-linuxapp-gcc will be assumed. Running PROX ^^^^^^^^^^^^ + After DPDK has been set up, run make from the directory where you have extracted this application. A build directory will be created containing the PROX executable. The usage of the application is shown @@ -540,6 +562,7 @@ been bound to the DPDK provided igb_uio driver. Refer to the "Getting Started Guide - DPDK" document for more details. :: + 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 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 new file mode 100644 index 00000000..c2c8836e --- /dev/null +++ b/docs/testing/user/userguide/06-How_to_use_REST_api.rst @@ -0,0 +1,280 @@ +.. This work is licensed under a creative commons attribution 4.0 international +.. license. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) opnfv, national center of scientific research "demokritos" and others. + +======================================================== +REST API - Readme +======================================================== + +Introduction +=============== +As the internet industry progresses creating REST API becomes more concrete +with emerging best Practices. RESTful web services don’t follow a prescribed +standard except fpr the protocol that is used which is HTTP, its important +to build RESTful API in accordance with industry best practices to ease +development & increase client adoption. + +In REST Architecture everything is a resource. RESTful web services are light +weight, highly scalable and maintainable and are very commonly used to +create APIs for web-based applications. + +Here are important points to be considered: + + * GET operations are read only and are safe. + * PUT and DELETE operations are idempotent means their result will + always same no matter how many times these operations are invoked. + * PUT and POST operation are nearly same with the difference lying + only in the result where PUT operation is idempotent and POST + operation can cause different result. + + +REST API in SampleVNF +===================== + +In SampleVNF project VNF’s are run under different contexts like BareMetal, +SRIOV, OVS & Openstack etc. It becomes difficult to interact with the +VNF’s using the command line interface provided by the VNF’s currently. + +Hence there is a need to provide a web interface to the VNF’s running in +different environments through the REST api’s. REST can be used to modify +or view resources on the server without performing any server-side +operations. + +REST api on VNF’s will help adapting with the new automation techniques +being adapted in yardstick. + +Web server integration with VNF’s +================================== + +In order to implement REST api’s in VNF one of the first task is to +identify a simple web server that needs to be integrated with VNF’s. +For this purpose “civetweb” is identified as the web server That will +be integrated with the VNF application. + +CivetWeb is an easy to use, powerful, C/C++ embeddable web server with +optional CGI, SSL and Lua support. CivetWeb can be used by developers +as a library, to add web server functionality to an existing application. + +Civetweb is a project forked out of Mongoose. CivetWeb uses an [MITlicense]. +It can also be used by end users as a stand-alone web server. It is available +as single executable, no installation is required. + +In our project we will be integrating civetweb into each of our VNF’s. +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 Command success/failure + 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 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: + +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 +==================== + +An application(say vFW) with REST API support is run as follows +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 -p 0x3 (Without the -f & -s option) + +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 + +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. + +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 + +2. Check the Link IP's using the REST API +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 + +3. Now that links are enabled we can configure IP's using link method as follows + +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 + +curl -X POST -H "Content-Type:application/json" -d '{"portid":"0", "nhipv4":"IPV4 address", + "depth":"8", "type":"net"}' http://<IP>/vnf/config/route + + +4. For Firewall/ACL in order to load the rules a script file needs to be posted +using a script. +/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 + +vCGNAPT can use the following REST api's for runtime configuring through a script +/vnf/config/rules/clear +/vnf/config/nat(vCGNAPT only) +/vnf/config/nat/load + +For debug purpose following REST API's could be used as described above. + +/vnf/dbg +/vnf/dbg/pipelines +/vnf/dbg/pipelines/<pipe id> +/vnf/dbg/cmd + +5. For stats we can use the following method + +/vnf/stats +e.g curl <IP>/vnf/stats + +6. For quittiong the application +/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 new file mode 100644 index 00000000..6ad6c6fb --- /dev/null +++ b/docs/testing/user/userguide/07-Config_files.rst @@ -0,0 +1,360 @@ +.. 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. + +SampleVNF - Config files +======================== + +The configuration files are created based on the DUT test scenarios. +The example reference files are provided as part of the VNFs in the +config folder. + +Following parameters will define the config files. + +1. Loadbalancing: Hardware or Software +2. Traffic type: IPv4 or IPv6 +3. Number of Ports: pairs: Single port or Multi-Port + +Following are the example configuration files for sampleVNFs. + +vCGNAPT Config files +-------------------- + + + + +vFW 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/vFW/config) folder +of the VNFs. + +1. SWLB, IPv4, Single Port Pair, 4WT: + + :: + + [PIPELINE0] + type = MASTER + core = 0 + + [PIPELINE1] + type = ARPICMP + core = 0 + + pktq_in = SWQ2 + pktq_out = TXQ0.0 TXQ1.0 + + ; IPv4 ARP route table entries (dst_ip, mask, if_port, nh) hex values with no 0x + ; arp_route_tbl = (ac102814,ff000000,1,ac102814) (ca106414,ff000000,0,ca106414) + + ; IPv6 ARP route table entries (dst_ip, mask, if_port, nh) hex values with no 0x + ;nd_route_tbl = (fec0::6a05:caff:fe30:21b0,64,0,fec0::6a05:caff:fe30:21b0) + ;nd_route_tbl = (2012::6a05:caff:fe30:2081,64,1,2012::6a05:caff:fe30:2081) + + ; egress (private interface) info + pktq_in_prv = RXQ0.0 + + ;for pub port <-> prv port mapping (prv, pub) + prv_to_pub_map = (0,1) + prv_que_handler = (0) + + [PIPELINE2] + type = TXRX + core = 1 + pktq_in = RXQ0.0 RXQ1.0 + pktq_out = SWQ0 SWQ1 SWQ2 + pipeline_txrx_type = RXRX + + [PIPELINE3] + type = LOADB + core = 2 + pktq_in = SWQ0 SWQ1 + pktq_out = SWQ3 SWQ4 SWQ5 SWQ6 SWQ7 SWQ8 SWQ9 SWQ10 + outport_offset = 136 + n_vnf_threads = 4 ; Number of worker threads + prv_que_handler = (0) + n_lb_tuples = 5 ; tuple(src_ip,dst_ip, src_port, dst_port, protocol) + ;loadb_debug = 0 + + [PIPELINE4] + type = VFW + core = 3 + pktq_in = SWQ3 SWQ4 + pktq_out = SWQ11 SWQ12;TXQ0.0 TXQ1.0 + + n_rules = 4096 ; Max number of ACL rules + ;n_flows gets round up to power of 2 + n_flows = 1048576 ; Max number of connections/flows per vFW WT + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 ; TCP Connection WAIT timeout + tcp_be_liberal = 0 + ;udp_unreplied and udp_replied controls udp "connection" timeouts, normally 30/180 + udp_unreplied = 180 ; UDP timeouts for unreplied traffic + udp_replied = 180 ; UDP timeout for replied traffic + + [PIPELINE5] + type = VFW + core = 4 + pktq_in = SWQ5 SWQ6 + pktq_out = SWQ13 SWQ14;TXQ0.0 TXQ1.0 + + n_rules = 4096 + ;n_flows gets round up to power of 2 + n_flows = 1048576 + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 + tcp_be_liberal = 0 + ;udp_unreplied and udp_replied controls udp "connection" timeouts, normally 30/180 + udp_unreplied = 180 + udp_replied = 180 + + [PIPELINE6] + type = VFW + core = 5 + pktq_in = SWQ7 SWQ8 + pktq_out = SWQ15 SWQ16 + + n_rules = 4096 + ;n_flows gets round up to power of 2 + n_flows = 1048576 + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 + tcp_be_liberal = 0 + ;udp_unreplied and udp_replied controls udp "connection" timeouts, normally 30/180 + udp_unreplied = 180 + udp_replied = 180 + + [PIPELINE7] + type = VFW + core = 6 + pktq_in = SWQ9 SWQ10 + pktq_out = SWQ17 SWQ18 + + n_rules = 4096 + ;n_flows gets round up to power of 2 + n_flows = 1048576 + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 + tcp_be_liberal = 0 + udp_unreplied = 180 + udp_replied = 180 + + [PIPELINE8] + type = TXRX + core = 1h + pktq_in = SWQ11 SWQ12 SWQ13 SWQ14 SWQ15 SWQ16 SWQ17 SWQ18 + pktq_out = TXQ0.1 TXQ1.1 TXQ0.2 TXQ1.2 TXQ0.3 TXQ1.3 TXQ0.4 TXQ1.4 + pipeline_txrx_type = TXTX + + +2. HWLB, IPv4, Single Port Pair, 4 WT: + +This configuration doesn't require LOADB and TXRX pipelines + + :: + + [PIPELINE0] + type = MASTER + core = 0 + + [PIPELINE1] + type = ARPICMP + core = 0 + pktq_in = SWQ0 SWQ1 SWQ2 SWQ3 + pktq_out = TXQ0.0 TXQ1.0 + + ; egress (private interface) info + pktq_in_prv = RXQ0.0 + + ;for pub port <-> prv port mapping (prv, pub) + prv_to_pub_map = (0,1) + prv_que_handler = (0) + + [PIPELINE2] + type = VFW + core = 1 + pktq_in = RXQ0.0 RXQ1.0 + pktq_out = TXQ0.1 TXQ1.1 SWQ0 + + n_rules = 4096 + ;n_flows gets round up to power of 2 + n_flows = 1048576 + + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 + tcp_be_liberal = 0 + ;udp_unreplied and udp_replied controls udp "connection" timeouts, normally 30/180 + udp_unreplied = 180 + udp_replied = 180 + + [PIPELINE3] + type = VFW + core = 2 + pktq_in = RXQ0.1 RXQ1.1 + pktq_out = TXQ0.2 TXQ1.2 SWQ1 + + n_rules = 4096 + ;n_flows gets round up to power of 2 + n_flows = 1048576 + + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 + tcp_be_liberal = 0 + ;udp_unreplied and udp_replied controls udp "connection" timeouts, normally 30/180 + udp_unreplied = 180 + udp_replied = 180 + + [PIPELINE4] + type = VFW + core = 3 + pktq_in = RXQ0.2 RXQ1.2 + pktq_out = TXQ0.3 TXQ1.3 SWQ2 + + n_rules = 4096 + ;n_flows gets round up to power of 2 + n_flows = 1048576 + + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 + tcp_be_liberal = 0 + ;udp_unreplied and udp_replied controls udp "connection" timeouts, normally 30/180 + udp_unreplied = 180 + udp_replied = 180 + + [PIPELINE5] + type = VFW + core = 4 + pktq_in = RXQ0.3 RXQ1.3 + pktq_out = TXQ0.4 TXQ1.4 SWQ3 + + n_rules = 4096 + ;n_flows gets round up to power of 2 + n_flows = 1048576 + + traffic_type = 4 ; IPv4 Traffic + ;traffic_type = 6 ; IPv6 Traffic + ; tcp_time_wait controls timeout for closed connection, normally 120 + tcp_time_wait = 10 + tcp_be_liberal = 0 + ;udp_unreplied and udp_replied controls udp "connection" timeouts, normally 30/180 + udp_unreplied = 180 + udp_replied = 180 + + +vACL 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/vACL/config) folder +of the VNFs. + +1. SWLB, IPv4, Single Port Pair, 1 WT: + + :: + + [EAL] + # add pci whitelist eg below + w = 05:00.0 ; Network Ports binded to dpdk + w = 05:00.1 ; Network Ports binded to dpdk + + [PIPELINE0] + type = MASTER + core = 0 + + [PIPELINE1] + type = ARPICMP + core = 0 + pktq_in = SWQ2 + pktq_out = SWQ7 + pktq_in_prv = RXQ0.0 + prv_to_pub_map = (0,1) + prv_que_handler = (0) + + [PIPELINE2] + type = TXRX + core = 1 + pktq_in = RXQ0.0 RXQ1.0 + pktq_out = SWQ0 SWQ1 SWQ2 + pipeline_txrx_type = RXRX + dest_if_offset = 176 + + [PIPELINE3] + type = LOADB + core = 2 + pktq_in = SWQ0 SWQ1 + pktq_out = SWQ3 SWQ4 + outport_offset = 136 + phyport_offset = 204 + n_vnf_threads = 1 + prv_que_handler = (0) + + [PIPELINE4] + type = ACL + core = 3 + pktq_in = SWQ3 SWQ4 + pktq_out = SWQ5 SWQ6 + n_flows = 1000000 + pkt_type = ipv4 + traffic_type = 4 + + [PIPELINE5] + type = TXRX + core = 1h + pktq_in = SWQ5 SWQ6 SWQ7 + pktq_out = TXQ0.0 TXQ1.0 + pipeline_txrx_type = TXTX + + +2. SWLB, IPv4, Single Port Pair, 1 WT: + + :: + + [EAL] + # add pci whitelist eg below + w = 05:00.0 + w = 05:00.1 + + [PIPELINE0] + type = MASTER + core = 0 + + [PIPELINE1] + type = ARPICMP + core = 0 + pktq_in = SWQ0 + pktq_out = TXQ0.0 TXQ1.0 + pktq_in_prv = RXQ0.0 + prv_to_pub_map = (0,1) + prv_que_handler = (0) + + [PIPELINE2] + type = ACL + core = 1 + pktq_in = RXQ0.0 RXQ1.0 + pktq_out = TXQ0.1 TXQ1.1 SWQ0 + n_flows = 1000000 + pkt_type = ipv4 + traffic_type = 4 + + + diff --git a/docs/testing/user/userguide/index.rst b/docs/testing/user/userguide/index.rst index 2099025f..71f3a0e7 100644 --- a/docs/testing/user/userguide/index.rst +++ b/docs/testing/user/userguide/index.rst @@ -17,5 +17,7 @@ SampleVNF User Guide 03-architecture 04-installation 05-How_to_run_SampleVNFs + 06-How_to_use_REST_api + 07-Config_files glossary references |