diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configguide/trafficgen.rst | 9 | ||||
| -rwxr-xr-x | docs/design/vswitchperf_design.rst | 3 | ||||
| -rwxr-xr-x | docs/requirements/ietf_draft/draft-ietf-bmwg-vswitch-opnfv-01.xml | 1027 | ||||
| -rw-r--r-- | docs/requirements/vswitchperf_ltp.rst | 2 | ||||
| -rw-r--r-- | docs/userguide/index.rst | 1 | ||||
| -rwxr-xr-x | docs/userguide/integration.rst | 595 | ||||
| -rw-r--r-- | docs/userguide/teststeps.rst | 651 | ||||
| -rwxr-xr-x | docs/userguide/testusage.rst | 323 |
8 files changed, 1893 insertions, 718 deletions
diff --git a/docs/configguide/trafficgen.rst b/docs/configguide/trafficgen.rst index 6ede7f2f..efcc4d83 100644 --- a/docs/configguide/trafficgen.rst +++ b/docs/configguide/trafficgen.rst @@ -69,7 +69,7 @@ OR from the commandline: .. code-block:: console - $ ./vsperf --test-params "pkt_sizes=x,y" $TESTNAME + $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y)" $TESTNAME You can also modify the traffic transmission duration and the number of tests run by the traffic generator by extending the example @@ -77,7 +77,8 @@ commandline above to: .. code-block:: console - $ ./vsperf --test-params "pkt_sizes=x,y;duration=10;rfc2544_tests=1" $TESTNAME + $ ./vsperf --test-params "TRAFFICGEN_PKT_SIZES=(x,y);TRAFFICGEN_DURATION=10;" \ + "TRAFFICGEN_RFC2544_TESTS=1" $TESTNAME Dummy Setup ------------ @@ -475,9 +476,9 @@ One can set up this ssh access by doing the following on both servers: Configuration ~~~~~~~~~~~~~ -Connection information for your Xena Chassis must be supplied inside the +Connection information for MoonGen must be supplied inside the ``10_custom.conf`` or ``03_custom.conf`` file. The following parameters must be -set to allow for proper connections to the chassis. +set to allow for proper connections to the host with MoonGen. .. code-block:: console diff --git a/docs/design/vswitchperf_design.rst b/docs/design/vswitchperf_design.rst index 375fa12e..88b6ba88 100755 --- a/docs/design/vswitchperf_design.rst +++ b/docs/design/vswitchperf_design.rst @@ -53,7 +53,8 @@ for development purposes: .. code-block:: console - $ ./vsperf --test-params 'duration=10;rfc2544_tests=1;pkt_sizes=64' --tests 'pvp_tput' + $ ./vsperf --test-params 'TRAFFICGEN_DURATION=10;TRAFFICGEN_RFC2544_TESTS=1;' \ + 'TRAFFICGEN_PKT_SIZES=(64,)' pvp_tput Typical Test Sequence ===================== diff --git a/docs/requirements/ietf_draft/draft-ietf-bmwg-vswitch-opnfv-01.xml b/docs/requirements/ietf_draft/draft-ietf-bmwg-vswitch-opnfv-01.xml new file mode 100755 index 00000000..c8a3d99b --- /dev/null +++ b/docs/requirements/ietf_draft/draft-ietf-bmwg-vswitch-opnfv-01.xml @@ -0,0 +1,1027 @@ +<?xml version="1.0" encoding="US-ASCII"?> +<!DOCTYPE rfc SYSTEM "rfc2629.dtd"> +<?rfc toc="yes"?> +<?rfc tocompact="yes"?> +<?rfc tocdepth="3"?> +<?rfc tocindent="yes"?> +<?rfc symrefs="yes"?> +<?rfc sortrefs="yes"?> +<?rfc comments="yes"?> +<?rfc inline="yes"?> +<?rfc compact="yes"?> +<?rfc subcompact="no"?> +<rfc category="info" docName="draft-ietf-bmwg-vswitch-opnfv-01" + ipr="trust200902"> + <front> + <title abbrev="Benchmarking vSwitches">Benchmarking Virtual Switches in + OPNFV</title> + + <author fullname="Maryam Tahhan" initials="M." surname="Tahhan"> + <organization>Intel</organization> + + <address> + <postal> + <street/> + + <city/> + + <region/> + + <code/> + + <country/> + </postal> + + <phone/> + + <facsimile/> + + <email>maryam.tahhan@intel.com</email> + + <uri/> + </address> + </author> + + <author fullname="Billy O'Mahony" initials="B." surname="O'Mahony"> + <organization>Intel</organization> + + <address> + <postal> + <street/> + + <city/> + + <region/> + + <code/> + + <country/> + </postal> + + <phone/> + + <facsimile/> + + <email>billy.o.mahony@intel.com</email> + + <uri/> + </address> + </author> + + <author fullname="Al Morton" initials="A." surname="Morton"> + <organization>AT&T Labs</organization> + + <address> + <postal> + <street>200 Laurel Avenue South</street> + + <city>Middletown,</city> + + <region>NJ</region> + + <code>07748</code> + + <country>USA</country> + </postal> + + <phone>+1 732 420 1571</phone> + + <facsimile>+1 732 368 1192</facsimile> + + <email>acmorton@att.com</email> + + <uri>http://home.comcast.net/~acmacm/</uri> + </address> + </author> + + <date day="10" month="October" year="2016"/> + + <abstract> + <t>This memo describes the progress of the Open Platform for NFV (OPNFV) + project on virtual switch performance "VSWITCHPERF". This project + intends to build on the current and completed work of the Benchmarking + Methodology Working Group in IETF, by referencing existing literature. + The Benchmarking Methodology Working Group has traditionally conducted + laboratory characterization of dedicated physical implementations of + internetworking functions. Therefore, this memo begins to describe the + additional considerations when virtual switches are implemented in + general-purpose hardware. The expanded tests and benchmarks are also + influenced by the OPNFV mission to support virtualization of the "telco" + infrastructure.</t> + </abstract> + + <note title="Requirements Language"> + <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in <xref + target="RFC2119">RFC 2119</xref>.</t> + + <t/> + </note> + </front> + + <middle> + <section title="Introduction"> + <t>Benchmarking Methodology Working Group (BMWG) has traditionally + conducted laboratory characterization of dedicated physical + implementations of internetworking functions. The Black-box Benchmarks + of Throughput, Latency, Forwarding Rates and others have served our + industry for many years. Now, Network Function Virtualization (NFV) has + the goal to transform how internetwork functions are implemented, and + therefore has garnered much attention.</t> + + <t>This memo summarizes the progress of the Open Platform for NFV + (OPNFV) project on virtual switch performance characterization, + "VSWITCHPERF", through the Brahmaputra (second) release <xref + target="BrahRel"/>. This project intends to build on the current and + completed work of the Benchmarking Methodology Working Group in IETF, by + referencing existing literature. For example, currently the most often + referenced RFC is <xref target="RFC2544"/> (which depends on <xref + target="RFC1242"/>) and foundation of the benchmarking work in OPNFV is + common and strong.</t> + + <t>See + https://wiki.opnfv.org/characterize_vswitch_performance_for_telco_nfv_use_cases + for more background, and the OPNFV website for general information: + https://www.opnfv.org/</t> + + <t>The authors note that OPNFV distinguishes itself from other open + source compute and networking projects through its emphasis on existing + "telco" services as opposed to cloud-computing. There are many ways in + which telco requirements have different emphasis on performance + dimensions when compared to cloud computing: support for and transfer of + isochronous media streams is one example.</t> + + <t>Note also that the move to NFV Infrastructure has resulted in many + new benchmarking initiatives across the industry. The authors are + currently doing their best to maintain alignment with many other + projects, and this Internet Draft is one part of the efforts. We + acknowledge the early work in <xref + target="I-D.huang-bmwg-virtual-network-performance"/>, and useful + discussion with the authors.</t> + </section> + + <section title="Scope"> + <t>The primary purpose and scope of the memo is to inform the industry + of work-in-progress that builds on the body of extensive BMWG literature + and experience, and describe the extensions needed for benchmarking + virtual switches. Inital feedback indicates that many of these + extensions may be applicable beyond the current scope (to hardware + switches in the NFV Infrastructure and to virtual routers, for example). + Additionally, this memo serves as a vehicle to include more detail and + commentary from BMWG and other Open Source communities, under BMWG's + chartered work to characterize the NFV Infrastructure (a virtual switch + is an important aspect of that infrastructure).</t> + + <t>The benchmarking covered in this memo should be applicable to many + types of vswitches, and remain vswitch-agnostic to great degree. There + has been no attempt to track and test all features of any specific + vswitch implementation.</t> + </section> + + <section title="Benchmarking Considerations"> + <t>This section highlights some specific considerations (from <xref + target="I-D.ietf-bmwg-virtual-net"/>)related to Benchmarks for virtual + switches. The OPNFV project is sharing its present view on these areas, + as they develop their specifications in the Level Test Design (LTD) + document.</t> + + <section title="Comparison with Physical Network Functions"> + <t>To compare the performance of virtual designs and implementations + with their physical counterparts, identical benchmarks are needed. + BMWG has developed specifications for many network functions this memo + re-uses existing benchmarks through references, and expands them + during development of new methods. A key configuration aspect is the + number of parallel cores required to achieve comparable performance + with a given physical device, or whether some limit of scale was + reached before the cores could achieve the comparable level.</t> + + <t>It's unlikely that the virtual switch will be the only application + running on the SUT, so CPU utilization, Cache utilization, and Memory + footprint should also be recorded for the virtual implementations of + internetworking functions.</t> + </section> + + <section title="Continued Emphasis on Black-Box Benchmarks"> + <t>External observations remain essential as the basis for Benchmarks. + Internal observations with fixed specification and interpretation will + be provided in parallel to assist the development of operations + procedures when the technology is deployed.</t> + </section> + + <section title="New Configuration Parameters"> + <t>A key consideration when conducting any sort of benchmark is trying + to ensure the consistency and repeatability of test results. When + benchmarking the performance of a vSwitch there are many factors that + can affect the consistency of results, one key factor is matching the + various hardware and software details of the SUT. This section lists + some of the many new parameters which this project believes are + critical to report in order to achieve repeatability.</t> + + <t>Hardware details including:</t> + + <t><list style="symbols"> + <t>Platform details</t> + + <t>Processor details</t> + + <t>Memory information (type and size)</t> + + <t>Number of enabled cores</t> + + <t>Number of cores used for the test</t> + + <t>Number of physical NICs, as well as their details + (manufacturer, versions, type and the PCI slot they are plugged + into)</t> + + <t>NIC interrupt configuration</t> + + <t>BIOS version, release date and any configurations that were + modified</t> + + <t>CPU microcode level</t> + + <t>Memory DIMM configurations (quad rank performance may not be + the same as dual rank) in size, freq and slot locations</t> + + <t>PCI configuration parameters (payload size, early ack + option...)</t> + + <t>Power management at all levels (ACPI sleep states, processor + package, OS...)</t> + </list>Software details including:</t> + + <t><list style="symbols"> + <t>OS parameters and behavior (text vs graphical no one typing at + the console on one system)</t> + + <t>OS version (for host and VNF)</t> + + <t>Kernel version (for host and VNF)</t> + + <t>GRUB boot parameters (for host and VNF)</t> + + <t>Hypervisor details (Type and version)</t> + + <t>Selected vSwitch, version number or commit id used</t> + + <t>vSwitch launch command line if it has been parameterised</t> + + <t>Memory allocation to the vSwitch</t> + + <t>which NUMA node it is using, and how many memory channels</t> + + <t>DPDK or any other SW dependency version number or commit id + used</t> + + <t>Memory allocation to a VM - if it's from Hugpages/elsewhere</t> + + <t>VM storage type: snapshot/independent persistent/independent + non-persistent</t> + + <t>Number of VMs</t> + + <t>Number of Virtual NICs (vNICs), versions, type and driver</t> + + <t>Number of virtual CPUs and their core affinity on the host</t> + + <t>Number vNIC interrupt configuration</t> + + <t>Thread affinitization for the applications (including the + vSwitch itself) on the host</t> + + <t>Details of Resource isolation, such as CPUs designated for + Host/Kernel (isolcpu) and CPUs designated for specific processes + (taskset). - Test duration. - Number of flows.</t> + </list></t> + + <t>Test Traffic Information:<list style="symbols"> + <t>Traffic type - UDP, TCP, IMIX / Other</t> + + <t>Packet Sizes</t> + + <t>Deployment Scenario</t> + </list></t> + + <t/> + </section> + + <section title="Flow classification"> + <t>Virtual switches group packets into flows by processing and + matching particular packet or frame header information, or by matching + packets based on the input ports. Thus a flow can be thought of a + sequence of packets that have the same set of header field values + (5-tuple) or have arrived on the same port. Performance results can + vary based on the parameters the vSwitch uses to match for a flow. The + recommended flow classification parameters for any vSwitch performance + tests are: the input port, the source IP address, the destination IP + address and the Ethernet protocol type field. It is essential to + increase the flow timeout time on a vSwitch before conducting any + performance tests that do not measure the flow setup time. Normally + the first packet of a particular stream will install the flow in the + virtual switch which adds an additional latency, subsequent packets of + the same flow are not subject to this latency if the flow is already + installed on the vSwitch.</t> + </section> + + <section title="Benchmarks using Baselines with Resource Isolation"> + <t>This outline describes measurement of baseline with isolated + resources at a high level, which is the intended approach at this + time.</t> + + <t><list style="numbers"> + <t>Baselines: <list style="symbols"> + <t>Optional: Benchmark platform forwarding capability without + a vswitch or VNF for at least 72 hours (serves as a means of + platform validation and a means to obtain the base performance + for the platform in terms of its maximum forwarding rate and + latency). <figure> + <preamble>Benchmark platform forwarding + capability</preamble> + + <artwork align="right"><![CDATA[ __ + +--------------------------------------------------+ | + | +------------------------------------------+ | | + | | | | | + | | Simple Forwarding App | | Host + | | | | | + | +------------------------------------------+ | | + | | NIC | | | + +---+------------------------------------------+---+ __| + ^ : + | | + : v + +--------------------------------------------------+ + | | + | traffic generator | + | | + +--------------------------------------------------+]]></artwork> + + <postamble/> + </figure></t> + + <t>Benchmark VNF forwarding capability with direct + connectivity (vSwitch bypass, e.g., SR/IOV) for at least 72 + hours (serves as a means of VNF validation and a means to + obtain the base performance for the VNF in terms of its + maximum forwarding rate and latency). The metrics gathered + from this test will serve as a key comparison point for + vSwitch bypass technologies performance and vSwitch + performance. <figure align="right"> + <preamble>Benchmark VNF forwarding capability</preamble> + + <artwork><![CDATA[ __ + +--------------------------------------------------+ | + | +------------------------------------------+ | | + | | | | | + | | VNF | | | + | | | | | + | +------------------------------------------+ | | + | | Passthrough/SR-IOV | | Host + | +------------------------------------------+ | | + | | NIC | | | + +---+------------------------------------------+---+ __| + ^ : + | | + : v + +--------------------------------------------------+ + | | + | traffic generator | + | | + +--------------------------------------------------+]]></artwork> + + <postamble/> + </figure></t> + + <t>Benchmarking with isolated resources alone, with other + resources (both HW&SW) disabled Example, vSw and VM are + SUT</t> + + <t>Benchmarking with isolated resources alone, leaving some + resources unused</t> + + <t>Benchmark with isolated resources and all resources + occupied</t> + </list></t> + + <t>Next Steps<list style="symbols"> + <t>Limited sharing</t> + + <t>Production scenarios</t> + + <t>Stressful scenarios</t> + </list></t> + </list></t> + </section> + </section> + + <section title="VSWITCHPERF Specification Summary"> + <t>The overall specification in preparation is referred to as a Level + Test Design (LTD) document, which will contain a suite of performance + tests. The base performance tests in the LTD are based on the + pre-existing specifications developed by BMWG to test the performance of + physical switches. These specifications include:</t> + + <t><list style="symbols"> + <t><xref target="RFC2544"/> Benchmarking Methodology for Network + Interconnect Devices</t> + + <t><xref target="RFC2889"/> Benchmarking Methodology for LAN + Switching</t> + + <t><xref target="RFC6201"/> Device Reset Characterization</t> + + <t><xref target="RFC5481"/> Packet Delay Variation Applicability + Statement</t> + </list></t> + + <t>Some of the above/newer RFCs are being applied in benchmarking for + the first time, and represent a development challenge for test equipment + developers. Fortunately, many members of the testing system community + have engaged on the VSPERF project, including an open source test + system.</t> + + <t>In addition to this, the LTD also re-uses the terminology defined + by:</t> + + <t><list style="symbols"> + <t><xref target="RFC2285"/> Benchmarking Terminology for LAN + Switching Devices</t> + + <t><xref target="RFC5481"/> Packet Delay Variation Applicability + Statement</t> + </list></t> + + <t/> + + <t>Specifications to be included in future updates of the LTD + include:<list style="symbols"> + <t><xref target="RFC3918"/> Methodology for IP Multicast + Benchmarking</t> + + <t><xref target="RFC4737"/> Packet Reordering Metrics</t> + </list></t> + + <t>As one might expect, the most fundamental internetworking + characteristics of Throughput and Latency remain important when the + switch is virtualized, and these benchmarks figure prominently in the + specification.</t> + + <t>When considering characteristics important to "telco" network + functions, we must begin to consider additional performance metrics. In + this case, the project specifications have referenced metrics from the + IETF IP Performance Metrics (IPPM) literature. This means that the <xref + target="RFC2544"/> test of Latency is replaced by measurement of a + metric derived from IPPM's <xref target="RFC2679"/>, where a set of + statistical summaries will be provided (mean, max, min, etc.). Further + metrics planned to be benchmarked include packet delay variation as + defined by <xref target="RFC5481"/> , reordering, burst behaviour, DUT + availability, DUT capacity and packet loss in long term testing at + Throughput level, where some low-level of background loss may be present + and characterized.</t> + + <t>Tests have been (or will be) designed to collect the metrics + below:</t> + + <t><list style="symbols"> + <t>Throughput Tests to measure the maximum forwarding rate (in + frames per second or fps) and bit rate (in Mbps) for a constant load + (as defined by <xref target="RFC1242"/>) without traffic loss.</t> + + <t>Packet and Frame Delay Distribution Tests to measure average, min + and max packet and frame delay for constant loads.</t> + + <t>Packet Delay Tests to understand latency distribution for + different packet sizes and over an extended test run to uncover + outliers.</t> + + <t>Scalability Tests to understand how the virtual switch performs + as the number of flows, active ports, complexity of the forwarding + logic’s configuration… it has to deal with + increases.</t> + + <t>Stream Performance Tests (TCP, UDP) to measure bulk data transfer + performance, i.e. how fast systems can send and receive data through + the switch.</t> + + <t>Control Path and Datapath Coupling Tests, to understand how + closely coupled the datapath and the control path are as well as the + effect of this coupling on the performance of the DUT (example: + delay of the initial packet of a flow).</t> + + <t>CPU and Memory Consumption Tests to understand the virtual + switch’s footprint on the system, usually conducted as + auxiliary measurements with benchmarks above. They include: CPU + utilization, Cache utilization and Memory footprint.</t> + + <t>The so-called "Soak" tests, where the selected test is conducted + over a long period of time (with an ideal duration of 24 hours, but + only long enough to determine that stability issues exist when + found; there is no requirement to continue a test when a DUT + exhibits instability over time). The key performance characteristics + and benchmarks for a DUT are determined (using short duration tests) + prior to conducting soak tests. The purpose of soak tests is to + capture transient changes in performance which may occur due to + infrequent processes, memory leaks, or the low probability + coincidence of two or more processes. The stability of the DUT is + the paramount consideration, so performance must be evaluated + periodically during continuous testing, and this results in use of + <xref target="RFC2889"/> Frame Rate metrics instead of <xref + target="RFC2544"/> Throughput (which requires stopping traffic to + allow time for all traffic to exit internal queues), for + example.</t> + </list></t> + + <t>Future/planned test specs include:<list style="symbols"> + <t>Request/Response Performance Tests (TCP, UDP) which measure the + transaction rate through the switch.</t> + + <t>Noisy Neighbour Tests, to understand the effects of resource + sharing on the performance of a virtual switch.</t> + + <t>Tests derived from examination of ETSI NFV Draft GS IFA003 + requirements <xref target="IFA003"/> on characterization of + acceleration technologies applied to vswitches.</t> + </list>The flexibility of deployment of a virtual switch within a + network means that the BMWG IETF existing literature needs to be used to + characterize the performance of a switch in various deployment + scenarios. The deployment scenarios under consideration include:</t> + + <t><figure> + <preamble>Physical port to virtual switch to physical + port</preamble> + + <artwork><![CDATA[ __ + +--------------------------------------------------+ | + | +--------------------+ | | + | | | | | + | | v | | Host + | +--------------+ +--------------+ | | + | | phy port | vSwitch | phy port | | | + +---+--------------+------------+--------------+---+ __| + ^ : + | | + : v + +--------------------------------------------------+ + | | + | traffic generator | + | | + +--------------------------------------------------+]]></artwork> + </figure></t> + + <t><figure> + <preamble>Physical port to virtual switch to VNF to virtual switch + to physical port</preamble> + + <artwork><![CDATA[ __ + +---------------------------------------------------+ | + | | | + | +-------------------------------------------+ | | + | | Application | | | + | +-------------------------------------------+ | | + | ^ : | | + | | | | | Guest + | : v | | + | +---------------+ +---------------+ | | + | | logical port 0| | logical port 1| | | + +---+---------------+-----------+---------------+---+ __| + ^ : + | | + : v __ + +---+---------------+----------+---------------+---+ | + | | logical port 0| | logical port 1| | | + | +---------------+ +---------------+ | | + | ^ : | | + | | | | | Host + | : v | | + | +--------------+ +--------------+ | | + | | phy port | vSwitch | phy port | | | + +---+--------------+------------+--------------+---+ __| + ^ : + | | + : v + +--------------------------------------------------+ + | | + | traffic generator | + | | + +--------------------------------------------------+]]></artwork> + </figure><figure> + <preamble>Physical port to virtual switch to VNF to virtual switch + to VNF to virtual switch to physical port</preamble> + + <artwork><![CDATA[ __ + +----------------------+ +----------------------+ | + | Guest 1 | | Guest 2 | | + | +---------------+ | | +---------------+ | | + | | Application | | | | Application | | | + | +---------------+ | | +---------------+ | | + | ^ | | | ^ | | | + | | v | | | v | | Guests + | +---------------+ | | +---------------+ | | + | | logical ports | | | | logical ports | | | + | | 0 1 | | | | 0 1 | | | + +---+---------------+--+ +---+---------------+--+__| + ^ : ^ : + | | | | + : v : v _ + +---+---------------+---------+---------------+--+ | + | | 0 1 | | 3 4 | | | + | | logical ports | | logical ports | | | + | +---------------+ +---------------+ | | + | ^ | ^ | | | Host + | | |-----------------| v | | + | +--------------+ +--------------+ | | + | | phy ports | vSwitch | phy ports | | | + +---+--------------+----------+--------------+---+_| + ^ : + | | + : v + +--------------------------------------------------+ + | | + | traffic generator | + | | + +--------------------------------------------------+]]></artwork> + </figure><figure> + <preamble>Physical port to virtual switch to VNF</preamble> + + <artwork><![CDATA[ __ + +---------------------------------------------------+ | + | | | + | +-------------------------------------------+ | | + | | Application | | | + | +-------------------------------------------+ | | + | ^ | | + | | | | Guest + | : | | + | +---------------+ | | + | | logical port 0| | | + +---+---------------+-------------------------------+ __| + ^ + | + : __ + +---+---------------+------------------------------+ | + | | logical port 0| | | + | +---------------+ | | + | ^ | | + | | | | Host + | : | | + | +--------------+ | | + | | phy port | vSwitch | | + +---+--------------+------------ -------------- ---+ __| + ^ + | + : + +--------------------------------------------------+ + | | + | traffic generator | + | | + +--------------------------------------------------+]]></artwork> + </figure><figure> + <preamble>VNF to virtual switch to physical port</preamble> + + <artwork><![CDATA[ __ + +---------------------------------------------------+ | + | | | + | +-------------------------------------------+ | | + | | Application | | | + | +-------------------------------------------+ | | + | : | | + | | | | Guest + | v | | + | +---------------+ | | + | | logical port | | | + +-------------------------------+---------------+---+ __| + : + | + v __ + +------------------------------+---------------+---+ | + | | logical port | | | + | +---------------+ | | + | : | | + | | | | Host + | v | | + | +--------------+ | | + | vSwitch | phy port | | | + +-------------------------------+--------------+---+ __| + : + | + v + +--------------------------------------------------+ + | | + | traffic generator | + | | + +--------------------------------------------------+]]></artwork> + </figure><figure> + <preamble>VNF to virtual switch to VNF</preamble> + + <artwork><![CDATA[ __ + +----------------------+ +----------------------+ | + | Guest 1 | | Guest 2 | | + | +---------------+ | | +---------------+ | | + | | Application | | | | Application | | | + | +---------------+ | | +---------------+ | | + | | | | ^ | | + | v | | | | | Guests + | +---------------+ | | +---------------+ | | + | | logical ports | | | | logical ports | | | + | | 0 | | | | 0 | | | + +---+---------------+--+ +---+---------------+--+__| + : ^ + | | + v : _ + +---+---------------+---------+---------------+--+ | + | | 1 | | 1 | | | + | | logical ports | | logical ports | | | + | +---------------+ +---------------+ | | + | | ^ | | Host + | L-----------------+ | | + | | | + | vSwitch | | + +------------------------------------------------+_|]]></artwork> + </figure></t> + + <t>A set of Deployment Scenario figures is available on the VSPERF Test + Methodology Wiki page <xref target="TestTopo"/>.</t> + </section> + + <section title="3x3 Matrix Coverage"> + <t>This section organizes the many existing test specifications into the + "3x3" matrix (introduced in <xref target="I-D.ietf-bmwg-virtual-net"/>). + Because the LTD specification ID names are quite long, this section is + organized into lists for each occupied cell of the matrix (not all are + occupied, also the matrix has grown to 3x4 to accommodate scale metrics + when displaying the coverage of many metrics/benchmarks). The current + version of the LTD specification is available <xref target="LTD"/>.</t> + + <t>The tests listed below assess the activation of paths in the data + plane, rather than the control plane.</t> + + <t>A complete list of tests with short summaries is available on the + VSPERF "LTD Test Spec Overview" Wiki page <xref target="LTDoverV"/>.</t> + + <section title="Speed of Activation"> + <t><list style="symbols"> + <t>Activation.RFC2889.AddressLearningRate</t> + + <t>PacketLatency.InitialPacketProcessingLatency</t> + </list></t> + </section> + + <section title="Accuracy of Activation section"> + <t><list style="symbols"> + <t>CPDP.Coupling.Flow.Addition</t> + </list></t> + </section> + + <section title="Reliability of Activation"> + <t><list style="symbols"> + <t>Throughput.RFC2544.SystemRecoveryTime</t> + + <t>Throughput.RFC2544.ResetTime</t> + </list></t> + </section> + + <section title="Scale of Activation"> + <t><list style="symbols"> + <t>Activation.RFC2889.AddressCachingCapacity</t> + </list></t> + </section> + + <section title="Speed of Operation"> + <t><list style="symbols"> + <t>Throughput.RFC2544.PacketLossRate</t> + + <t>CPU.RFC2544.0PacketLoss</t> + + <t>Throughput.RFC2544.PacketLossRateFrameModification</t> + + <t>Throughput.RFC2544.BackToBackFrames</t> + + <t>Throughput.RFC2889.MaxForwardingRate</t> + + <t>Throughput.RFC2889.ForwardPressure</t> + + <t>Throughput.RFC2889.BroadcastFrameForwarding</t> + </list></t> + </section> + + <section title="Accuracy of Operation"> + <t><list style="symbols"> + <t>Throughput.RFC2889.ErrorFramesFiltering</t> + + <t>Throughput.RFC2544.Profile</t> + </list></t> + </section> + + <section title="Reliability of Operation"> + <t><list style="symbols"> + <t>Throughput.RFC2889.Soak</t> + + <t>Throughput.RFC2889.SoakFrameModification</t> + + <t>PacketDelayVariation.RFC3393.Soak</t> + </list></t> + </section> + + <section title="Scalability of Operation"> + <t><list style="symbols"> + <t>Scalability.RFC2544.0PacketLoss</t> + + <t>MemoryBandwidth.RFC2544.0PacketLoss.Scalability</t> + </list></t> + </section> + + <section title="Summary"> + <t><figure> + <artwork><![CDATA[|------------------------------------------------------------------------| +| | | | | | +| | SPEED | ACCURACY | RELIABILITY | SCALE | +| | | | | | +|------------------------------------------------------------------------| +| | | | | | +| Activation | X | X | X | X | +| | | | | | +|------------------------------------------------------------------------| +| | | | | | +| Operation | X | X | X | X | +| | | | | | +|------------------------------------------------------------------------| +| | | | | | +| De-activation | | | | | +| | | | | | +|------------------------------------------------------------------------|]]></artwork> + </figure></t> + </section> + </section> + + <section title="Security Considerations"> + <t>Benchmarking activities as described in this memo are limited to + technology characterization of a Device Under Test/System Under Test + (DUT/SUT) using controlled stimuli in a laboratory environment, with + dedicated address space and the constraints specified in the sections + above.</t> + + <t>The benchmarking network topology will be an independent test setup + and MUST NOT be connected to devices that may forward the test traffic + into a production network, or misroute traffic to the test management + network.</t> + + <t>Further, benchmarking is performed on a "black-box" basis, relying + solely on measurements observable external to the DUT/SUT.</t> + + <t>Special capabilities SHOULD NOT exist in the DUT/SUT specifically for + benchmarking purposes. Any implications for network security arising + from the DUT/SUT SHOULD be identical in the lab and in production + networks.</t> + </section> + + <section anchor="IANA" title="IANA Considerations"> + <t>No IANA Action is requested at this time.</t> + </section> + + <section title="Acknowledgements"> + <t>The authors appreciate and acknowledge comments from Scott Bradner, + Marius Georgescu, Ramki Krishnan, Doug Montgomery, Martin Klozik, + Christian Trautman, and others for their reviews.</t> + </section> + </middle> + + <back> + <references title="Normative References"> + <?rfc ?> + + <?rfc include="reference.RFC.2119"?> + + <?rfc ?> + + <?rfc include="reference.RFC.2330"?> + + <?rfc include='reference.RFC.2544'?> + + <?rfc include="reference.RFC.2679"?> + + <?rfc include='reference.RFC.2680'?> + + <?rfc include='reference.RFC.3393'?> + + <?rfc include='reference.RFC.3432'?> + + <?rfc include='reference.RFC.2681'?> + + <?rfc include='reference.RFC.5905'?> + + <?rfc include='reference.RFC.4689'?> + + <?rfc include='reference.RFC.4737'?> + + <?rfc include='reference.RFC.5357'?> + + <?rfc include='reference.RFC.2889'?> + + <?rfc include='reference.RFC.3918'?> + + <?rfc include='reference.RFC.6201'?> + + <?rfc include='reference.RFC.2285'?> + + <reference anchor="NFV.PER001"> + <front> + <title>Network Function Virtualization: Performance and Portability + Best Practices</title> + + <author fullname="ETSI NFV" initials="" surname=""> + <organization/> + </author> + + <date month="June" year="2014"/> + </front> + + <seriesInfo name="Group Specification" + value="ETSI GS NFV-PER 001 V1.1.1 (2014-06)"/> + + <format type="PDF"/> + </reference> + </references> + + <references title="Informative References"> + <?rfc include='reference.RFC.1242'?> + + <?rfc include='reference.RFC.5481'?> + + <?rfc include='reference.RFC.6049'?> + + <?rfc include='reference.RFC.6248'?> + + <?rfc include='reference.RFC.6390'?> + + <?rfc include='reference.I-D.ietf-bmwg-virtual-net'?> + + <?rfc include='reference.I-D.huang-bmwg-virtual-network-performance'?> + + <reference anchor="TestTopo"> + <front> + <title>Test Topologies + https://wiki.opnfv.org/vsperf/test_methodology</title> + + <author> + <organization/> + </author> + + <date/> + </front> + </reference> + + <reference anchor="LTDoverV"> + <front> + <title>LTD Test Spec Overview + https://wiki.opnfv.org/wiki/vswitchperf_test_spec_review</title> + + <author> + <organization/> + </author> + + <date/> + </front> + </reference> + + <reference anchor="LTD"> + <front> + <title>LTD Test Specification + http://artifacts.opnfv.org/vswitchperf/brahmaputra/docs/requirements/index.html</title> + + <author> + <organization/> + </author> + + <date/> + </front> + </reference> + + <reference anchor="BrahRel"> + <front> + <title>Brahmaputra, Second OPNFV Release + https://www.opnfv.org/brahmaputra</title> + + <author> + <organization/> + </author> + + <date/> + </front> + </reference> + + <reference anchor="IFA003"> + <front> + <title>https://docbox.etsi.org/ISG/NFV/Open/Drafts/IFA003_Acceleration_-_vSwitch_Spec/</title> + + <author> + <organization/> + </author> + + <date/> + </front> + </reference> + </references> + </back> +</rfc> diff --git a/docs/requirements/vswitchperf_ltp.rst b/docs/requirements/vswitchperf_ltp.rst index 6b2ee9bc..14303de5 100644 --- a/docs/requirements/vswitchperf_ltp.rst +++ b/docs/requirements/vswitchperf_ltp.rst @@ -1304,7 +1304,7 @@ vsperf CI jobs are broken down into: * Runs everyday takes about 10 hours to complete. * TESTCASES_DAILY='phy2phy_tput back2back phy2phy_tput_mod_vlan phy2phy_scalability pvp_tput pvp_back2back pvvp_tput pvvp_back2back'. - * TESTPARAM_DAILY='--test-params pkt_sizes=64,128,512,1024,1518'. + * TESTPARAM_DAILY='--test-params TRAFFICGEN_PKT_SIZES=(64,128,512,1024,1518)'. * Merge job: diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 1a796dbf..a1cce262 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -11,5 +11,6 @@ VSPERF User Guide :maxdepth: 3 testusage.rst + teststeps.rst integration.rst yardstick.rst diff --git a/docs/userguide/integration.rst b/docs/userguide/integration.rst index ceb11635..003e8adb 100755 --- a/docs/userguide/integration.rst +++ b/docs/userguide/integration.rst @@ -33,579 +33,6 @@ view the current test list simply execute the following command: The standard tests included are defined inside the ``conf/integration/01_testcases.conf`` file. -Test Steps ----------- - -Execution of integration tests are done on a step by step work flow starting -with step 0 as defined inside the test case. Each step of the test increments -the step number by one which is indicated in the log. - -.. code-block:: console - - (testcases.integration) - Step 1 - 'vswitch add_switch ['int_br1']' ... OK - -Each step in the test case is validated. If a step does not pass validation the -test will fail and terminate. The test will continue until a failure is detected -or all steps pass. A csv report file is generated after a test completes with an -OK or FAIL result. - -Test objects and their functions --------------------------------- - -Every test step can call a function of one of the supported test objects. The list -of supported objects and their most common functions follows: - - * ``vswitch`` - provides functions for vSwitch configuration - - List of supported functions: - - * ``add_switch br_name`` - creates a new switch (bridge) with given ``br_name`` - * ``del_switch br_name`` - deletes switch (bridge) with given ``br_name`` - * ``add_phy_port br_name`` - adds a physical port into bridge specified by ``br_name`` - * ``add_vport br_name`` - adds a virtual port into bridge specified by ``br_name`` - * ``del_port br_name port_name`` - removes physical or virtual port specified by - ``port_name`` from bridge ``br_name`` - * ``add_flow br_name flow`` - adds flow specified by ``flow`` dictionary into - the bridge ``br_name``; Content of flow dictionary will be passed to the vSwitch. - In case of Open vSwitch it will be passed to the ``ovs-ofctl add-flow`` command. - Please see Open vSwitch documentation for the list of supported flow parameters. - * ``del_flow br_name [flow]`` - deletes flow specified by ``flow`` dictionary from - bridge ``br_name``; In case that optional parameter ``flow`` is not specified - or set to an empty dictionary ``{}``, then all flows from bridge ``br_name`` - will be deleted. - * ``dump_flows br_name`` - dumps all flows from bridge specified by ``br_name`` - * ``enable_stp br_name`` - enables Spanning Tree Protocol for bridge ``br_name`` - * ``disable_stp br_name`` - disables Spanning Tree Protocol for bridge ``br_name`` - * ``enable_rstp br_name`` - enables Rapid Spanning Tree Protocol for bridge ``br_name`` - * ``disable_rstp br_name`` - disables Rapid Spanning Tree Protocol for bridge ``br_name`` - - Examples: - - .. code-block:: python - - ['vswitch', 'add_switch', 'int_br0'] - - ['vswitch', 'del_switch', 'int_br0'] - - ['vswitch', 'add_phy_port', 'int_br0'] - - ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'] - - ['vswitch', 'add_flow', 'int_br0', {'in_port': '1', 'actions': ['output:2'], - 'idle_timeout': '0'}], - - ['vswitch', 'enable_rstp', 'int_br0'] - - * ``vnf[ID]`` - provides functions for deployment and termination of VNFs; Optional - alfanumerical ``ID`` is used for VNF identification in case that testcase - deploys multiple VNFs. - - List of supported functions: - - * ``start`` - starts a VNF based on VSPERF configuration - * ``stop`` - gracefully terminates given VNF - - Examples: - - .. code-block:: python - - ['vnf1', 'start'] - ['vnf2', 'start'] - ['vnf2', 'stop'] - ['vnf1', 'stop'] - - * ``trafficgen`` - triggers traffic generation - - List of supported functions: - - * ``send_traffic traffic`` - starts a traffic based on the vsperf configuration - and given ``traffic`` dictionary. More details about ``traffic`` dictionary - and its possible values are available at `Traffic Generator Integration Guide - <http://artifacts.opnfv.org/vswitchperf/docs/design/trafficgen_integration_guide.html#step-5-supported-traffic-types>`__ - - Examples: - - .. code-block:: python - - ['trafficgen', 'send_traffic', {'traffic_type' : 'throughput'}] - - ['trafficgen', 'send_traffic', {'traffic_type' : 'back2back', 'bidir' : 'True'}] - - * ``settings`` - reads or modifies VSPERF configuration - - List of supported functions: - - * ``getValue param`` - returns value of given ``param`` - * ``setValue param value`` - sets value of ``param`` to given ``value`` - - Examples: - - .. code-block:: python - - ['settings', 'getValue', 'TOOLS'] - - ['settings', 'setValue', 'GUEST_USERNAME', ['root']] - - * ``namespace`` - creates or modifies network namespaces - - List of supported functions: - - * ``create_namespace name`` - creates new namespace with given ``name`` - * ``delete_namespace name`` - deletes namespace specified by its ``name`` - * ``assign_port_to_namespace port name [port_up]`` - assigns NIC specified by ``port`` - into given namespace ``name``; If optional parameter ``port_up`` is set to ``True``, - then port will be brought up. - * ``add_ip_to_namespace_eth port name addr cidr`` - assigns an IP address ``addr``/``cidr`` - to the NIC specified by ``port`` within namespace ``name`` - * ``reset_port_to_root port name`` - returns given ``port`` from namespace ``name`` back - to the root namespace - - Examples: - - .. code-block:: python - - ['namespace', 'create_namespace', 'testns'] - - ['namespace', 'assign_port_to_namespace', 'eth0', 'testns'] - - * ``veth`` - manipulates with eth and veth devices - - List of supported functions: - - * ``add_veth_port port peer_port`` - adds a pair of veth ports named ``port`` and - ``peer_port`` - * ``del_veth_port port peer_port`` - deletes a veth port pair specified by ``port`` - and ``peer_port`` - * ``bring_up_eth_port eth_port [namespace]`` - brings up ``eth_port`` in (optional) - ``namespace`` - - Examples: - - .. code-block:: python - - ['veth', 'add_veth_port', 'veth', 'veth1'] - - ['veth', 'bring_up_eth_port', 'eth1'] - - * ``tools`` - provides a set of helper functions - - List of supported functions: - - * ``Assert condition`` - evaluates given ``condition`` and raises ``AssertionError`` - in case that condition is not ``True`` - * ``Eval expression`` - evaluates given expression as a python code and returns - its result - * ``Exec command [regex]`` - executes a shell command and filters its output by - (optional) regular expression - - Examples: - - .. code-block:: python - - ['tools', 'exec', 'numactl -H', 'available: ([0-9]+)'] - ['tools', 'assert', '#STEP[-1][0]>1'] - - * ``wait`` - is used for test case interruption. This object doesn't have - any functions. Once reached, vsperf will pause test execution and waits - for press of ``Enter key``. It can be used during testcase design - for debugging purposes. - - Examples: - - .. code-block:: python - - ['wait'] - -Test Macros ------------ - -Test profiles can include macros as part of the test step. Each step in the -profile may return a value such as a port name. Recall macros use #STEP to -indicate the recalled value inside the return structure. If the method the -test step calls returns a value it can be later recalled, for example: - -.. code-block:: python - - { - "Name": "vswitch_add_del_vport", - "Deployment": "clean", - "Description": "vSwitch - add and delete virtual port", - "TestSteps": [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_vport', 'int_br0'], # STEP 1 - ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], # STEP 2 - ['vswitch', 'del_switch', 'int_br0'], # STEP 3 - ] - } - -This test profile uses the vswitch add_vport method which returns a string -value of the port added. This is later called by the del_port method using the -name from step 1. - -It is also possible to use negative indexes in step macros. In that case -``#STEP[-1]`` will refer to the result from previous step, ``#STEP[-2]`` -will refer to result of step called before previous step, etc. It means, -that you could change ``STEP 2`` from previous example to achieve the same -functionality: - -.. code-block:: python - - ['vswitch', 'del_port', 'int_br0', '#STEP[-1][0]'], # STEP 2 - -Also commonly used steps can be created as a separate profile. - -.. code-block:: python - - STEP_VSWITCH_PVP_INIT = [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 - ['vswitch', 'add_vport', 'int_br0'], # STEP 3 - ['vswitch', 'add_vport', 'int_br0'], # STEP 4 - ] - -This profile can then be used inside other testcases - -.. code-block:: python - - { - "Name": "vswitch_pvp", - "Deployment": "clean", - "Description": "vSwitch - configure switch and one vnf", - "TestSteps": STEP_VSWITCH_PVP_INIT + - [ - ['vnf', 'start'], - ['vnf', 'stop'], - ] + - STEP_VSWITCH_PVP_FINIT - } - -HelloWorld and other basic Testcases ------------------------------------- - -The following examples are for demonstration purposes. -You can run them by copying and pasting into the -conf/integration/01_testcases.conf file. -A command-line instruction is shown at the end of each -example. - -HelloWorld -^^^^^^^^^^ - -The first example is a HelloWorld testcase. -It simply creates a bridge with 2 physical ports, then sets up a flow to drop -incoming packets from the port that was instantiated at the STEP #1. -There's no interaction with the traffic generator. -Then the flow, the 2 ports and the bridge are deleted. -'add_phy_port' method creates a 'dpdk' type interface that will manage the -physical port. The string value returned is the port name that will be referred -by 'del_port' later on. - -.. code-block:: python - - { - "Name": "HelloWorld", - "Description": "My first testcase", - "Deployment": "clean", - "TestSteps": [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'actions': ['drop'], 'idle_timeout': '0'}], - ['vswitch', 'del_flow', 'int_br0'], - ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], - ['vswitch', 'del_switch', 'int_br0'], - ] - - } - -To run HelloWorld test: - - .. code-block:: console - - ./vsperf --conf-file user_settings.py --integration HelloWorld - -Specify a Flow by the IP address -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The next example shows how to explicitly set up a flow by specifying a -destination IP address. -All packets received from the port created at STEP #1 that have a destination -IP address = 90.90.90.90 will be forwarded to the port created at the STEP #2. - -.. code-block:: python - - { - "Name": "p2p_rule_l3da", - "Description": "Phy2Phy with rule on L3 Dest Addr", - "Deployment": "clean", - "biDirectional": "False", - "TestSteps": [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_dst': '90.90.90.90', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous'}], - ['vswitch', 'dump_flows', 'int_br0'], # STEP 5 - ['vswitch', 'del_flow', 'int_br0'], # STEP 7 == del-flows - ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], - ['vswitch', 'del_switch', 'int_br0'], - ] - }, - -To run the test: - - .. code-block:: console - - ./vsperf --conf-file user_settings.py --integration p2p_rule_l3da - -Multistream feature -^^^^^^^^^^^^^^^^^^^ - -The next testcase uses the multistream feature. -The traffic generator will send packets with different UDP ports. -That is accomplished by using "Stream Type" and "MultiStream" keywords. -4 different flows are set to forward all incoming packets. - -.. code-block:: python - - { - "Name": "multistream_l4", - "Description": "Multistream on UDP ports", - "Deployment": "clean", - "Stream Type": "L4", - "MultiStream": 4, - "TestSteps": [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 - # Setup Flows - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '0', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '1', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '2', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '3', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - # Send mono-dir traffic - ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous', \ - 'bidir' : 'False'}], - # Clean up - ['vswitch', 'del_flow', 'int_br0'], - ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], - ['vswitch', 'del_switch', 'int_br0'], - ] - }, - -To run the test: - - .. code-block:: console - - ./vsperf --conf-file user_settings.py --integration multistream_l4 - -PVP with a VM Replacement -^^^^^^^^^^^^^^^^^^^^^^^^^ - -This example launches a 1st VM in a PVP topology, then the VM is replaced -by another VM. -When VNF setup parameter in ./conf/04_vnf.conf is "QemuDpdkVhostUser" -'add_vport' method creates a 'dpdkvhostuser' type port to connect a VM. - -.. code-block:: python - - { - "Name": "ex_replace_vm", - "Description": "PVP with VM replacement", - "Deployment": "clean", - "TestSteps": [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 - ['vswitch', 'add_vport', 'int_br0'], # STEP 3 vm1 - ['vswitch', 'add_vport', 'int_br0'], # STEP 4 - - # Setup Flows - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[2][1]', \ - 'actions': ['output:#STEP[4][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[3][1]', \ - 'actions': ['output:#STEP[1][1]'], 'idle_timeout': '0'}], - - # Start VM 1 - ['vnf1', 'start'], - # Now we want to replace VM 1 with another VM - ['vnf1', 'stop'], - - ['vswitch', 'add_vport', 'int_br0'], # STEP 11 vm2 - ['vswitch', 'add_vport', 'int_br0'], # STEP 12 - ['vswitch', 'del_flow', 'int_br0'], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'actions': ['output:#STEP[11][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[12][1]', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - - # Start VM 2 - ['vnf2', 'start'], - ['vnf2', 'stop'], - ['vswitch', 'dump_flows', 'int_br0'], - - # Clean up - ['vswitch', 'del_flow', 'int_br0'], - ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'], # vm1 - ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[11][0]'], # vm2 - ['vswitch', 'del_port', 'int_br0', '#STEP[12][0]'], - ['vswitch', 'del_switch', 'int_br0'], - ] - }, - -To run the test: - - .. code-block:: console - - ./vsperf --conf-file user_settings.py --integration ex_replace_vm - -VM with a Linux bridge -^^^^^^^^^^^^^^^^^^^^^^ - -In this example a command-line parameter allows to set up a Linux bridge into -the guest VM. -That's one of the available ways to specify the guest application. -Packets matching the flow will be forwarded to the VM. - -.. code-block:: python - - { - "Name": "ex_pvp_rule_l3da", - "Description": "PVP with flow on L3 Dest Addr", - "Deployment": "clean", - "TestSteps": [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 - ['vswitch', 'add_vport', 'int_br0'], # STEP 3 vm1 - ['vswitch', 'add_vport', 'int_br0'], # STEP 4 - # Setup Flows - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_dst': '90.90.90.90', \ - 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], - # Each pkt from the VM is forwarded to the 2nd dpdk port - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - # Start VMs - ['vnf1', 'start'], - ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous', \ - 'bidir' : 'False'}], - ['vnf1', 'stop'], - # Clean up - ['vswitch', 'dump_flows', 'int_br0'], # STEP 10 - ['vswitch', 'del_flow', 'int_br0'], # STEP 11 - ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'], # vm1 ports - ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'], - ['vswitch', 'del_switch', 'int_br0'], - ] - }, - -To run the test: - - .. code-block:: console - - ./vsperf --conf-file user_settings.py --test-params - "guest_loopback=linux_bridge" --integration ex_pvp_rule_l3da - -Forward packets based on UDP port -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This examples launches 2 VMs connected in parallel. -Incoming packets will be forwarded to one specific VM depending on the -destination UDP port. - -.. code-block:: python - - { - "Name": "ex_2pvp_rule_l4dp", - "Description": "2 PVP with flows on L4 Dest Port", - "Deployment": "clean", - "Stream Type": "L4", # loop UDP ports - "MultiStream": 2, - "TestSteps": [ - ['vswitch', 'add_switch', 'int_br0'], # STEP 0 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 - ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 - ['vswitch', 'add_vport', 'int_br0'], # STEP 3 vm1 - ['vswitch', 'add_vport', 'int_br0'], # STEP 4 - ['vswitch', 'add_vport', 'int_br0'], # STEP 5 vm2 - ['vswitch', 'add_vport', 'int_br0'], # STEP 6 - # Setup Flows to reply ICMPv6 and similar packets, so to - # avoid flooding internal port with their re-transmissions - ['vswitch', 'add_flow', 'int_br0', \ - {'priority': '1', 'dl_src': '00:00:00:00:00:01', \ - 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', \ - {'priority': '1', 'dl_src': '00:00:00:00:00:02', \ - 'actions': ['output:#STEP[4][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', \ - {'priority': '1', 'dl_src': '00:00:00:00:00:03', \ - 'actions': ['output:#STEP[5][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', \ - {'priority': '1', 'dl_src': '00:00:00:00:00:04', \ - 'actions': ['output:#STEP[6][1]'], 'idle_timeout': '0'}], - # Forward UDP packets depending on dest port - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '0', \ - 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ - 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '1', \ - 'actions': ['output:#STEP[5][1]'], 'idle_timeout': '0'}], - # Send VM output to phy port #2 - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[6][1]', \ - 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], - # Start VMs - ['vnf1', 'start'], # STEP 16 - ['vnf2', 'start'], # STEP 17 - ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous', \ - 'bidir' : 'False'}], - ['vnf1', 'stop'], - ['vnf2', 'stop'], - ['vswitch', 'dump_flows', 'int_br0'], - # Clean up - ['vswitch', 'del_flow', 'int_br0'], - ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'], # vm1 ports - ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'], - ['vswitch', 'del_port', 'int_br0', '#STEP[5][0]'], # vm2 ports - ['vswitch', 'del_port', 'int_br0', '#STEP[6][0]'], - ['vswitch', 'del_switch', 'int_br0'], - ] - }, - -To run the test: - - .. code-block:: console - - ./vsperf --conf-file user_settings.py --integration ex_2pvp_rule_l4dp - Executing Tunnel encapsulation tests ------------------------------------ @@ -654,21 +81,21 @@ To run VXLAN encapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ --test-params 'tunnel_type=vxlan' overlay_p2p_tput To run GRE encapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ --test-params 'tunnel_type=gre' overlay_p2p_tput To run GENEVE encapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ --test-params 'tunnel_type=geneve' overlay_p2p_tput To run OVS NATIVE tunnel tests (VXLAN/GRE/GENEVE): @@ -700,7 +127,7 @@ To run OVS NATIVE tunnel tests (VXLAN/GRE/GENEVE): .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ --test-params 'tunnel_type=vxlan' overlay_p2p_tput @@ -762,7 +189,7 @@ To run GRE decapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --test-params 'tunnel_type=gre' + ./vsperf --conf-file user_settings.py --test-params 'tunnel_type=gre' \ --integration overlay_p2p_decap_cont @@ -801,7 +228,7 @@ To import the template do: 2. Click on the Traffic menu 3. Click on the Traffic actions and click Edit Packet Templates 4. On the Template editor window, click Import. Select the template - tools/pkt_gen/ixnet/GeneveIxNetTemplate.xml_ClearText.xml + located at ``3rd_party/ixia/GeneveIxNetTemplate.xml_ClearText.xml`` and click import. 5. Restart the TCL Server. @@ -819,7 +246,7 @@ To run GENEVE decapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --test-params 'tunnel_type=geneve' + ./vsperf --conf-file user_settings.py --test-params 'tunnel_type=geneve' \ --integration overlay_p2p_decap_cont @@ -903,7 +330,7 @@ To run VXLAN decapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ --test-params 'tunnel_type=vxlan' overlay_p2p_decap_cont Executing Native/Vanilla OVS GRE decapsulation tests @@ -962,7 +389,7 @@ To run GRE decapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ --test-params 'tunnel_type=gre' overlay_p2p_decap_cont Executing Native/Vanilla OVS GENEVE decapsulation tests @@ -1021,7 +448,7 @@ To run GENEVE decapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ --test-params 'tunnel_type=geneve' overlay_p2p_decap_cont @@ -1071,5 +498,5 @@ To run VXLAN encapsulation+decapsulation tests: .. code-block:: console - ./vsperf --conf-file user_settings.py --integration + ./vsperf --conf-file user_settings.py --integration \ overlay_p2p_mod_tput diff --git a/docs/userguide/teststeps.rst b/docs/userguide/teststeps.rst new file mode 100644 index 00000000..65a25b0a --- /dev/null +++ b/docs/userguide/teststeps.rst @@ -0,0 +1,651 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Intel Corporation, AT&T and others. + +Step driven tests +================= + +In general, test scenarios are defined by a ``deployment`` used in the particular +test case definition. The chosen deployment scenario will take care of the vSwitch +configuration, deployment of VNFs and it can also affect configuration of a traffic +generator. In order to allow a more flexible way of testcase scripting, VSPERF supports +a detailed step driven testcase definition. It can be used to configure and +program vSwitch, deploy and terminate VNFs, execute a traffic generator, +modify a VSPERF configuration, execute external commands, etc. + +Execution of step driven tests is done on a step by step work flow starting +with step 0 as defined inside the test case. Each step of the test increments +the step number by one which is indicated in the log. + +.. code-block:: console + + (testcases.integration) - Step 0 'vswitch add_vport ['br0']' start + +Step driven tests can be used for both performance and integration testing. +In case of integration test, each step in the test case is validated. If a step +does not pass validation the test will fail and terminate. The test will continue +until a failure is detected or all steps pass. A csv report file is generated after +a test completes with an OK or FAIL result. + +In case of performance test, the validation of steps is not performed and +standard output files with results from traffic generator and underlying OS +details are generated by vsperf. + +Step driven testcases can be used in two different ways: + + # description of full testcase - in this case ``clean`` deployment is used + to indicate that vsperf should neither configure vSwitch nor deploy any VNF. + Test shall perform all required vSwitch configuration and programming and + deploy required number of VNFs. + + # modification of existing deployment - in this case, any of supported + deployments can be used to perform initial vSwitch configuration and + deployment of VNFs. Additional actions defined by TestSteps can be used + to alter vSwitch configuration or deploy additional VNFs. After the last + step is processed, the test execution will continue with traffic execution. + +Test objects and their functions +-------------------------------- + +Every test step can call a function of one of the supported test objects. The list +of supported objects and their most common functions follows: + + * ``vswitch`` - provides functions for vSwitch configuration + + List of supported functions: + + * ``add_switch br_name`` - creates a new switch (bridge) with given ``br_name`` + * ``del_switch br_name`` - deletes switch (bridge) with given ``br_name`` + * ``add_phy_port br_name`` - adds a physical port into bridge specified by ``br_name`` + * ``add_vport br_name`` - adds a virtual port into bridge specified by ``br_name`` + * ``del_port br_name port_name`` - removes physical or virtual port specified by + ``port_name`` from bridge ``br_name`` + * ``add_flow br_name flow`` - adds flow specified by ``flow`` dictionary into + the bridge ``br_name``; Content of flow dictionary will be passed to the vSwitch. + In case of Open vSwitch it will be passed to the ``ovs-ofctl add-flow`` command. + Please see Open vSwitch documentation for the list of supported flow parameters. + * ``del_flow br_name [flow]`` - deletes flow specified by ``flow`` dictionary from + bridge ``br_name``; In case that optional parameter ``flow`` is not specified + or set to an empty dictionary ``{}``, then all flows from bridge ``br_name`` + will be deleted. + * ``dump_flows br_name`` - dumps all flows from bridge specified by ``br_name`` + * ``enable_stp br_name`` - enables Spanning Tree Protocol for bridge ``br_name`` + * ``disable_stp br_name`` - disables Spanning Tree Protocol for bridge ``br_name`` + * ``enable_rstp br_name`` - enables Rapid Spanning Tree Protocol for bridge ``br_name`` + * ``disable_rstp br_name`` - disables Rapid Spanning Tree Protocol for bridge ``br_name`` + + Examples: + + .. code-block:: python + + ['vswitch', 'add_switch', 'int_br0'] + + ['vswitch', 'del_switch', 'int_br0'] + + ['vswitch', 'add_phy_port', 'int_br0'] + + ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'] + + ['vswitch', 'add_flow', 'int_br0', {'in_port': '1', 'actions': ['output:2'], + 'idle_timeout': '0'}], + + ['vswitch', 'enable_rstp', 'int_br0'] + + * ``vnf[ID]`` - provides functions for deployment and termination of VNFs; Optional + alfanumerical ``ID`` is used for VNF identification in case that testcase + deploys multiple VNFs. + + List of supported functions: + + * ``start`` - starts a VNF based on VSPERF configuration + * ``stop`` - gracefully terminates given VNF + + Examples: + + .. code-block:: python + + ['vnf1', 'start'] + ['vnf2', 'start'] + ['vnf2', 'stop'] + ['vnf1', 'stop'] + + * ``trafficgen`` - triggers traffic generation + + List of supported functions: + + * ``send_traffic traffic`` - starts a traffic based on the vsperf configuration + and given ``traffic`` dictionary. More details about ``traffic`` dictionary + and its possible values are available at `Traffic Generator Integration Guide + <http://artifacts.opnfv.org/vswitchperf/docs/design/trafficgen_integration_guide.html#step-5-supported-traffic-types>`__ + + Examples: + + .. code-block:: python + + ['trafficgen', 'send_traffic', {'traffic_type' : 'throughput'}] + + ['trafficgen', 'send_traffic', {'traffic_type' : 'back2back', 'bidir' : 'True'}] + + * ``settings`` - reads or modifies VSPERF configuration + + List of supported functions: + + * ``getValue param`` - returns value of given ``param`` + * ``setValue param value`` - sets value of ``param`` to given ``value`` + + Examples: + + .. code-block:: python + + ['settings', 'getValue', 'TOOLS'] + + ['settings', 'setValue', 'GUEST_USERNAME', ['root']] + + * ``namespace`` - creates or modifies network namespaces + + List of supported functions: + + * ``create_namespace name`` - creates new namespace with given ``name`` + * ``delete_namespace name`` - deletes namespace specified by its ``name`` + * ``assign_port_to_namespace port name [port_up]`` - assigns NIC specified by ``port`` + into given namespace ``name``; If optional parameter ``port_up`` is set to ``True``, + then port will be brought up. + * ``add_ip_to_namespace_eth port name addr cidr`` - assigns an IP address ``addr``/``cidr`` + to the NIC specified by ``port`` within namespace ``name`` + * ``reset_port_to_root port name`` - returns given ``port`` from namespace ``name`` back + to the root namespace + + Examples: + + .. code-block:: python + + ['namespace', 'create_namespace', 'testns'] + + ['namespace', 'assign_port_to_namespace', 'eth0', 'testns'] + + * ``veth`` - manipulates with eth and veth devices + + List of supported functions: + + * ``add_veth_port port peer_port`` - adds a pair of veth ports named ``port`` and + ``peer_port`` + * ``del_veth_port port peer_port`` - deletes a veth port pair specified by ``port`` + and ``peer_port`` + * ``bring_up_eth_port eth_port [namespace]`` - brings up ``eth_port`` in (optional) + ``namespace`` + + Examples: + + .. code-block:: python + + ['veth', 'add_veth_port', 'veth', 'veth1'] + + ['veth', 'bring_up_eth_port', 'eth1'] + + * ``tools`` - provides a set of helper functions + + List of supported functions: + + * ``Assert condition`` - evaluates given ``condition`` and raises ``AssertionError`` + in case that condition is not ``True`` + * ``Eval expression`` - evaluates given expression as a python code and returns + its result + * ``Exec command [regex]`` - executes a shell command and filters its output by + (optional) regular expression + + Examples: + + .. code-block:: python + + ['tools', 'exec', 'numactl -H', 'available: ([0-9]+)'] + ['tools', 'assert', '#STEP[-1][0]>1'] + + * ``wait`` - is used for test case interruption. This object doesn't have + any functions. Once reached, vsperf will pause test execution and waits + for press of ``Enter key``. It can be used during testcase design + for debugging purposes. + + Examples: + + .. code-block:: python + + ['wait'] + +Test Macros +----------- + +Test profiles can include macros as part of the test step. Each step in the +profile may return a value such as a port name. Recall macros use #STEP to +indicate the recalled value inside the return structure. If the method the +test step calls returns a value it can be later recalled, for example: + +.. code-block:: python + + { + "Name": "vswitch_add_del_vport", + "Deployment": "clean", + "Description": "vSwitch - add and delete virtual port", + "TestSteps": [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_vport', 'int_br0'], # STEP 1 + ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], # STEP 2 + ['vswitch', 'del_switch', 'int_br0'], # STEP 3 + ] + } + +This test profile uses the vswitch add_vport method which returns a string +value of the port added. This is later called by the del_port method using the +name from step 1. + +It is also possible to use negative indexes in step macros. In that case +``#STEP[-1]`` will refer to the result from previous step, ``#STEP[-2]`` +will refer to result of step called before previous step, etc. It means, +that you could change ``STEP 2`` from previous example to achieve the same +functionality: + +.. code-block:: python + + ['vswitch', 'del_port', 'int_br0', '#STEP[-1][0]'], # STEP 2 + +Also commonly used steps can be created as a separate profile. + +.. code-block:: python + + STEP_VSWITCH_PVP_INIT = [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 + ['vswitch', 'add_vport', 'int_br0'], # STEP 3 + ['vswitch', 'add_vport', 'int_br0'], # STEP 4 + ] + +This profile can then be used inside other testcases + +.. code-block:: python + + { + "Name": "vswitch_pvp", + "Deployment": "clean", + "Description": "vSwitch - configure switch and one vnf", + "TestSteps": STEP_VSWITCH_PVP_INIT + + [ + ['vnf', 'start'], + ['vnf', 'stop'], + ] + + STEP_VSWITCH_PVP_FINIT + } + +HelloWorld and other basic Testcases +------------------------------------ + +The following examples are for demonstration purposes. +You can run them by copying and pasting into the +conf/integration/01_testcases.conf file. +A command-line instruction is shown at the end of each +example. + +HelloWorld +^^^^^^^^^^ + +The first example is a HelloWorld testcase. +It simply creates a bridge with 2 physical ports, then sets up a flow to drop +incoming packets from the port that was instantiated at the STEP #1. +There's no interaction with the traffic generator. +Then the flow, the 2 ports and the bridge are deleted. +'add_phy_port' method creates a 'dpdk' type interface that will manage the +physical port. The string value returned is the port name that will be referred +by 'del_port' later on. + +.. code-block:: python + + { + "Name": "HelloWorld", + "Description": "My first testcase", + "Deployment": "clean", + "TestSteps": [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'actions': ['drop'], 'idle_timeout': '0'}], + ['vswitch', 'del_flow', 'int_br0'], + ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], + ['vswitch', 'del_switch', 'int_br0'], + ] + + }, + +To run HelloWorld test: + + .. code-block:: console + + ./vsperf --conf-file user_settings.py --integration HelloWorld + +Specify a Flow by the IP address +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The next example shows how to explicitly set up a flow by specifying a +destination IP address. +All packets received from the port created at STEP #1 that have a destination +IP address = 90.90.90.90 will be forwarded to the port created at the STEP #2. + +.. code-block:: python + + { + "Name": "p2p_rule_l3da", + "Description": "Phy2Phy with rule on L3 Dest Addr", + "Deployment": "clean", + "biDirectional": "False", + "TestSteps": [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_dst': '90.90.90.90', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous'}], + ['vswitch', 'dump_flows', 'int_br0'], # STEP 5 + ['vswitch', 'del_flow', 'int_br0'], # STEP 7 == del-flows + ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], + ['vswitch', 'del_switch', 'int_br0'], + ] + }, + +To run the test: + + .. code-block:: console + + ./vsperf --conf-file user_settings.py --integration p2p_rule_l3da + +Multistream feature +^^^^^^^^^^^^^^^^^^^ + +The next testcase uses the multistream feature. +The traffic generator will send packets with different UDP ports. +That is accomplished by using "Stream Type" and "MultiStream" keywords. +4 different flows are set to forward all incoming packets. + +.. code-block:: python + + { + "Name": "multistream_l4", + "Description": "Multistream on UDP ports", + "Deployment": "clean", + "Stream Type": "L4", + "MultiStream": 4, + "TestSteps": [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 + # Setup Flows + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '0', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '1', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '2', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '3', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + # Send mono-dir traffic + ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous', \ + 'bidir' : 'False'}], + # Clean up + ['vswitch', 'del_flow', 'int_br0'], + ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], + ['vswitch', 'del_switch', 'int_br0'], + ] + }, + +To run the test: + + .. code-block:: console + + ./vsperf --conf-file user_settings.py --integration multistream_l4 + +PVP with a VM Replacement +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example launches a 1st VM in a PVP topology, then the VM is replaced +by another VM. +When VNF setup parameter in ./conf/04_vnf.conf is "QemuDpdkVhostUser" +'add_vport' method creates a 'dpdkvhostuser' type port to connect a VM. + +.. code-block:: python + + { + "Name": "ex_replace_vm", + "Description": "PVP with VM replacement", + "Deployment": "clean", + "TestSteps": [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 + ['vswitch', 'add_vport', 'int_br0'], # STEP 3 vm1 + ['vswitch', 'add_vport', 'int_br0'], # STEP 4 + + # Setup Flows + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[2][1]', \ + 'actions': ['output:#STEP[4][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[3][1]', \ + 'actions': ['output:#STEP[1][1]'], 'idle_timeout': '0'}], + + # Start VM 1 + ['vnf1', 'start'], + # Now we want to replace VM 1 with another VM + ['vnf1', 'stop'], + + ['vswitch', 'add_vport', 'int_br0'], # STEP 11 vm2 + ['vswitch', 'add_vport', 'int_br0'], # STEP 12 + ['vswitch', 'del_flow', 'int_br0'], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'actions': ['output:#STEP[11][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[12][1]', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + + # Start VM 2 + ['vnf2', 'start'], + ['vnf2', 'stop'], + ['vswitch', 'dump_flows', 'int_br0'], + + # Clean up + ['vswitch', 'del_flow', 'int_br0'], + ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'], # vm1 + ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[11][0]'], # vm2 + ['vswitch', 'del_port', 'int_br0', '#STEP[12][0]'], + ['vswitch', 'del_switch', 'int_br0'], + ] + }, + +To run the test: + + .. code-block:: console + + ./vsperf --conf-file user_settings.py --integration ex_replace_vm + +VM with a Linux bridge +^^^^^^^^^^^^^^^^^^^^^^ + +This example setups a PVP topology and routes traffic to the VM based on +the destination IP address. A command-line parameter is used to select a Linux +bridge as a guest loopback application. It is also possible to select a guest +loopback application by a configuration option ``GUEST_LOOPBACK``. + +.. code-block:: python + + { + "Name": "ex_pvp_rule_l3da", + "Description": "PVP with flow on L3 Dest Addr", + "Deployment": "clean", + "TestSteps": [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 + ['vswitch', 'add_vport', 'int_br0'], # STEP 3 vm1 + ['vswitch', 'add_vport', 'int_br0'], # STEP 4 + # Setup Flows + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_dst': '90.90.90.90', \ + 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], + # Each pkt from the VM is forwarded to the 2nd dpdk port + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + # Start VMs + ['vnf1', 'start'], + ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous', \ + 'bidir' : 'False'}], + ['vnf1', 'stop'], + # Clean up + ['vswitch', 'dump_flows', 'int_br0'], # STEP 10 + ['vswitch', 'del_flow', 'int_br0'], # STEP 11 + ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'], # vm1 ports + ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'], + ['vswitch', 'del_switch', 'int_br0'], + ] + }, + +To run the test: + + .. code-block:: console + + ./vsperf --conf-file user_settings.py --test-params \ + "GUEST_LOOPBACK=['linux_bridge']" --integration ex_pvp_rule_l3da + +Forward packets based on UDP port +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This examples launches 2 VMs connected in parallel. +Incoming packets will be forwarded to one specific VM depending on the +destination UDP port. + +.. code-block:: python + + { + "Name": "ex_2pvp_rule_l4dp", + "Description": "2 PVP with flows on L4 Dest Port", + "Deployment": "clean", + "Stream Type": "L4", # loop UDP ports + "MultiStream": 2, + "TestSteps": [ + ['vswitch', 'add_switch', 'int_br0'], # STEP 0 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 1 + ['vswitch', 'add_phy_port', 'int_br0'], # STEP 2 + ['vswitch', 'add_vport', 'int_br0'], # STEP 3 vm1 + ['vswitch', 'add_vport', 'int_br0'], # STEP 4 + ['vswitch', 'add_vport', 'int_br0'], # STEP 5 vm2 + ['vswitch', 'add_vport', 'int_br0'], # STEP 6 + # Setup Flows to reply ICMPv6 and similar packets, so to + # avoid flooding internal port with their re-transmissions + ['vswitch', 'add_flow', 'int_br0', \ + {'priority': '1', 'dl_src': '00:00:00:00:00:01', \ + 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', \ + {'priority': '1', 'dl_src': '00:00:00:00:00:02', \ + 'actions': ['output:#STEP[4][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', \ + {'priority': '1', 'dl_src': '00:00:00:00:00:03', \ + 'actions': ['output:#STEP[5][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', \ + {'priority': '1', 'dl_src': '00:00:00:00:00:04', \ + 'actions': ['output:#STEP[6][1]'], 'idle_timeout': '0'}], + # Forward UDP packets depending on dest port + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '0', \ + 'actions': ['output:#STEP[3][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[1][1]', \ + 'dl_type': '0x0800', 'nw_proto': '17', 'udp_dst': '1', \ + 'actions': ['output:#STEP[5][1]'], 'idle_timeout': '0'}], + # Send VM output to phy port #2 + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[4][1]', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'int_br0', {'in_port': '#STEP[6][1]', \ + 'actions': ['output:#STEP[2][1]'], 'idle_timeout': '0'}], + # Start VMs + ['vnf1', 'start'], # STEP 16 + ['vnf2', 'start'], # STEP 17 + ['trafficgen', 'send_traffic', {'traffic_type' : 'continuous', \ + 'bidir' : 'False'}], + ['vnf1', 'stop'], + ['vnf2', 'stop'], + ['vswitch', 'dump_flows', 'int_br0'], + # Clean up + ['vswitch', 'del_flow', 'int_br0'], + ['vswitch', 'del_port', 'int_br0', '#STEP[1][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[2][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[3][0]'], # vm1 ports + ['vswitch', 'del_port', 'int_br0', '#STEP[4][0]'], + ['vswitch', 'del_port', 'int_br0', '#STEP[5][0]'], # vm2 ports + ['vswitch', 'del_port', 'int_br0', '#STEP[6][0]'], + ['vswitch', 'del_switch', 'int_br0'], + ] + }, + +To run the test: + + .. code-block:: console + + ./vsperf --conf-file user_settings.py --integration ex_2pvp_rule_l4dp + +Modification of existing PVVP deployment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is an example of modification of a standard deployment scenario with additional TestSteps. +Standard PVVP scenario is used to configure a vSwitch and to deploy two VNFs connected +in series. Additional TestSteps will deploy a 3rd VNF and connect it in parallel to +already configured VNFs. Traffic generator is instructed (by Multistream feature) to send +two separate traffic streams. One stream will be sent to the standalone VNF and second +to two chained VNFs. + +In case, that test is defined as a performance test, then traffic results will be collected +and available in both csv and rst report files. + +.. code-block:: python + + { + "Name": "pvvp_pvp_cont", + "Traffic Type": "continuous", + "Deployment": "pvvp", + "Description": "PVVP and PVP in parallel with Continuous Stream", + "biDirectional": "True", + "iLoad": "100", + "MultiStream": "2", + "TestSteps": [ + ['vswitch', 'add_vport', 'br0'], + ['vswitch', 'add_vport', 'br0'], + # priority must be higher than default 32768, otherwise flows won't match + ['vswitch', 'add_flow', 'br0', + {'in_port': '1', 'actions': ['output:#STEP[-2][1]'], 'idle_timeout': '0', 'dl_type':'0x800', + 'nw_proto':'17', 'tp_dst':'0', 'priority': '33000'}], + ['vswitch', 'add_flow', 'br0', + {'in_port': '2', 'actions': ['output:#STEP[-2][1]'], 'idle_timeout': '0', 'dl_type':'0x800', + 'nw_proto':'17', 'tp_dst':'0', 'priority': '33000'}], + ['vswitch', 'add_flow', 'br0', {'in_port': '#STEP[-4][1]', 'actions': ['output:1'], + 'idle_timeout': '0'}], + ['vswitch', 'add_flow', 'br0', {'in_port': '#STEP[-4][1]', 'actions': ['output:2'], + 'idle_timeout': '0'}], + ['vswitch', 'dump_flows', 'br0'], + ['vnf1', 'start'], + ] + }, + +To run the test: + + .. code-block:: console + + ./vsperf --conf-file user_settings.py pvvp_pvp_cont + diff --git a/docs/userguide/testusage.rst b/docs/userguide/testusage.rst index 788f84a2..f446f261 100755 --- a/docs/userguide/testusage.rst +++ b/docs/userguide/testusage.rst @@ -105,14 +105,61 @@ or via another command line argument will override both the default and your custom configuration files. This "priority hierarchy" can be described like so (1 = max priority): -1. Command line arguments -2. Environment variables -3. Configuration file(s) +1. Testcase definition section ``Parameters`` +2. Command line arguments +3. Environment variables +4. Configuration file(s) Further details about configuration files evaluation and special behaviour of options with ``GUEST_`` prefix could be found at `design document <http://artifacts.opnfv.org/vswitchperf/docs/design/vswitchperf_design.html#configuration>`__. +Overriding values defined in configuration files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The configuration items can be overridden by command line argument +``--test-params``. In this case, the configuration items and +their values should be passed in form of ``item=value`` and separated +by semicolon. + +Example: + +.. code:: console + + $ ./vsperf --test-params "TRAFFICGEN_DURATION=10;TRAFFICGEN_PKT_SIZES=(128,);" \ + "GUEST_LOOPBACK=['testpmd','l2fwd']" pvvp_tput + +The second option is to override configuration items by ``Parameters`` section +of the test case definition. The configuration items can be added into ``Parameters`` +dictionary with their new values. These values will override values defined in +configuration files or specified by ``--test-params`` command line argument. + +Example: + +.. code:: python + + "Parameters" : {'TRAFFICGEN_PKT_SIZES' : (128,), + 'TRAFFICGEN_DURATION' : 10, + 'GUEST_LOOPBACK' : ['testpmd','l2fwd'], + } + +**NOTE:** In both cases, configuration item names and their values must be specified +in the same form as they are defined inside configuration files. Parameter names +must be specified in uppercase and data types of original and new value must match. +Python syntax rules related to data types and structures must be followed. +For example, parameter ``TRAFFICGEN_PKT_SIZES`` above is defined as a tuple +with a single value ``128``. In this case trailing comma is mandatory, otherwise +value can be wrongly interpreted as a number instead of a tuple and vsperf +execution would fail. Please check configuration files for default values and their +types and use them as a basis for any customized values. In case of any doubt, please +check official python documentation related to data structures like tuples, lists +and dictionaries. + +**NOTE:** Vsperf execution will terminate with runtime error in case, that unknown +parameter name is passed via ``--test-params`` CLI argument or defined in ``Parameters`` +section of test case definition. It is also forbidden to redefine a value of +``TEST_PARAMS`` configuration item via CLI or ``Parameters`` section. + vloop_vnf ^^^^^^^^^ @@ -131,6 +178,7 @@ installation instructions for information on these images vloop_vnf forwards traffic through a VM using one of: + * DPDK testpmd * Linux Bridge * l2fwd kernel Module. @@ -191,9 +239,9 @@ Some tests allow for configurable parameters, including test duration .. code:: bash - $ ./vsperf --conf-file user_settings.py - --tests RFC2544Tput - --test-params "duration=10;pkt_sizes=128" + $ ./vsperf --conf-file user_settings.py \ + --tests RFC2544Tput \ + --test-params "TRAFFICGEN_DURATION=10;TRAFFICGEN_PKT_SIZES=(128,)" For all available options, check out the help dialog: @@ -206,35 +254,30 @@ Executing Vanilla OVS tests 1. If needed, recompile src for all OVS variants -.. code-block:: console - - $ cd src - $ make distclean - $ make + .. code-block:: console -2. Update your ''10_custom.conf'' file to use the appropriate variables -for Vanilla OVS: + $ cd src + $ make distclean + $ make -.. code-block:: console +2. Update your ``10_custom.conf`` file to use Vanilla OVS: - VSWITCH = 'OvsVanilla' + .. code-block:: python -Where $PORT1 and $PORT2 are the Linux interfaces you'd like to bind -to the vswitch. + VSWITCH = 'OvsVanilla' 3. Run test: -.. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf> + $ ./vsperf --conf-file=<path_to_custom_conf> -Please note if you don't want to configure Vanilla OVS through the -configuration file, you can pass it as a CLI argument; BUT you must -set the ports. + Please note if you don't want to configure Vanilla OVS through the + configuration file, you can pass it as a CLI argument. -.. code-block:: console + .. code-block:: console - $ ./vsperf --vswitch OvsVanilla + $ ./vsperf --vswitch OvsVanilla Executing tests with VMs @@ -244,24 +287,24 @@ To run tests using vhost-user as guest access method: 1. Set VHOST_METHOD and VNF of your settings file to: -.. code-block:: console + .. code-block:: python - VSWITCH = 'OvsDpdkVhost' - VNF = 'QemuDpdkVhost' + VSWITCH = 'OvsDpdkVhost' + VNF = 'QemuDpdkVhost' 2. If needed, recompile src for all OVS variants -.. code-block:: console + .. code-block:: console - $ cd src - $ make distclean - $ make + $ cd src + $ make distclean + $ make 3. Run test: -.. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf Executing tests with VMs using Vanilla OVS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -270,39 +313,42 @@ To run tests using Vanilla OVS: 1. Set the following variables: -.. code-block:: console + .. code-block:: python - VSWITCH = 'OvsVanilla' - VNF = 'QemuVirtioNet' + VSWITCH = 'OvsVanilla' + VNF = 'QemuVirtioNet' - VANILLA_TGEN_PORT1_IP = n.n.n.n - VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn + VANILLA_TGEN_PORT1_IP = n.n.n.n + VANILLA_TGEN_PORT1_MAC = nn:nn:nn:nn:nn:nn - VANILLA_TGEN_PORT2_IP = n.n.n.n - VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn + VANILLA_TGEN_PORT2_IP = n.n.n.n + VANILLA_TGEN_PORT2_MAC = nn:nn:nn:nn:nn:nn - VANILLA_BRIDGE_IP = n.n.n.n + VANILLA_BRIDGE_IP = n.n.n.n - or use --test-param + or use ``--test-params`` option - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf - --test-params "vanilla_tgen_tx_ip=n.n.n.n; - vanilla_tgen_tx_mac=nn:nn:nn:nn:nn:nn" + .. code-block:: console + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ + --test-params "VANILLA_TGEN_PORT1_IP=n.n.n.n;" \ + "VANILLA_TGEN_PORT1_MAC=nn:nn:nn:nn:nn:nn;" \ + "VANILLA_TGEN_PORT2_IP=n.n.n.n;" \ + "VANILLA_TGEN_PORT2_MAC=nn:nn:nn:nn:nn:nn" 2. If needed, recompile src for all OVS variants -.. code-block:: console + .. code-block:: console - $ cd src - $ make distclean - $ make + $ cd src + $ make distclean + $ make 3. Run test: -.. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf + $ ./vsperf --conf-file<path_to_custom_conf>/10_custom.conf .. _vfio-pci: @@ -312,7 +358,7 @@ Using vfio_pci with DPDK To use vfio with DPDK instead of igb_uio add into your custom configuration file the following parameter: -.. code-block:: console +.. code-block:: python PATHS['dpdk']['src']['modules'] = ['uio', 'vfio-pci'] @@ -392,7 +438,7 @@ Execution of test with PCI passthrough with vswitch disabled: .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ --vswitch none --vnf QemuPciPassthrough pvp_tput Any of supported guest-loopback-application_ can be used inside VM with @@ -406,19 +452,19 @@ deployment. Selection of loopback application for tests with VMs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To select loopback application, which will perform traffic forwarding -inside VM, following configuration parameter should be configured: +To select the loopback applications which will forward packets inside VMs, +the following parameter should be configured: -.. code-block:: console +.. code-block:: python GUEST_LOOPBACK = ['testpmd'] -or use --test-param +or use ``--test-params`` CLI argument: .. code-block:: console - $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf - --test-params "guest_loopback=testpmd" + $ ./vsperf --conf-file=<path_to_custom_conf>/10_custom.conf \ + --test-params "GUEST_LOOPBACK=['testpmd']" Supported loopback applications are: @@ -434,37 +480,69 @@ Guest loopback application must be configured, otherwise traffic will not be forwarded by VM and testcases with VM related deployments will fail. Guest loopback application is set to 'testpmd' by default. -Note: In case that only 1 or more than 2 NICs are configured for VM, +**NOTE:** In case that only 1 or more than 2 NICs are configured for VM, then 'testpmd' should be used. As it is able to forward traffic between multiple VM NIC pairs. -Note: In case of linux_bridge, all guest NICs are connected to the same +**NOTE:** In case of linux_bridge, all guest NICs are connected to the same bridge inside the guest. +Selection of dpdk binding driver for tests with VMs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To select dpdk binding driver, which will specify which driver the vm NICs will +use for dpdk bind, the following configuration parameter should be configured: + +.. code-block:: console + + GUEST_DPDK_BIND_DRIVER = ['igb_uio_from_src'] + +The supported dpdk guest bind drivers are: + +.. code-block:: console + + 'uio_pci_generic' - Use uio_pci_generic driver + 'igb_uio_from_src' - Build and use the igb_uio driver from the dpdk src + files + 'vfio_no_iommu' - Use vfio with no iommu option. This requires custom + guest images that support this option. The default + vloop image does not support this driver. + +Note: uio_pci_generic does not support sr-iov testcases with guests attached. +This is because uio_pci_generic only supports legacy interrupts. In case +uio_pci_generic is selected with the vnf as QemuPciPassthrough it will be +modified to use igb_uio_from_src instead. + +Note: vfio_no_iommu requires kernels equal to or greater than 4.5 and dpdk +16.04 or greater. Using this option will also taint the kernel. + +Please refer to the dpdk documents at http://dpdk.org/doc/guides for more +information on these drivers. + Multi-Queue Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^ VSPerf currently supports multi-queue with the following limitations: - 1. Requires QEMU 2.5 or greater and any OVS version higher than 2.5. The - default upstream package versions installed by VSPerf satisfies this - requirement. +1. Requires QEMU 2.5 or greater and any OVS version higher than 2.5. The + default upstream package versions installed by VSPerf satisfies this + requirement. - 2. Guest image must have ethtool utility installed if using l2fwd or linux - bridge inside guest for loopback. +2. Guest image must have ethtool utility installed if using l2fwd or linux + bridge inside guest for loopback. - 3. If using OVS versions 2.5.0 or less enable old style multi-queue as shown - in the ''02_vswitch.conf'' file. +3. If using OVS versions 2.5.0 or less enable old style multi-queue as shown + in the ''02_vswitch.conf'' file. - .. code-block:: console + .. code-block:: python - OVS_OLD_STYLE_MQ = True + OVS_OLD_STYLE_MQ = True To enable multi-queue for dpdk modify the ''02_vswitch.conf'' file. - .. code-block:: console +.. code-block:: python - VSWITCH_DPDK_MULTI_QUEUES = 2 + VSWITCH_DPDK_MULTI_QUEUES = 2 **NOTE:** you should consider using the switch affinity to set a pmd cpu mask that can optimize your performance. Consider the numa of the NIC in use if this @@ -478,9 +556,9 @@ port by port option. To enable multi-queue on the guest modify the ''04_vnf.conf'' file. - .. code-block:: console +.. code-block:: python - GUEST_NIC_QUEUES = 2 + GUEST_NIC_QUEUES = [2] Enabling multi-queue at the guest will add multiple queues to each NIC port when qemu launches the guest. @@ -492,13 +570,12 @@ multi-queue on the guest is sufficient for Vanilla OVS multi-queue. Testpmd should be configured to take advantage of multi-queue on the guest if using DPDKVhostUser. This can be done by modifying the ''04_vnf.conf'' file. - .. code-block:: console - - GUEST_TESTPMD_CPU_MASK = '-l 0,1,2,3,4' +.. code-block:: python - GUEST_TESTPMD_NB_CORES = 4 - GUEST_TESTPMD_TXQ = 2 - GUEST_TESTPMD_RXQ = 2 + GUEST_TESTPMD_PARAMS = ['-l 0,1,2,3,4 -n 4 --socket-mem 512 -- ' + '--burst=64 -i --txqflags=0xf00 ' + '--nb-cores=4 --rxq=2 --txq=2 ' + '--disable-hw-vlan'] **NOTE:** The guest SMP cores must be configured to allow for testpmd to use the optimal number of cores to take advantage of the multiple guest queues. @@ -508,11 +585,11 @@ by binding vhost-net threads to cpus. This can be done by enabling the affinity in the ''04_vnf.conf'' file. This can be done to non multi-queue enabled configurations as well as there will be 2 vhost-net threads. - .. code-block:: console +.. code-block:: python - VSWITCH_VHOST_NET_AFFINITIZATION = True + VSWITCH_VHOST_NET_AFFINITIZATION = True - VSWITCH_VHOST_CPU_MAP = [4,5,8,11] + VSWITCH_VHOST_CPU_MAP = [4,5,8,11] **NOTE:** This method of binding would require a custom script in a real environment. @@ -521,66 +598,56 @@ environment. on the same numa as the NIC in use if possible/applicable. Testpmd should be assigned at least (nb_cores +1) total cores with the cpu mask. -The following CLI parameters override the corresponding configuration settings: - 1. guest_nic_queues, which overrides all GUEST_NIC_QUEUES values - 2. guest_testpmd_txq, which overrides all GUEST_TESTPMD_TXQ - 3. guest_testpmd_rxq, which overrides all GUEST_TESTPMD_RXQ - 4. guest_testpmd_nb_cores, which overrides all GUEST_TESTPMD_NB_CORES - values - 5. guest_testpmd_cpu_mask, which overrides all GUEST_TESTPMD_CPU_MASK - values - 6. vswitch_dpdk_multi_queues, which overrides VSWITCH_DPDK_MULTI_QUEUES - 7. guest_smp, which overrides all GUEST_SMP values - 8. guest_core_binding, which overrides all GUEST_CORE_BINDING values - Executing Packet Forwarding tests ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To select application, which will perform packet forwarding, -following configuration parameter should be configured: +To select the applications which will forward packets, +the following parameters should be configured: - .. code-block:: console +.. code-block:: python + + VSWITCH = 'none' + PKTFWD = 'TestPMD' - VSWITCH = 'none' - PKTFWD = 'TestPMD' +or use ``--vswitch`` and ``--fwdapp`` CLI arguments: - or use --vswitch and --fwdapp +.. code-block:: console - $ ./vsperf --conf-file user_settings.py - --vswitch none - --fwdapp TestPMD + $ ./vsperf --conf-file user_settings.py \ + --vswitch none \ + --fwdapp TestPMD Supported Packet Forwarding applications are: - .. code-block:: console +.. code-block:: console - 'testpmd' - testpmd from dpdk + 'testpmd' - testpmd from dpdk 1. Update your ''10_custom.conf'' file to use the appropriate variables -for selected Packet Forwarder: - - .. code-block:: console - - # testpmd configuration - TESTPMD_ARGS = [] - # packet forwarding mode supported by testpmd; Please see DPDK documentation - # for comprehensive list of modes supported by your version. - # e.g. io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho|... - # Note: Option "mac_retry" has been changed to "mac retry" since DPDK v16.07 - TESTPMD_FWD_MODE = 'csum' - # checksum calculation layer: ip|udp|tcp|sctp|outer-ip - TESTPMD_CSUM_LAYER = 'ip' - # checksum calculation place: hw (hardware) | sw (software) - TESTPMD_CSUM_CALC = 'sw' - # recognize tunnel headers: on|off - TESTPMD_CSUM_PARSE_TUNNEL = 'off' + for selected Packet Forwarder: + + .. code-block:: python + + # testpmd configuration + TESTPMD_ARGS = [] + # packet forwarding mode supported by testpmd; Please see DPDK documentation + # for comprehensive list of modes supported by your version. + # e.g. io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho|... + # Note: Option "mac_retry" has been changed to "mac retry" since DPDK v16.07 + TESTPMD_FWD_MODE = 'csum' + # checksum calculation layer: ip|udp|tcp|sctp|outer-ip + TESTPMD_CSUM_LAYER = 'ip' + # checksum calculation place: hw (hardware) | sw (software) + TESTPMD_CSUM_CALC = 'sw' + # recognize tunnel headers: on|off + TESTPMD_CSUM_PARSE_TUNNEL = 'off' 2. Run test: - .. code-block:: console + .. code-block:: console - $ ./vsperf --conf-file <path_to_settings_py> + $ ./vsperf --conf-file <path_to_settings_py> VSPERF modes of operation ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -602,7 +669,7 @@ Mode of operation is driven by configuration parameter -m or --mode "trafficgen-pause" - execute vSwitch and VNF but wait before traffic transmission In case, that VSPERF is executed in "trafficgen" mode, then configuration -of traffic generator should be configured through --test-params option. +of traffic generator should be configured through ``--test-params`` option. Supported CLI options useful for traffic generator configuration are: .. code-block:: console @@ -629,7 +696,7 @@ Example of execution of VSPERF in "trafficgen" mode: .. code-block:: console - $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf + $ ./vsperf -m trafficgen --trafficgen IxNet --conf-file vsperf.conf \ --test-params "traffic_type=continuous;bidirectional=True;iload=60" Code change verification by pylint @@ -665,7 +732,7 @@ By default the vswitchd is launched with 1Gb of memory, to change this, modify --socket-mem parameter in conf/02_vswitch.conf to allocate an appropriate amount of memory: -.. code-block:: console +.. code-block:: python VSWITCHD_DPDK_ARGS = ['-c', '0x4', '-n', '4', '--socket-mem 1024,0'] VSWITCHD_DPDK_CONFIG = { |