X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Ftesting%2Fuser%2Fuserguide%2Fadvanced.rst;h=1d2ac36cac375b18a93ed3e2953d02475aceb7a9;hb=7a90e74a1390794b72fc5c3629e141f2def908d7;hp=f757b46f082f405602b04c84031603a4bf933e6d;hpb=04a7de082bd221eae3c7004f4e0b99dfa4f8be91;p=nfvbench.git diff --git a/docs/testing/user/userguide/advanced.rst b/docs/testing/user/userguide/advanced.rst index f757b46..1d2ac36 100644 --- a/docs/testing/user/userguide/advanced.rst +++ b/docs/testing/user/userguide/advanced.rst @@ -11,7 +11,7 @@ Below are shown the most common and useful use-cases and explained some fields f How to change any NFVbench run configuration (CLI) -------------------------------------------------- -NFVbench always starts with a default configuration which can further be partially refined (overridden) by the user from the CLI or from REST requests. +NFVbench always starts with a default configuration which can further be refined (overridden) by the user from the CLI or from REST requests. At first have a look at the default config: @@ -39,9 +39,9 @@ as seen from inside the container (in this example, we assume the current direct The same -c option also accepts any valid yaml or json string to override certain parameters without having to create a configuration file. -NFVbench also provides many configuration options as optional arguments. For example the number of flows can be specified using the --flow-count option. +NFVbench provides many configuration options as optional arguments. For example the number of flows can be specified using the --flow-count option. -For example, flow count can be specified in any of 3 ways: +The flow count option can be specified in any of 3 ways: - by providing a confguration file that has the flow_count value to use (-c myconfig.yaml and myconfig.yaml contains 'flow_count: 100k') - by passing that yaml paremeter inline (-c "flow_count: 100k") or (-c "{flow_count: 100k}") @@ -63,10 +63,9 @@ For example, this will only display the running configuration (without actually Connectivity and Configuration Check ------------------------------------ -NFVbench allows to test connectivity to devices used with selected flow test, for example PVP. -It runs the whole test, but without actually sending any traffic or influencing interface counters. -It is also a good way to check if everything is configured properly in the config file and what versions of components are used. - +NFVbench allows to test connectivity to devices used with the selected packet path. +It runs the whole test, but without actually sending any traffic. +It is also a good way to check if everything is configured properly in the configuration file and what versions of components are used. To verify everything works without sending any traffic, use the --no-traffic option: @@ -83,13 +82,13 @@ Used parameters: Fixed Rate Run -------------- -Fixed rate run is the most basic type of NFVbench usage. It is usually used to verify that some amount of packets can pass network components in selected flow. +Fixed rate run is the most basic type of NFVbench usage. It can be used to measure the drop rate with a fixed transmission rate of packets. -The first example shows how to run PVP flow (default flow) with multiple different settings: +This example shows how to run the PVP packet path (which is the default packet path) with multiple different settings: .. code-block:: bash - nfvbench -c nfvbench.cfg --no-reset --no-cleanup --rate 100000pps --duration 30 --interval 15 --json results.json + nfvbench -c nfvbench.cfg --no-cleanup --rate 100000pps --duration 30 --interval 15 --json results.json Used parameters: @@ -100,16 +99,16 @@ Used parameters: * ``--interval 15`` : stats are checked and shown periodically (in seconds) in this interval when traffic is flowing * ``--json results.json`` : collected data are stored in this file after run is finished -.. note:: It is your responsibility to clean up resources if needed when ``--no-cleanup`` parameter is used. +.. note:: It is your responsibility to clean up resources if needed when ``--no-cleanup`` parameter is used. You can use the nfvbench_cleanup helper script for that purpose. -The ``--json`` parameter makes it easy to store NFVbench results. To display collected results in a table form, do: +The ``--json`` parameter makes it easy to store NFVbench results. The --show-summary (or -ss) option can be used to display the results in a json results file in a text tabular format: .. code-block:: bash - nfvbench --show-summary results.json # or shortcut -ss results.json + nfvbench --show-summary results.json -Second example aims to show how to specify which supported flow to run: +This example shows how to specify a different packet path: .. code-block:: bash @@ -120,7 +119,7 @@ Used parameters: * ``-c nfvbench.cfg`` : path to the config file * ``--rate 1Mbps`` : defines rate of packets sent by traffic generator * ``--inter-node`` : VMs are created on different compute nodes, works only with PVVP flow -* ``--service-chain PVVP`` or ``-sc PVVP`` : specifies type of flow to use, default is PVP +* ``--service-chain PVVP`` or ``-sc PVVP`` : specifies the type of service chain (or packet path) to use .. note:: When parameter ``--inter-node`` is not used or there aren't enough compute nodes, VMs are on the same compute node. @@ -135,20 +134,22 @@ Parameter ``--rate`` accepts different types of values: * bits per second (bps, kbps, Mbps, Gbps), e.g. ``1Gbps``, ``1000bps`` * NDR/PDR (ndr, pdr, ndr_pdr), e.g. ``ndr_pdr`` -The last mentioned value, NDR/PDR, is default one and its usage is covered more below. - +NDR/PDR is the default rate when not specified. NDR and PDR ----------- -NDR and PDR test is used to determine performance of your setup, maximum packets throughput. +The NDR and PDR test is used to determine the maximum throughput performance of the system under test +following guidelines defined in RFC-2544: + +* NDR (No Drop Rate): maximum packet rate sent without dropping any packet +* PDR (Partial Drop Rate): maximum packet rate sent while allowing a given maximum drop rate -* NDR (No Drop Rate): how many packets can be sent so (almost) none of them are dropped -* PDR (Partial Drop Rate): how many packets can be sent so drop rate is below given limit +The NDR search can also be relaxed to allow some very small amount of drop rate (lower than the PDR maximum drop rate). +NFVbench will measure the NDR and PDR values by driving the traffic generator through multiple iterations +at different transmission rates using a binary search algorithm. -Config file contains section where settings for NDR/PDR can be set. -Increasing number of attempts helps to minimize a chance of traffic hiccups influencing result. -Other way of increasing precision is to specify longer duration for traffic to run. +The configuration file contains section where settings for NDR/PDR can be set. .. code-block:: bash @@ -166,13 +167,13 @@ Other way of increasing precision is to specify longer duration for traffic to r # or PDR should be within `load_epsilon` difference than the one calculated. load_epsilon: 0.1 -Because NDR/PDR is the default ``--rate`` value, it's possible to run NFVbench simply like this: +Because NDR/PDR is the default ``--rate`` value, it is possible to run NFVbench simply like this: .. code-block:: bash nfvbench -c nfvbench.cfg -Other custom run: +Other possible run options: .. code-block:: bash @@ -188,69 +189,27 @@ Used parameters: Multichain ---------- -NFVbench allows to run multiple chains at the same time. For example it is possible to run PVP service chain N-times, +NFVbench allows to run multiple chains at the same time. For example it is possible to stage the PVP service chain N-times, where N can be as much as your compute power can scale. With N = 10, NFVbench will spawn 10 VMs as a part of 10 simultaneous PVP chains. -Number of chains is specified by ``--service-chain-count`` or ``-scc`` flag, default value is 1. -For example to run NFVbench with 3 PVP chains use command: +The number of chains is specified by ``--service-chain-count`` or ``-scc`` flag with a default value of 1. +For example to run NFVbench with 3 PVP chains: .. code-block:: bash nfvbench -c nfvbench.cfg --rate 10000pps -scc 3 -It is not necessary to specify service chain because PVP is set as default. PVP service chains will have 3 VMs in 3 chains with this configuration. +It is not necessary to specify the service chain type (-sc) because PVP is set as default. The PVP service chains will have 3 VMs in 3 chains with this configuration. If ``-sc PVVP`` is specified instead, there would be 6 VMs in 3 chains as this service chain has 2 VMs per chain. -Both **single run** or **NDR/PDR** can be run as multichain. Running multichain is a scenario closer to a real life situation than just simple run. - - -External Chain --------------- - -NFVbench can measure the performance of 1 or more L3 service chains that are setup externally. Instead of being setup by NFVbench, -the complete environment (VMs and networks) has to be setup prior to running NFVbench. - -Each external chain is made of 1 or more VNFs and has exactly 2 end network interfaces (left and right network interfaces) that are connected to 2 neutron networks (left and right networks). -The internal composition of a multi-VNF service chain can be arbitrary (usually linear) as far as NFVbench is concerned, -the only requirement is that the service chain can route L3 packets properly between the left and right networks. - -To run NFVbench on such external service chains: - -- explicitly tell NFVbench to use external service chain by adding ``-sc EXT`` or ``--service-chain EXT`` to NFVbench CLI options -- specify the number of external chains using the ``-scc`` option (defaults to 1 chain) -- specify the 2 end point networks of your environment in ``external_networks`` inside the config file. - - The two networks specified there have to exist in Neutron and will be used as the end point networks by NFVbench ('napa' and 'marin' in the diagram below) -- specify the router gateway IPs for the external service chains (1.1.0.2 and 2.2.0.2) -- specify the traffic generator gateway IPs for the external service chains (1.1.0.102 and 2.2.0.102 in diagram below) -- specify the packet source and destination IPs for the virtual devices that are simulated (10.0.0.0/8 and 20.0.0.0/8) - - -.. image:: images/extchain-config.svg - -The L3 router function must be enabled in the VNF and configured to: - -- reply to ARP requests to its public IP addresses on both left and right networks -- route packets from each set of remote devices toward the appropriate dest gateway IP in the traffic generator using 2 static routes (as illustrated in the diagram) - -Upon start, NFVbench will: -- first retrieve the properties of the left and right networks using Neutron APIs, -- extract the underlying network ID (either VLAN ID or VNI if VxLAN is used), -- then program the TOR to stitch the 2 interfaces from the traffic generator into each end of the service chain, -- then generate and measure traffic. - -Note that in the case of multiple chains, all chains end interfaces must be connected to the same two left and right networks. -The traffic will be load balanced across the corresponding gateway IP of these external service chains. - -.. note:: By default, interfaces configuration (TOR, VTS, etc.) will be run by NFVbench but these can be skipped by using ``--no-int-config`` flag. +Both **single run** or **NDR/PDR** can be run as multichain. Runnin multichain is a scenario closer to a real life situation than runs with a single chain. Multiflow --------- NFVbench always generates L3 packets from the traffic generator but allows the user to specify how many flows to generate. -A flow is identified by a unique src/dest MAC IP and port tuple that is sent by the traffic generator. Note that from a vswitch point of view, the -number of flows seen will be higher as it will be at least 4 times the number of flows sent by the traffic generator -(add reverse direction of vswitch to traffic generator, add flow to VM and flow from VM). - +A flow is identified by a unique src/dest MAC IP and port tuple that is sent by the traffic generator. Flows are +generated by ranging the IP adresses but using a small fixed number of MAC addresses. The number of flows will be spread roughly even between chains when more than 1 chain is being tested. For example, for 11 flows and 3 chains, number of flows that will run for each chain will be 3, 4, and 4 flows respectively. @@ -262,6 +221,9 @@ To run NFVbench with 3 chains and 100 flows, use the following command: nfvbench -c nfvbench.cfg --rate 10000pps -scc 3 -fc 100 +Note that from a vswitch point of view, the +number of flows seen will be higher as it will be at least 4 times the number of flows sent by the traffic generator +(add flow to VM and flow from VM). IP addresses generated can be controlled with the following NFVbench configuration options: @@ -286,12 +248,11 @@ The corresponding ``step`` is used for ranging the IP addresses from the `ip_add 0.0.0.1 is the default step for all IP ranges. In ``ip_addrs``, 'random' can be configured which tells NFVBench to generate random src/dst IP pairs in the traffic stream. -Traffic Config via CLI ----------------------- +Traffic Configuration via CLI +----------------------------- -While traffic configuration can modified using the config file, it became a hassle to have to change the config file everytime you need to change traffic config. - -Traffic config can be overridden with the CLI options. +While traffic configuration can be modified using the configuration file, it can be inconvenient to have to change the configuration file everytime +you need to change a traffic configuration option. Traffic configuration options can be overridden with a few CLI options. Here is an example of configuring traffic via CLI: @@ -299,7 +260,7 @@ Here is an example of configuring traffic via CLI: nfvbench --rate 10kpps --service-chain-count 2 -fs 64 -fs IMIX -fs 1518 --unidir -This command will run NFVbench with two streams with unidirectional flow for three packet sizes 64B, IMIX, and 1518B. +This command will run NFVbench with a unidirectional flow for three packet sizes 64B, IMIX, and 1518B. Used parameters: @@ -313,6 +274,63 @@ MAC Addresses ------------- NFVbench will dicover the MAC addresses to use for generated frames using: -- either OpenStack discovery (find the MAC of an existing VM) if the loopback VM is configured to run L2 forwarding -- or using dynamic ARP discovery (find MAC from IP) if the loopback VM is configured to run L3 routing or in the case of external chains. - +- either OpenStack discovery (find the MAC of an existing VM) in the case of PVP and PVVP service chains +- or using dynamic ARP discovery (find MAC from IP) in the case of external chains. + +Status and Cleanup of NFVbench Resources +---------------------------------------- + +The --status option will display the status of NFVbench and list any NFVbench resources. You need to pass the OpenStack RC +file in order to connect to OpenStack. + +.. code-block:: none + + # nfvbench --status -r /tmp/nfvbench/openrc + 2018-04-09 17:05:48,682 INFO Version: 1.3.2.dev1 + 2018-04-09 17:05:48,683 INFO Status: idle + 2018-04-09 17:05:48,757 INFO Discovering instances nfvbench-loop-vm... + 2018-04-09 17:05:49,252 INFO Discovering flavor nfvbench.medium... + 2018-04-09 17:05:49,281 INFO Discovering networks... + 2018-04-09 17:05:49,365 INFO No matching NFVbench resources found + # + +The Status can be either "idle" or "busy (run pending)". + +The --cleanup option will first discover resources created by NFVbench and prompt if you want to proceed with cleaning them up. +Example of run: + +.. code-block:: none + + # nfvbench --cleanup -r /tmp/nfvbench/openrc + 2018-04-09 16:58:00,204 INFO Version: 1.3.2.dev1 + 2018-04-09 16:58:00,205 INFO Status: idle + 2018-04-09 16:58:00,279 INFO Discovering instances nfvbench-loop-vm... + 2018-04-09 16:58:00,829 INFO Discovering flavor nfvbench.medium... + 2018-04-09 16:58:00,876 INFO Discovering networks... + 2018-04-09 16:58:00,960 INFO Discovering ports... + 2018-04-09 16:58:01,012 INFO Discovered 6 NFVbench resources: + +----------+-------------------+--------------------------------------+ + | Type | Name | UUID | + |----------+-------------------+--------------------------------------| + | Instance | nfvbench-loop-vm0 | b039b858-777e-467e-99fb-362f856f4a94 | + | Flavor | nfvbench.medium | a027003c-ad86-4f24-b676-2b05bb06adc0 | + | Network | nfvbench-net0 | bca8d183-538e-4965-880e-fd92d48bfe0d | + | Network | nfvbench-net1 | c582a201-8279-4309-8084-7edd6511092c | + | Port | | 67740862-80ac-4371-b04e-58a0b0f05085 | + | Port | | b5db95b9-e419-4725-951a-9a8f7841e66a | + +----------+-------------------+--------------------------------------+ + 2018-04-09 16:58:01,013 INFO NFVbench will delete all resources shown... + Are you sure? (y/n) y + 2018-04-09 16:58:01,865 INFO Deleting instance nfvbench-loop-vm0... + 2018-04-09 16:58:02,058 INFO Waiting for 1 instances to be fully deleted... + 2018-04-09 16:58:02,182 INFO 1 yet to be deleted by Nova, retries left=6... + 2018-04-09 16:58:04,506 INFO 1 yet to be deleted by Nova, retries left=5... + 2018-04-09 16:58:06,636 INFO 1 yet to be deleted by Nova, retries left=4... + 2018-04-09 16:58:08,701 INFO Deleting flavor nfvbench.medium... + 2018-04-09 16:58:08,729 INFO Deleting port 67740862-80ac-4371-b04e-58a0b0f05085... + 2018-04-09 16:58:09,102 INFO Deleting port b5db95b9-e419-4725-951a-9a8f7841e66a... + 2018-04-09 16:58:09,620 INFO Deleting network nfvbench-net0... + 2018-04-09 16:58:10,357 INFO Deleting network nfvbench-net1... + # + +The --force-cleanup option will do the same but without prompting for confirmation.