docs/testing/user/userguide/trafficcapture.rst

   1 Traffic Capture
   2 ---------------
   3
   4 Tha ability to capture traffic at multiple points of the system is crucial to
   5 many of the functional tests. It allows the verification of functionality for
   6 both the vSwitch and the NICs using hardware acceleration for packet
   7 manipulation and modification.
   8
   9 There are three different methods of traffic capture supported by VSPERF.
  10 Detailed descriptions of these methods as well as their pros and cons can be
  11 found in the following chapters.
  12
  13 Traffic Capture inside of a VM
  14 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15
  16 This method uses the standard PVP scenario, in which vSwitch first processes
  17 and modifies the packet before forwarding it to the VM. Inside of the VM we
  18 capture the traffic using **tcpdump** or a similiar technique. The capture
  19 information is the used to verify the expected modifications to the packet done
  20 by vSwitch.
  21
  22 .. code-block:: console
  23
  24                                                             _
  25        +--------------------------------------------------+  |
  26        |                                                  |  |
  27        |   +------------------------------------------+   |  |
  28        |   |  Traffic capture and Packet Forwarding   |   |  |
  29        |   +------------------------------------------+   |  |
  30        |          ^                            :          |  |
  31        |          |                            |          |  |  Guest
  32        |          :                            v          |  |
  33        |   +---------------+          +---------------+   |  |
  34        |   | logical port 0|          | logical port 1|   |  |
  35        +---+---------------+----------+---------------+---+ _|
  36                    ^                          :
  37                    |                          |
  38                    :                          v            _
  39        +---+---------------+----------+---------------+---+  |
  40        |   | logical port 0|          | logical port 1|   |  |
  41        |   +---------------+          +---------------+   |  |
  42        |           ^                          :           |  |
  43        |           |                          |           |  |  Host
  44        |           :                          v           |  |
  45        |   +--------------+            +--------------+   |  |
  46        |   |   phy port   |  vSwitch   |   phy port   |   |  |
  47        +---+--------------+------------+--------------+---+ _|
  48                    ^                          :
  49                    |                          |
  50                    :                          v
  51        +--------------------------------------------------+
  52        |                                                  |
  53        |                traffic generator                 |
  54        |                                                  |
  55        +--------------------------------------------------+
  56
  57 PROS:
  58
  59 - supports testing with all traffic generators
  60 - easy to use and implement into test
  61 - allows testing hardware offloading on the ingress side
  62
  63 CONS:
  64
  65 - does not allow testing hardware offloading on the egress side
  66
  67 An example of Traffic Capture in VM test:
  68
  69 .. code-block:: python
  70
  71     # Capture Example 1 - Traffic capture inside VM (PVP scenario)
  72     # This TestCase will modify VLAN ID set by the traffic generator to the new value.
  73     # Correct VLAN ID settings is verified by inspection of captured frames.
  74     {
  75         Name: capture_pvp_modify_vid,
  76         Deployment: pvp,
  77         Description: Test and verify VLAN ID modification by Open vSwitch,
  78         Parameters : {
  79             VSWITCH : OvsDpdkVhost, # works also for Vanilla OVS
  80             TRAFFICGEN_DURATION : 5,
  81             TRAFFIC : {
  82                 traffic_type : rfc2544_continuous,
  83                 frame_rate : 100,
  84                 'vlan': {
  85                     'enabled': True,
  86                     'id': 8,
  87                     'priority': 1,
  88                     'cfi': 0,
  89                 },
  90             },
  91             GUEST_LOOPBACK : ['linux_bridge'],
  92         },
  93         TestSteps: [
  94             # replace original flows with vlan ID modification
  95             ['!vswitch', 'add_flow', 'br0', {'in_port': '1', 'actions': ['mod_vlan_vid:4','output:3']}],
  96             ['!vswitch', 'add_flow', 'br0', {'in_port': '2', 'actions': ['mod_vlan_vid:4','output:4']}],
  97             ['vswitch', 'dump_flows', 'br0'],
  98             # verify that received frames have modified vlan ID
  99             ['VNF0', 'execute_and_wait', 'tcpdump -i eth0 -c 5 -w dump.pcap vlan 4 &'],
 100             ['trafficgen', 'send_traffic',{}],
 101             ['!VNF0', 'execute_and_wait', 'tcpdump -qer dump.pcap vlan 4 2>/dev/null | wc -l','|^(\d+)$'],
 102             ['tools', 'assert', '#STEP[-1][0] == 5'],
 103         ],
 104     },
 105
 106 Traffic Capture for testing NICs with HW offloading/acceleration
 107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 108
 109 The NIC with hardware acceleration/offloading is inserted as an additional card
 110 into the server. Two ports on this card are then connected together using
 111 a patch cable as shown in the diagram. Only a single port of the tested NIC is
 112 setup with DPDK acceleration, while the other is handled by the Linux Ip stack
 113 allowing for traffic capture. The two NICs are then connected by vSwitch so the
 114 original card can forward the processed packets to the traffic generator. The
 115 ports handled by Linux IP stack allow for capturing packets, which are then
 116 analyzed for changes done by both the vSwitch and the NIC with hardware
 117 acceleration.
 118
 119 .. code-block:: console
 120
 121                                                        _
 122     +------------------------------------------------+  |
 123     |                                                |  |
 124     |   +----------------------------------------+   |  |
 125     |   |                 vSwitch                |   |  |
 126     |   |  +----------------------------------+  |   |  |
 127     |   |  |                                  |  |   |  |
 128     |   |  |       +------------------+       |  |   |  |
 129     |   |  |       |                  |       v  |   |  |
 130     |   +----------------------------------------+   |  |  Device under Test
 131     |      ^       |                  ^       |      |  |
 132     |      |       |                  |       |      |  |
 133     |      |       v                  |       v      |  |
 134     |   +--------------+          +--------------+   |  |
 135     |   |              |          | NIC w HW acc |   |  |
 136     |   |   phy ports  |          |   phy ports  |   |  |
 137     +---+--------------+----------+--------------+---+ _|
 138            ^       :                  ^       :
 139            |       |                  |       |
 140            |       |                  +-------+
 141            :       v                 Patch Cable
 142     +------------------------------------------------+
 143     |                                                |
 144     |                traffic generator               |
 145     |                                                |
 146     +------------------------------------------------+
 147
 148 PROS:
 149
 150 - allows testing hardware offloading on both the ingress and egress side
 151 - supports testing with all traffic generators
 152 - relatively easy to use and implement into tests
 153
 154 CONS:
 155
 156 - a more complex setup with two cards
 157 - if the tested card only has one port, an additional card is needed
 158
 159 An example of Traffic Capture for testing NICs with HW offloading test:
 160
 161 .. code-block:: python
 162
 163     # Capture Example 2 - Setup with 2 NICs, where traffic is captured after it is
 164     # processed by NIC under the test (2nd NIC). See documentation for further details.
 165     # This TestCase will strip VLAN headers from traffic sent by the traffic generator.
 166     # The removal of VLAN headers is verified by inspection of captured frames.
 167     #
 168     # NOTE: This setup expects a DUT with two NICs with two ports each. First NIC is
 169     # connected to the traffic generator (standard VSPERF setup). Ports of a second NIC
 170     # are interconnected by a patch cable. PCI addresses of all four ports have to be
 171     # properly configured in the WHITELIST_NICS parameter.
 172     {
 173         Name: capture_p2p2p_strip_vlan_ovs,
 174         Deployment: clean,
 175         Description: P2P Continuous Stream,
 176         Parameters : {
 177             _CAPTURE_P2P2P_OVS_ACTION : 'strip_vlan',
 178             TRAFFIC : {
 179                 bidir : False,
 180                 traffic_type : rfc2544_continuous,
 181                 frame_rate : 100,
 182                 'l2': {
 183                     'srcmac': ca:fe:00:00:00:00,
 184                     'dstmac': 00:00:00:00:00:01
 185                 },
 186                 'vlan': {
 187                     'enabled': True,
 188                     'id': 8,
 189                     'priority': 1,
 190                     'cfi': 0,
 191                 },
 192             },
 193             # suppress DPDK configuration, so physical interfaces are not bound to DPDK driver
 194             'WHITELIST_NICS' : [],
 195             'NICS' : [],
 196         },
 197         TestSteps: _CAPTURE_P2P2P_SETUP + [
 198             # capture traffic after processing by NIC under the test (after possible egress HW offloading)
 199             ['tools', 'exec_shell_background', 'tcpdump -i [2][device] -c 5 -w capture.pcap '
 200                                                'ether src [l2][srcmac]'],
 201             ['trafficgen', 'send_traffic', {}],
 202             ['vswitch', 'dump_flows', 'br0'],
 203             ['vswitch', 'dump_flows', 'br1'],
 204             # there must be 5 captured frames...
 205             ['tools', 'exec_shell', 'tcpdump -r capture.pcap | wc -l', '|^(\d+)$'],
 206             ['tools', 'assert', '#STEP[-1][0] == 5'],
 207             # ...but no vlan headers
 208             ['tools', 'exec_shell', 'tcpdump -r capture.pcap vlan | wc -l', '|^(\d+)$'],
 209             ['tools', 'assert', '#STEP[-1][0] == 0'],
 210         ],
 211     },
 212
 213
 214 Traffic Capture on the Traffic Generator
 215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 216
 217 Using the functionality of the Traffic generator makes it possible to configure
 218 Traffic Capture on both it's ports. With Traffic Capture enabled, VSPERF
 219 instructs the Traffic Generator to automatically export captured data into
 220 a pcap file. The captured packets are then sent to VSPERF for analysis and
 221 verification, monitoring any changes done by both vSwitch and the NICs.
 222
 223 Vsperf currently only supports this functionality with the **T-Rex** generator.
 224
 225 .. code-block:: console
 226
 227                                                             _
 228        +--------------------------------------------------+  |
 229        |                                                  |  |
 230        |           +--------------------------+           |  |
 231        |           |                          |           |  |
 232        |           |                          v           |  |  Host
 233        |   +--------------+            +--------------+   |  |
 234        |   |   phy port   |  vSwitch   |   phy port   |   |  |
 235        +---+--------------+------------+--------------+---+ _|
 236                    ^                          :
 237                    |                          |
 238                    :                          v
 239        +--------------------------------------------------+
 240        |                                                  |
 241        |                traffic generator                 |
 242        |                                                  |
 243        +--------------------------------------------------+
 244
 245 PROS:
 246
 247 - allows testing hardware offloading on both the ingress and egress side
 248 - does not require an additional NIC
 249
 250 CONS:
 251
 252 - currently only supported by **T-Rex** traffic generator
 253
 254 An example Traffic Capture on the Traffic Generator test:
 255
 256 .. code-block:: python
 257
 258
 259     # Capture Example 3 - Traffic capture by traffic generator.
 260     # This TestCase uses OVS flow to add VLAN tag with given ID into every
 261     # frame send by traffic generator. Correct frame modificaiton is verified by
 262     # inspection of packet capture received by T-Rex.
 263     {
 264         Name: capture_p2p_add_vlan_ovs_trex,
 265         Deployment: clean,
 266         Description: OVS: Test VLAN tag modification and verify it by traffic capture,
 267         vSwitch : OvsDpdkVhost, # works also for Vanilla OVS
 268         Parameters : {
 269             TRAFFICGEN : Trex,
 270             TRAFFICGEN_DURATION : 5,
 271             TRAFFIC : {
 272                 traffic_type : rfc2544_continuous,
 273                 frame_rate : 100,
 274                 # enable capture of five RX frames
 275                 'capture': {
 276                     'enabled': True,
 277                     'tx_ports' : [],
 278                     'rx_ports' : [1],
 279                     'count' : 5,
 280                 },
 281             },
 282         },
 283         TestSteps : STEP_VSWITCH_P2P_INIT + [
 284             # replace standard L2 flows by flows, which will add VLAN tag with ID 3
 285             ['!vswitch', 'add_flow', 'int_br0', {'in_port': '1', 'actions': ['mod_vlan_vid:3','output:2']}],
 286             ['!vswitch', 'add_flow', 'int_br0', {'in_port': '2', 'actions': ['mod_vlan_vid:3','output:1']}],
 287             ['vswitch', 'dump_flows', 'int_br0'],
 288             ['trafficgen', 'send_traffic', {}],
 289             ['trafficgen', 'get_results'],
 290             # verify that captured frames have vlan tag with ID 3
 291             ['tools', 'exec_shell', 'tcpdump -qer /#STEP[-1][0][capture_rx] vlan 3 '
 292                                     '2>/dev/null | wc -l', '|^(\d+)$'],
 293             # number of received frames with expected VLAN id must match the number of captured frames
 294             ['tools', 'assert', '#STEP[-1][0] == 5'],
 295         ] + STEP_VSWITCH_P2P_FINIT,
 296     },
 297