diff options
Diffstat (limited to 'docs')
16 files changed, 1396 insertions, 693 deletions
diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index 192e82e5..e2a66217 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -23,7 +23,7 @@ OPNFV Euphrates Release Note for SampleVNF .. toctree:: :maxdepth: 2 -.. _SampleVNF: https://wiki.opnfv.org/samplevnf +.. _SampleVNF: https://wiki.opnfv.org/SAM .. _Yardstick: https://wiki.opnfv.org/yardstick @@ -43,8 +43,7 @@ Version History | *Date* | *Version* | *Comment* | | | | | +----------------+--------------------+---------------------------------+ -+----------------+--------------------+---------------------------------+ -| | 1.0 | SampleVNF for Euphrates release | +| "Oct 20 2017" | 5.0 | SampleVNF for Euphrates release | | | | | +----------------+--------------------+---------------------------------+ @@ -53,9 +52,8 @@ Important Notes =============== The software delivered in the OPNFV SampleVNF_ Project, comprising the -*SampleVNF VNFs*, the *SampleVNF test cases* and performance test case -are part of OPNFV Yardstick_ Project is a realization of the methodology in -ETSI-ISG NFV-TST001_. +*SampleVNF VNFs* and performance test case are part of OPNFV Yardstick_ +Project is a realization of the methodology in ETSI-ISG NFV-TST001_. OPNFV Euphrates Release @@ -79,6 +77,26 @@ OPNFV platform, including: * SampleVNF source code +For Euphrates release, the *SampleVNF* supported: + ++----------------+---------------------------------------------------------+-------------------+ +| *VNF* | *Name* | *version* | ++----------------+---------------------------------------------------------+-------------------+ +| *CGNAPT* | Carrier Grade Network Address and port Translation .5.0 | v0.1.0 | ++----------------+---------------------------------------------------------+-------------------+ +| *Prox* | Packet pROcessing eXecution engine | v0.39.0 | +| | acts as traffic generator, L3FWD, L2FWD, BNG etc | | ++----------------+---------------------------------------------------------+-------------------+ +| *vACL* | Access Control List | v0.1.0 | ++----------------+---------------------------------------------------------+-------------------+ +| *vFW* | Firewall | v0.1.0 | ++----------------+---------------------------------------------------------+-------------------+ +| *UDP_replay* | UDP_Replay | v0.1.0 | ++----------------+---------------------------------------------------------+-------------------+ + +.. note:: Highlevel Desgin and features supported by each of the VNFs is described in Developer + and user guide. + For Euphrates release, the *SampleVNF* is used for the following testing: @@ -93,9 +111,9 @@ testing: * Network - rfc2544, rfc3511, latency, http_test etc -The *SampleVNF* is developed in the OPNFV community, by the -SampleVNF_ team. The *Network Service Benchmarking* Testing tool is a part of -the Yardstick Project. +The *SampleVNF* is developed in the OPNFV community, by the SampleVNF_ team. +The *Network Service Benchmarking* SampleVNF Characterization Testing tool is a part of the +Yardstick Project. .. note:: The test case description template used for the SampleVNF in yardstick test cases is based on the document ETSI-ISG NFV-TST001_; the results report template @@ -109,19 +127,19 @@ Release Data | **Project** | SampleVNF | | | | +--------------------------------------+--------------------------------------+ -| **Repo/tag** | | +| **Repo/tag** | samplevnf/Euphrates.5.0 | | | | +--------------------------------------+--------------------------------------+ -| **SampleVNF Docker image tag** | | +| **SampleVNF Docker image tag** | Euphrates.5.0 | | | | +--------------------------------------+--------------------------------------+ | **Release designation** | Euphrates | | | | +--------------------------------------+--------------------------------------+ -| **Release date** | | +| **Release date** | "October 20 2017" | | | | +--------------------------------------+--------------------------------------+ -| **Purpose of the delivery** | | +| **Purpose of the delivery** | OPNFV Euphrates release 5.0 | | | | +--------------------------------------+--------------------------------------+ @@ -132,9 +150,9 @@ Deliverables Documents --------- - - User Guide + - User Guide: http://artifacts.opnfv.org/samplevnf/euphrates/5.0.0/docs/testing_user_userguide/index.html - - Developer Guide + - Developer Guide: http://artifacts.opnfv.org/samplevnf/euphrates/5.0.0/docs/testing_developer/index.html Software Deliverables @@ -166,9 +184,6 @@ This is the first version of the SampleVNF in OPNFV. It includes the following documentation updates: - SampleVNF User Guide: - add "network service benchmarking(NSB)" chapter; - add "SampleVNF - NSB Testing -Installation" chapter; add "SampleVNF API" chapter; - add "SampleVNF user interface" chapter; Update SampleVNF installation chapter; - SampleVNF Developer Guide @@ -185,24 +200,29 @@ Feature additions Known Issues/Faults ------------------- - - +- Huge page freeing needs to be handled properly while running the application else it might + cause system crash. Known issue from DPDK. +- UDP Replay is used to capture throughput for dynamic cgnapt +- Hardware Checksum offload is not supported for IPv6 traffic +- SampleVNF on sriov is tested till 4 threads +- Rest API is supported only for vACL, vFW, vCGNAPT +- Rest API uses port 80, make sure other webservices are stopped before using SampleVNF RestAPI. Corrected Faults ---------------- -Euphrates.1.0: +Euphrates.5.0: +----------------------------+------------------------------------------------+ | **JIRA REFERENCE** | **DESCRIPTION** | | | | +----------------------------+------------------------------------------------+ -| JIRA: samplevnf- | | +| | | | | | +----------------------------+------------------------------------------------+ -Euphrates known restrictions/issues +Euphrates known restrictions/issues ==================================== +-----------+-----------+----------------------------------------------+ | Installer | Scenario | Issue | diff --git a/docs/release/results/overview.rst b/docs/release/results/overview.rst index 77b36542..df04d327 100644 --- a/docs/release/results/overview.rst +++ b/docs/release/results/overview.rst @@ -3,7 +3,7 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Intel Corporation and other. -Yardstick test tesult document overview +SampleVNF test tesult document overview ======================================= .. _`SampleVNF user guide`: artifacts.opnfv.org/samplevnf/docs/userguide/index.html diff --git a/docs/testing/developer/design/01-Overview.rst b/docs/testing/developer/design/01-Overview.rst index a1ae66af..5cd22bb1 100644 --- a/docs/testing/developer/design/01-Overview.rst +++ b/docs/testing/developer/design/01-Overview.rst @@ -14,7 +14,8 @@ Introduction .. _SampleVNF: https://wiki.opnfv.org/samplevnf .. _Technical_Briefs: https://wiki.opnfv.org/display/SAM/Technical+Briefs+of+VNFs -Overview: + +Overview --------- This project provides a placeholder for various sample VNF (Virtual Network Function) @@ -23,10 +24,17 @@ 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 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 +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. + +The purpose is to encourage the community to contribute and close the feature gaps. + + :: + + * Not a commercial product. + † 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 @@ -35,15 +43,25 @@ the sample VNFs through OPEN SOURCE VNF approximations and test tools. The VNFs belongs to this project are never meant for field deployment. All the VNF source code part of this project requires Apache License Version 2.0. -Scope: +Scope ----- -The Scope of samplevnf project as follows" -To create a repository of sample VNFs to help VNF benchmarking and NFVi -characterization with real world traffic. -Host a common development environment for developing the VNF using optimized libraries -Integrate into CI tool chain and existing test frameworks for VNF feature and deployment testing +The Scope of samplevnf project is to create a repository of sample VNFs +to help VNF benchmarking and NFVi characterization with real world traffic. + +Also to host a common development environment for developing the VNF using +optimized libraries and integrate into CI tool chain and existing test +frameworks for VNF feature and deployment testing. + +About DPDK +---------- +The DPDK IP Pipeline Framework provides set of libraries to build a pipeline +application. + +This document assumes the reader possess the knowledge of DPDK concepts and IP +Pipeline Framework. For more details, read DPDK Getting Started Guide, DPDK +Programmers Guide, DPDK Sample Applications Guide. -Testability: +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. diff --git a/docs/testing/developer/design/02-Get_started_Guide.rst b/docs/testing/developer/design/02-Get_started_Guide.rst index 995a2270..c8f35ed3 100644 --- a/docs/testing/developer/design/02-Get_started_Guide.rst +++ b/docs/testing/developer/design/02-Get_started_Guide.rst @@ -14,62 +14,79 @@ Get started as a SampleVNF developer .. _Technical_Briefs: https://wiki.opnfv.org/display/SAM/Technical+Briefs+of+VNFs Prerequisite knowledge ------------------------ -Development/Contribution to SampleVNF requires knowledge of networking technologies including -knowledge of network protocols and hands-on experience with relevant open-source -software, such as Linux*, SDN, NFVI and the DPDK (if VNF is based on DPDK libraries). -Developer needs debugging and benchmarking skils, as well as understanding of NFVi -infrastructure across multiple domains. +====================== + +Development/Contribution to SampleVNF requires knowledge of networking +technologies including knowledge of network protocols and hands-on experience +with relevant open-source software, such as Linux*, SDN, NFVI and the DPDK (if +VNF is based on DPDK libraries). +Developer needs debugging and benchmarking skills, as well as understanding of +NFVi infrastructure across multiple domains. There are many ways to contribute to samplevnf. + * Develop new test cases in samplevnf * Review code changes * Develop/contribute to existing VNFs or new VNFs * Write samplevnf documentation -Techical Briefs of existsin VNFs in Technical_Briefs_ +Technical Briefs of exists in VNFs in Technical_Briefs_ + +Get Started +=========== -Get Started: ----------- Where can I find some help to start? -You can also directly contact us by mail with [SampleVNF] prefix in the title at -opnfv-tech-discuss@lists.opnfv.org or on the IRC chan #opnfv-samplevnf. + +You can also directly contact us by mail with [SampleVNF] prefix in the title +at opnfv-tech-discuss@lists.opnfv.org or on the IRC chan #opnfv-samplevnf. How TOs +------- + How can I contribute to SampleVNF? -If you are already a contributor of any OPNFV project, you can contribute to samplevnf. -If you are totally new to OPNFV, you must first create your Linux Foundation account, -then contact us in order to declare you in the repository database. + +If you are already a contributor of any OPNFV project, you can contribute to +samplevnf. +If you are totally new to OPNFV, you must first create your Linux Foundation +account, then contact us in order to declare you in the repository database. We distinguish 2 levels of contributors: -the standard contributor can push patch and vote +1/0/-1 on any samplevnf patch -The commitor can vote -2/-1/0/+1/+2 and merge -SampleVNF commitors are promoted by the samplevnf contributors. +The standard contributor can push patch and vote +1/0/-1 on any samplevnf patch +The committer can vote -2/-1/0/+1/+2 and merge. +SampleVNF committers are promoted by the samplevnf contributors. Gerrit & JIRA +------------- + OPNFV uses Gerrit_ for web based code review and repository management for the Git Version Control System. You can access OPNFV Gerrit from this link. -Please note that you need to have Linux Foundation ID in order to use OPNFV Gerrit. +Please note that you need to have Linux Foundation ID in order to use OPNFV +Gerrit. You can get one from this link. -OPNFV uses JIRA_ for issue management. An important principle of change management -is to have two-way trace-ability between issue management (i.e. JIRA_) and the code repository (via Gerrit). -In this way, individual commits can be traced to JIRA issues and we also know which -commits were used to resolve a JIRA issue. +OPNFV uses JIRA_ for issue management. An important principle of change +management is to have two-way traceability between issue management (i.e. JIRA_)and the code repository (via Gerrit). +In this way, individual commits can be traced to JIRA issues and we also know +which 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. +------------------------- + +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. +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 samplevnf project folder. Replace this with the path of your own project. :: + cd /home/opnfv/samplevnf Tell Git which files you would like to take into account for the next commit. @@ -77,25 +94,34 @@ This is called 'staging' the files, by placing them into the staging area, using the 'git add' command (or the synonym 'git stage' command). :: + git add samplevnf/samples/sample.yaml ... Alternatively, you can choose to stage all files that have been modified -(that is the files you have worked on) since the last time you generated a commit, by using the -a argument. +(that is the files you have worked on) since the last time you generated a +commit, by using the -a argument. :: + git add -a -Git won't let you push (upload) any code to Gerrit if you haven't pulled the latest changes first. -So the next step is to pull (download) the latest changes made to the project by other collaborators using the 'pull' command. +Git won't let you push (upload) any code to Gerrit if you haven't pulled +the latest changes first. +So the next step is to pull (download) the latest changes made to the project +by other collaborators using the 'pull' command. :: + git pull -Now that you have the latest version of the project and you have staged the files you wish to push, -it is time to actually commit your work to your local Git repository. + +Now that you have the latest version of the project and you have staged the +files you wish to push, 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 @@ -104,20 +130,24 @@ it is time to actually commit your work to your local Git repository. JIRA: SAMPLEVNF-XXX" -The message that is required for the commit should follow a specific set of rules. -This practice allows to standardize the description messages attached to the commits, -and eventually navigate among the latter more easily. +The message that is required for the commit should follow a specific set of +rules. This practice allows to standardize the description messages attached +to the commits, and eventually navigate among the latter more easily. Verify your patch locally before submitting Once you finish a patch, you can submit it to Gerrit for code review. -A developer sends a new patch to Gerrit will trigger patch verify job on Jenkins CI. +A developer sends a new patch to Gerrit will trigger patch verify job on +Jenkins CI. Pushing the code to Gerrit for review -Now that the code has been comitted into your local Git repository the following -step is to push it online to Gerrit for it to be reviewed. The command we will use is 'git review'. +Now that the code has been comitted into your local Git repository the +following step is to push it online to Gerrit for it to be reviewed. The +command we will use is 'git review'. :: + git review + This will automatically push your local commit into Gerrit. Code review @@ -125,21 +155,30 @@ 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. -Once you have modified/edited your code files under your IDE, you will have to stage them. -The 'status' command is very helpful at this point as it provides an overview of Git's current state. +make some changes and then send it back for review. The following steps go +through the procedure. +Once you have modified/edited your code files under your IDE, you will have to +stage them. +The 'status' command is very helpful at this point as it provides an overview +of Git's current state. :: + 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 -create a new commit, we simply want to inject the new changes into the previous commit. +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 create a new commit, we simply want to inject the new changes into the +previous commit. + You can achieve that with the '--amend' option on the 'commit' command: :: + git commit --amend If the commit was successful, the 'status' command should not return the updated @@ -148,6 +187,7 @@ files as about to be commited. The final step consists in pushing the newly modified commit to Gerrit. :: + git review References diff --git a/docs/testing/developer/design/04-SampleVNF_Design.rst b/docs/testing/developer/design/04-SampleVNF_Design.rst index dff8d535..a3332e27 100644 --- a/docs/testing/developer/design/04-SampleVNF_Design.rst +++ b/docs/testing/developer/design/04-SampleVNF_Design.rst @@ -4,60 +4,35 @@ .. OPNFV SAMPLEVNF Documentation design file. -=================================== +========================== SampleVNF Highlevel Design -=================================== - -Introduction --------------- -This project provides a placeholder for various sample VNF (Virtual Network Function) -development which includes example 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 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 - -About DPDK -^^^^^^^^^^^ -The DPDK IP Pipeline Framework provides set of libraries to build a pipeline -application. In this document, CG-NAT application will be explained with its -own building blocks. - -This document assumes the reader possess the knowledge of DPDK concepts and IP -Pipeline Framework. For more details, read DPDK Getting Started Guide, DPDK -Programmers Guide, DPDK Sample Applications Guide. - -Scope --------- -These application provides a standalone DPDK based high performance different -Virtual Network Function implementation. +========================== +The high level design of the VNF and common code is explained here. Common Code - L2L3 stack -------------------------- +======================== Introduction -^^^^^^^^^^^^^^^ +------------ + L2L3 stack comprises of a set of libraries which are commonly used by all -other VNF's. The different components of this stack is shown in the picture -below. +other VNF's. -.. image:: l2l3-components.png +.. image:: images/l2l3-components.png + :width: 800px It comprises of following components. - (i) Interface Manager - (ii) RTM Lock Library - (iii) ARP/ND & L2 adjacency Library - (iv) L3 stack components - + * Interface Manager + * RTM Lock Library + * ARP/ND & L2 adjacency Library + * L3 stack components Interface Manager -^^^^^^^^^^^^^^^^^ +----------------- + Interface manager is a set of API's which acts as a wrapper for the physical interfaces initialization & population. This set of api's assists in configuring an ethernet device, setting up TX & RX queues & starting of the devices. It @@ -68,21 +43,23 @@ components who wants to listen to interface status. It Maintains table of all the interfaces present. It provides API for getting interface statistics. It Provides wrapper APIs on top of DPDKs LAG(link Aggregation) APIs, This -includes creating/deleting BOND interfaces, knowing the properties like Bond mode, -xmit policy, link up delay, link monitor frequency. +includes creating/deleting BOND interfaces, knowing the properties like Bond +mode, xmit policy, link up delay, link monitor frequency. RTM Lock Library -^^^^^^^^^^^^^^^^^ +---------------- + It provides basic lock & unlock functions which should be used for synchronization purposes. ARP/ND & L2 adjacency Library -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- The ARP/ND state machine is given in the following diagram. -.. image:: state-machine.png +.. image:: images/state-machine.png + :width: 800px This library provides api's for handling ARP/ICMPv4 & ND/ICMPV6 packets handling. It provides api's for creating/deleting & populating an entry. @@ -102,17 +79,18 @@ retrieval based on nexthop & port_id. It handles Gratuitous ARP. L3 stack Library -^^^^^^^^^^^^^^^^^ +---------------- This library provides API for taking decision of whether pkt belongs to local system or to forwarding.It Provides API for IPv4/IPv6 local packet out send function. It Provides API for packet forwarding - LPM lookup function. + Common Code - Gateway routing ------------------------------ +============================= Introduction -^^^^^^^^^^^^ +------------ Gateway common code is created to support routing functionality for both network and direct attached interfaces. It is supported for both IPv4 and @@ -129,7 +107,8 @@ allocated only for the nb_ports which is configured as per the VNF application configuration. Design -^^^^^^ +------ + The next hop IP and Port numbers are retrieved from the routing table based on the destinantion IP addreess. The destination IP address anded with mask is looked in the routing table for the match. The port/interface number which @@ -144,31 +123,30 @@ of parameters provide in the commands are not valied. Example the if port number is bigger than the supported number ports/interface per application configuration. - Reference routeadd command -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- Following are typical reference commands and syntax for adding routes using the CLI. :: -;routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask/NotApplicable> -routeadd net 0 202.16.100.20 0xffff0000 -routeadd net 1 172.16.40.20 0xffff0000 -routeadd host 0 202.16.100.20 -routeadd host 1 172.16.40.20 + ;routeadd <net/host> <port #> <ipv4 nhip address in decimal> <Mask/NotApplicable> + routeadd net 0 202.16.100.20 0xffff0000 + routeadd net 1 172.16.40.20 0xffff0000 + routeadd host 0 202.16.100.20 + routeadd host 1 172.16.40.20 -;routeadd <net/host> <port #> <ipv6 nhip address in hex> <Depth/NotApplicable> -routeadd net 0 fec0::6a05:caff:fe30:21b0 64 -routeadd net 1 2012::6a05:caff:fe30:2081 64 -routeadd host 0 fec0::6a05:caff:fe30:21b0 -routeadd host 1 2012::6a05:caff:fe30:2081 + ;routeadd <net/host> <port #> <ipv6 nhip address in hex> <Depth/NotApplicable> + routeadd net 0 fec0::6a05:caff:fe30:21b0 64 + routeadd net 1 2012::6a05:caff:fe30:2081 64 + routeadd host 0 fec0::6a05:caff:fe30:21b0 + routeadd host 1 2012::6a05:caff:fe30:2081 vFW - Design -============= +============ Requirements -------------- +------------ Following are the design requierments of the vFW. @@ -188,7 +166,7 @@ Following are the design requierments of the vFW. performance. High Level Design -------------------- +----------------- The Firewall performs basic filtering for malformed packets and dynamic packet filtering incoming packets using the connection tracker library. @@ -274,10 +252,11 @@ connection. The ACL library integrated to firewall provide rule based filtering. vCGNAPT - Design -================= +================ Introduction -^^^^^^^^^^^^^^ +------------ + This application implements vCGNAPT. The idea of vCGNAPT is to extend the life of the service providers IPv4 network infrastructure and mitigate IPv4 address exhaustion by using address and port translation in large scale. It processes the @@ -287,12 +266,14 @@ It also supports the connectivity between the IPv6 access network to IPv4 data n using the IPv6 to IPv4 address translation and vice versa. Scope -^^^^^^ +----- + This application provides a standalone DPDK based high performance vCGNAPT Virtual Network Function implementation. Features -^^^^^^^^^ +-------- + The vCGNAPT VNF currently supports the following functionality: • Static NAT • Dynamic NAT @@ -308,9 +289,9 @@ The vCGNAPT VNF currently supports the following functionality: • Live Session tracking to NAT flow • NAT64 - High Level Design -^^^^^^^^^^^^^^^^^^^ +----------------- + The Upstream path defines the traffic from Private to Public and the downstream path defines the traffic from Public to Private. The vCGNAPT has same set of components to process Upstream and Downstream traffic. @@ -327,46 +308,51 @@ information from which side packet is arrived. The actions can be forwarding to output port (either egress or ingress) or to drop the packet. vCGNAPT Background -^^^^^^^^^^^^^^^^^^^ +------------------ The idea of vCGNAPT is to extend the life of the service providers IPv4 network infrastructure and mitigate IPv4 address exhaustion by using address and port translation in large scale. -It processes the traffic in both the directions. :: -+------------------+ -| +-----+ -| Private consumer | CPE ---- -| IPv4 traffic +-----+ | -+------------------+ | +It processes the traffic in both the directions. + +:: + + +------------------+ + | +-----+ + | Private consumer | CPE ---- + | IPv4 traffic +-----+ | + +------------------+ | | +-------------------+ +------------------+ | | +------------+ - |-> - Private IPv4 - vCGNAPT - Public - |-> - access network - NAT44 - IPv4 traffic - | | +------------+ - | +-------------------+ +------------------+ -+------------------+ | -| +-----+ | -| Private consumer - CPE ---- -| IPv4 traffic +-----+ -+------------------+ + +------------------+ | + | +-----+ | + | Private consumer - CPE ---- + | IPv4 traffic +-----+ + +------------------+ Figure: vCGNAPT deployment in Service provider network Components of vCGNAPT --------------------- -In vCGNAPT, each component is constructed as a packet framework. It includes Master pipeline -component, driver, load balancer pipeline component and vCGNAPT worker pipeline component. A -pipeline framework is a collection of input ports, table(s), output ports and actions -(functions). +In vCGNAPT, each component is constructed as a packet framework. It includes +Master pipeline component, driver, load balancer pipeline component and +vCGNAPT worker pipeline component. A pipeline framework is a collection of +input ports, table(s), output ports and actions (functions). Receive and transmit driver -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Packets will be received in bulk and provided to load balancer thread. The transmit takes -packets from worker thread in a dedicated ring and sent to the hardware queue. +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Packets will be received in bulk and provided to load balancer thread. The +transmit takes packets from worker thread in a dedicated ring and sent to the +hardware queue. Master pipeline ^^^^^^^^^^^^^^^^ This component does not process any packets and should configure with Core 0, to save cores for other components which processes traffic. The component is responsible for: + 1. Initializing each component of the Pipeline application in different threads 2. Providing CLI shell for the user 3. Propagating the commands from user to the corresponding components. @@ -386,6 +372,7 @@ Tuple can be modified/configured using configuration file vCGNAPT - Static ------------------ + The vCGNAPT component performs translation of private IP & port to public IP & port at egress side and public IP & port to private IP & port at Ingress side based on the NAT rules added to the pipeline Hash table. The NAT rules are @@ -397,94 +384,114 @@ the packets. vCGNAPT- Dynamic ----------------- -The vCGNAPT component performs translation of private IP & port to public IP & port -at egress side and public IP & port to private IP & port at Ingress side based on the -NAT rules added to the pipeline Hash table. Dynamic nature of vCGNAPT refers to the -addition of NAT entries in the Hash table dynamically when new packet arrives. The NAT -rules will be added to the Hash table automatically when there is no matching entry in -the table and the packet is circulated through software queue. The packets that have a -matching egress key or ingress key in the NAT table will be processed to change IP & + +The vCGNAPT component performs translation of private IP & port to public IP & +port at egress side and public IP & port to private IP & port at Ingress side +based on the NAT rules added to the pipeline Hash table. Dynamic nature of +vCGNAPT refers to the addition of NAT entries in the Hash table dynamically +when new packet arrives. The NAT rules will be added to the Hash table +automatically when there is no matching entry in the table and the packet is +circulated through software queue. The packets that have a matching egress +key or ingress key in the NAT table will be processed to change IP & port and will be forwarded to the output port defined in the entry. -Dynamic vCGNAPT acts as static one too, we can do NAT entries statically. Static NAT -entries port range must not conflict to dynamic NAT port range. +Dynamic vCGNAPT acts as static one too, we can do NAT entries statically. +Static NAT entries port range must not conflict to dynamic NAT port range. + +vCGNAPT Static Topology +---------------------- -vCGNAPT Static Topology: --------------------------- IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 1) IXIA operation: Egress --> The packets sent out from ixia(port 0) will be CGNAPTed to ixia(port 1). Igress --> The packets sent out from ixia(port 1) will be CGNAPTed to ixia(port 0). -vCGNAPT Dynamic Topology (UDP_REPLAY): --------------------------------------- +vCGNAPT Dynamic Topology (UDP_REPLAY) +------------------------------------- + IXIA(Port 0)-->(Port 0)VNF(Port 1)-->(Port 0)UDP_REPLAY operation: Egress --> The packets sent out from ixia will be CGNAPTed to L3FWD/L4REPLAY. Ingress --> The L4REPLAY upon reception of packets (Private to Public Network), will immediately replay back the traffic to IXIA interface. (Pub -->Priv). -How to run L4Replay: --------------------- - 1. After the installation of ISB on L4Replay server - go to /opt/isb_bin - 2. ./UDP_Replay -c core_mask -n no_of_channels(let it be as 2) -- -p PORT_MASK --config="(port,queue,lcore)" - eg: ./UDP_Replay -c 0xf -n 4 -- -p 0x3 --config="(0,0,1)" +How to run L4Replay +------------------- + +After the installation of ISB on L4Replay server go to /opt/isb_bin and run the +following command. + +:: + + ./UDP_Replay -c core_mask -n no_of_channels(let it be as 2) -- -p PORT_MASK --config="(port,queue,lcore)" + eg: ./UDP_Replay -c 0xf -n 4 -- -p 0x3 --config="(0,0,1)" vACL - Design -================= +============= Introduction -------------- -This application implements Access Control List (ACL). ACL is typically used for rule -based policy enforcement. It restricts access to a destination IP address/port based -on various header fields, such as source IP address/port, destination IP address/port -and protocol. It is built on top of DPDK and uses the packet framework infrastructure. +This application implements Access Control List (ACL). ACL is typically used +for rule based policy enforcement. It restricts access to a destination IP +address/port based on various header fields, such as source IP address/port, +destination IP address/port and protocol. It is built on top of DPDK and uses +the packet framework infrastructure. Scope ------ -This application provides a standalone DPDK based high performance ACL Virtual Network -Function implementation. +This application provides a standalone DPDK based high performance ACL Virtual +Network Function implementation. High Level Design ------------------ -The ACL Filter performs bulk filtering of incoming packets based on rules in current ruleset, -discarding any packets not permitted by the rules. The mechanisms needed for building the -rule database and performing lookups are provided by the DPDK API. +The ACL Filter performs bulk filtering of incoming packets based on rules in +current ruleset, discarding any packets not permitted by the rules. The +mechanisms needed for building the rule database and performing lookups are +provided by the DPDK API. + http://dpdk.org/doc/api/rte__acl_8h.html -The Input FIFO contains all the incoming packets for ACL filtering. Packets will be dequeued -from the FIFO in bulk for processing by the ACL. Packets will be enqueued to the output FIFO. +The Input FIFO contains all the incoming packets for ACL filtering. Packets +will be dequeued from the FIFO in bulk for processing by the ACL. Packets will +be enqueued to the output FIFO. + The Input and Output FIFOs will be implemented using DPDK Ring Buffers. -The DPDK ACL example: http://dpdk.org/doc/guides/sample_app_ug/l3_forward_access_ctrl.html +The DPDK ACL example: + +http://dpdk.org/doc/guides/sample_app_ug/l3_forward_access_ctrl.html + #figure-ipv4-acl-rule contains a suitable syntax and parser for ACL rules. Components of ACL ------------------ -In ACL, each component is constructed as a packet framework. It includes Master pipeline -component, driver, load balancer pipeline component and ACL worker pipeline component. A -pipeline framework is a collection of input ports, table(s), output ports and actions -(functions). +In ACL, each component is constructed as a packet framework. It includes +Master pipeline component, driver, load balancer pipeline component and ACL +worker pipeline component. A pipeline framework is a collection of input ports, +table(s), output ports and actions (functions). Receive and transmit driver ---------------------------- -Packets will be received in bulk and provided to load balancer thread. The transmit takes -packets from worker thread in a dedicated ring and it is sent to the hardware queue. +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Packets will be received in bulk and provided to load balancer thread. The +transmit takes packets from worker thread in a dedicated ring and it is sent +to the hardware queue. Master -------- +^^^^^^ This component does not process any packets and should configure with Core 0, -to save cores for other components which processes traffic. The component -is responsible for: +to save cores for other components which processes traffic. + +The component is responsible for + 1. Initializing each component of the Pipeline application in different threads 2. Providing CLI shell for the user 3. Propagating the commands from user to the corresponding components. 4. ARP and ICMP are handled here. Load Balancer --------------- +^^^^^^^^^^^^^ + Load balancer is part of the Multi-Threaded ACL release which distributes the flows to Multiple ACL worker threads. @@ -493,9 +500,11 @@ address, destination port and protocol) applying an XOR logic distributing the load to active worker threads, thereby maintaining an affinity of flows to worker threads. -ACL ---- +ACL Pipeline +^^^^^^^^^^^^ + Visit the following link for DPDK ACL library implementation. + http://dpdk.org/doc/api/rte__acl_8h.html http://dpdk.org/doc/guides/prog_guide/packet_classif_access_ctrl.html @@ -504,10 +513,11 @@ Provides shadow copy for runtime rule configuration support Implements policy based packet forwarding vPE - Design -============= +============ Introduction ---------------- +------------ + An Edge Router typically sits between two networks such as the provider core network and the provider access network. In the below diagram, Customer Edge (CE) Router sits in the provider access network and MPLS cloud network @@ -529,12 +539,14 @@ IP Pipeline Framework. For more details, read DPDK Getting Started Guide, DPDK Programmers Guide, DPDK Sample Applications Guide. Scope ------- +----- + This application provides a standalone DPDK based high performance Provide Edge Router Network Function implementation. High Level Design -------------------- +----------------- + The Edge Router application processes the traffic between Customer and the core network. The Upstream path defines the traffic from Customer to Core and the downstream @@ -596,6 +608,7 @@ Edge Router has the following functionalities in Upstream. Components of vPE ------------------- + The vPE has downstream and upstream pipelines controlled by Master component. Edge router processes two different types of traffic through pipelines I. Downstream (Core-to-Customer) @@ -617,7 +630,8 @@ II. Upstream (Customer-to-Core) 5. Appends two MPLS labels in each outgoing packet. Master Component ------------------ +^^^^^^^^^^^^^^^^ + The Master component is part of all the IP Pipeline applications. This component does not process any packets and should configure with Core0, to save cores for other components which processes traffic. The component @@ -627,20 +641,26 @@ is responsible for 3. Propagating the commands from user to the corresponding components. Upstream and Downstream Pipelines ----------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + The downstream will have Firewall, Pass-through, Metering and Routing pipelines. The upstream will have Pass-through and Routing pipelines. To run the VNF, execute the following: -isb_root/VNFs/vPE$ ./build/ip_pipeline -p 0x3 \ + +:: + + isb_root/VNFs/vPE$ ./build/ip_pipeline -p 0x3 \ -f config/auto_combo_1_instances_1_queues_2_ports_v2.cfg \ -s config/auto_combo_1_instances_1_queues_2_ports_v2.txt + Prox - Packet pROcessing eXecution engine ========================================== -Overview: ----------- +Introduction +------------ + 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 @@ -653,6 +673,7 @@ configuration files. The figure shows that each core is executing a set of tasks. Currently, a task can be any one of the following: + 1. Classify 2. Drop 3. Basic Forwarding (no touch) @@ -669,14 +690,15 @@ a task can be any one of the following: 14. ACL ... One of the example configurations that is distributed with the source code is a -Proof of Concept (PoC) implementation of a Broadband Network Gateway (BNG) with Quality of Service (QoS). +Proof of Concept (PoC) implementation of a Broadband Network Gateway (BNG) +with Quality of Service (QoS). The software architecture for this PoC is presented below. .. image:: images/prox-qo-img02.png The display shows per task statistics through an ncurses interface. -Statistics include: estimated idleness; per second statistics for packets received, -transmitted or dropped; per core cache occupancy; cycles per packet. +Statistics include: estimated idleness; per second statistics for packets +received, transmitted or dropped; per core cache occupancy; cycles per packet. These statistics can help pinpoint bottlenecks in the system. This information can then be used to optimize the configuration. Other features include debugging support, scripting, diff --git a/docs/testing/developer/design/images/l2l3-components.png b/docs/testing/developer/design/images/l2l3-components.png Binary files differnew file mode 100644 index 00000000..751c4b7c --- /dev/null +++ b/docs/testing/developer/design/images/l2l3-components.png diff --git a/docs/testing/developer/design/images/state-machine.png b/docs/testing/developer/design/images/state-machine.png Binary files differnew file mode 100644 index 00000000..f0b06199 --- /dev/null +++ b/docs/testing/developer/design/images/state-machine.png diff --git a/docs/testing/developer/requirements/03-Requirements.rst b/docs/testing/developer/requirements/03-Requirements.rst index dab07a6e..25798606 100644 --- a/docs/testing/developer/requirements/03-Requirements.rst +++ b/docs/testing/developer/requirements/03-Requirements.rst @@ -15,24 +15,25 @@ Requirements Supported Test setup: -------------------- -The device under test (DUT) consists of a system following; + +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) * Specific Intel Network Interface Cards (NICs) * BIOS settings noting those that updated from the basic settings * DPDK build configuration settings, and commands used for tests + Connected to the DUT is an IXIA* or Software Traffic generator like pktgen or TRex, 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. -.. image:: images/deploy_type.png - :width: 800px - :alt: SampleVNF supported topology Hardware & Software Ingredients ------------------------------- -.. code-block:: console + +:: + +---------------+------------------+ | Item | Description | +---------------+------------------+ @@ -75,19 +76,22 @@ The connectivity could be - 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 + - 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 3 <------> VNF:Port 3 + 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 ab79e931..10c0161f 100755 --- a/docs/testing/user/userguide/01-introduction.rst +++ b/docs/testing/user/userguide/01-introduction.rst @@ -53,6 +53,12 @@ This document consists of the following chapters: * Chapter :doc:`05-How_to_run_SampleVNFs` provides example on how installing and running *SampleVNF*. +* Chapter :doc:`06-How_to_use_REST_api` provides info on how to run REST API *SampleVNF*. + +* Chapter :doc:`07-Config_files` provides info *SampleVNF* configuration. + +* Chapter :doc:`08-CLI_Commands_Reference` provides info on CLI commands supported by *SampleVNF* + Contact SampleVNF ================= 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..08e1b2f2 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,65 @@ 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. + +Feature supported by the VNFs +----------------------------- + +The following features were verified by SampleVNF test cases: + + - 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 + + * Static and dynamic Network address translation. + * Static and dynamic Network address and port translation + * ARP (request, response, gratuitous) + * ICMP (terminal echo, echo response, pass-through) + * UDP, TCP and ICMP protocol pass-through + * Multithread support and Multiple physical port support + * Limiting max ports per client + * Limiting max clients per public IP address + * Live Session tracking to NAT flow + * NAT64 – connectivity between IPv6 access network to IPv4 data network. + + - 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 + * Multithread support + * Multiple physical port support + * Forwarding packets to specific ports on base of rules + * Rules definition on base TCP/UDP connection tracking + + - Prox - Packet pROcessing eXecution engine. + + * Classify + * Drop + * Basic Forwarding (no touch) + * L2 Forwarding (change MAC) + * GRE encap/decap + * Load balance based on packet fields + * Symmetric load balancing + * QinQ encap/decap IPv4/IPv6 + * ARP + * QoS + * Routing + * Unmpls + * Policing + * Basic ACL + * Basic CGNAT Test Framework -------------- @@ -111,3 +170,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..e54243cb 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,15 +155,16 @@ 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. + Follow the steps in the screen from option [1] –> [10] and + select option [9] to build the vnfs. It will automatically download selected DPDK version and any required patches and will setup everything and build VNFs. + Options [8], If RestAPI feature is needed install 'civetweb' + Following are the options for setup: ---------------------------------------------------------- Step 1: Environment setup. @@ -172,17 +180,17 @@ Auto Build - Using script to build VNFs [5] Download DPDK zip [6] Build and Install DPDK [7] Setup hugepages + [8] Download and Build 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) - [9] Exit Script - * non-Interactive options: + [10] Exit Script + * non-Interactive options: :: - ./tools/vnf_build.sh -s -d=<dpdk version eg 17.02> Manual Build @@ -191,40 +199,32 @@ 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..7ba25fe1 100644 --- a/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst +++ b/docs/testing/user/userguide/05-How_to_run_SampleVNFs.rst @@ -32,7 +32,6 @@ Hardware & Software Ingredients SUT requirements: - +-----------+------------------+ | Item | Description | +-----------+------------------+ @@ -42,14 +41,13 @@ SUT requirements: +-----------+------------------+ | OS | Ubuntu 16.04 LTS | +-----------+------------------+ - | kernel | 4.4.0-34-generic| + | kernel | 4.4.0-34-generic | +-----------+------------------+ | DPDK | 17.02 | +-----------+------------------+ Boot and BIOS settings: - +------------------+---------------------------------------------------+ | Boot settings | default_hugepagesz=1G hugepagesz=1G hugepages=16 | | | hugepagesz=2M hugepages=2048 isolcpus=1-11,22-33 | @@ -57,7 +55,7 @@ Boot and BIOS settings: | | Note: nohz_full and rcu_nocbs is to disable Linux*| | | kernel interrupts, and it’s import | +------------------+---------------------------------------------------+ - |BIOS | CPU Power and Performance Policy <Performance> | + | BIOS | CPU Power and Performance Policy <Performance> | | | CPU C-state Disabled | | | CPU P-state Disabled | | | Enhanced Intel® Speedstep® Tech Disabled | @@ -75,13 +73,22 @@ 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 TG:port 1 <------> VNF:Port 1 @@ -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,20 @@ 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 +153,88 @@ 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] –> [10] and select option [9] to build the vnfs. + It will automatically download selected DPDK version and any required patches and will setup everything and build VNFs. + + Options [8], If RestAPI feature is needed install 'civetweb' + + 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 and Build 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) Add this to Go to /etc/default/grub configuration file to setup higepages. + * Append “default_hugepagesz=1G hugepagesz=1G hugepages=8 hugepagesz=2M hugepages=2048” to the GRUB_CMDLINE_LINUX entry. + * execute update-grub + * Reboot after grub setup + + 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 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 +246,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 +330,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 +415,75 @@ 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. -step 4: Run Test using traffic geneator + :: + + 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)' - On traffic generator system: +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. + 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 +495,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 @@ -527,22 +543,451 @@ PROX is a DPDK-based application implementing Telco use-cases such as a simplified BRAS/BNG, light-weight AFTR... It also allows configuring finer grained network functions like QoS, Routing, load-balancing... +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: 800px + :alt: SampleVNF supported topology + Compiling and running this application ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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/ + This application supports DPDK 16.04, 16.11, 17.02 and 17.05. The following commands assume that the following variables have been set: export RTE_SDK=/path/to/dpdk export RTE_TARGET=x86_64-native-linuxapp-gcc -Example: DPDK 17.05 installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +PROX Compiation installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* git clone https://git.opnfv.org/samplevnf +* cd samplevnf +* export RTE_SDK=`pwd`/dpdk +* export RTE_TARGET=x86_64-native-linuxapp-gcc * git clone http://dpdk.org/git/dpdk * cd dpdk * git checkout v17.05 * make install T=$RTE_TARGET +* cd <samplevnf>/VNFs/DPPD-PROX +* make + +or Auto build + +:: + + * git clone https://git.opnfv.org/samplevnf + * cd samplevnf + * ./tools/vnf_build.sh -s -d='17.05' [-p=<proxy> if behind the proxy] + +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 {} PROX compilation ^^^^^^^^^^^^^^^^ @@ -592,6 +1037,8 @@ 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 +1051,32 @@ 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..b8c0cbea 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,11 +4,11 @@ .. (c) opnfv, national center of scientific research "demokritos" and others. ======================================================== -REST API - Readme +REST API ======================================================== 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 @@ -30,7 +30,7 @@ Here are important points to be considered: 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 @@ -45,7 +45,7 @@ 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. @@ -65,243 +65,203 @@ 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: - -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(,,,); -} ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| *URI* | *Method* | *Arguments* | *description* | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf* | GET | None | Displays top level methods available | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config* | GET | None | Displays the current config set | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config* | 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 | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/arp* | POST | action: <add/del/req> | | +| | | ipv4/ipv6: <address> | | +| | | portid: <> | | +| | | macaddr: <> for add | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link* | GET | None | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link* | POST | link_id:<> | | +| | | state: <1/0> | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link/<link id>* | GET | None | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/link/<link id>* | POST | ipv4/ipv6: <address> | | +| | | depth: <> | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/route* | GET | None | Displays gateway route entries | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/route* | POST | portid: <> | Adds route entries for default gateway | +| | | nhipv4/nhipv6: <addr> | | +| | | depth: <> | | +| | | type:"net/host" | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules(vFW/vACL)* | GET | None | Displays the methods /load/clear | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules/load* | GET | None | Displays if file was loaded | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules/load* | 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 | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/config/rules/load* | 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 | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ +| */vnf/dbg/cmd* | POST | cmd: | | +| | | dbg: | | +| | | d1: | | +| | | d2: | | ++---------------------------------+-----------+--------------------------+----------------------------------------------------+ + + PUT/POST - Command success/failure +API Usage +--------- -2. Run time Usage -==================== +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 (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. 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. +1. When VNF(vCGNAPT/vACL/vFW) is launched it waits for user to provide the /vnf/config REST method. + :: -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 + :: + 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 + 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..d5564e8d 100644 --- a/docs/testing/user/userguide/07-Config_files.rst +++ b/docs/testing/user/userguide/07-Config_files.rst @@ -20,9 +20,129 @@ 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 +475,3 @@ of the VNFs. n_flows = 1000000 pkt_type = ipv4 traffic_type = 4 - - - 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 |
