doc/guides/howto/rte_flow.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2017 Mellanox Technologies, Ltd
   3
   4 Generic flow API - examples
   5 ===========================
   6
   7 This document demonstrates some concrete examples for programming flow rules
   8 with the ``rte_flow`` APIs.
   9
  10 * Detail of the rte_flow APIs can be found in the following link:
  11   :doc:`../prog_guide/rte_flow`.
  12
  13 * Details of the TestPMD commands to set the flow rules can be found in the
  14   following link: :ref:`TestPMD Flow rules <testpmd_rte_flow>`
  15
  16 Simple IPv4 drop
  17 ----------------
  18
  19 Description
  20 ~~~~~~~~~~~
  21
  22 In this example we will create a simple rule that drops packets whose IPv4
  23 destination equals 192.168.3.2. This code is equivalent to the following
  24 testpmd command (wrapped for clarity)::
  25
  26   testpmd> flow create 0 ingress pattern eth / vlan /
  27                     ipv4 dst is 192.168.3.2 / end actions drop / end
  28
  29 Code
  30 ~~~~
  31
  32 .. code-block:: c
  33
  34   /* create the attribute structure */
  35   struct rte_flow_attr attr = { .ingress = 1 };
  36   struct rte_flow_item pattern[MAX_PATTERN_IN_FLOW];
  37   struct rte_flow_action actions[MAX_ACTIONS_IN_FLOW];
  38   struct rte_flow_item_eth eth;
  39   struct rte_flow_item_vlan vlan;
  40   struct rte_flow_item_ipv4 ipv4;
  41   struct rte_flow *flow;
  42   struct rte_flow_error error;
  43
  44   /* setting the eth to pass all packets */
  45   pattern[0].type = RTE_FLOW_ITEM_TYPE_ETH;
  46   pattern[0].spec = &eth;
  47
  48   /* set the vlan to pass all packets */
  49   pattern[1] = RTE_FLOW_ITEM_TYPE_VLAN;
  50   pattern[1].spec = &vlan;
  51
  52   /* set the dst ipv4 packet to the required value */
  53   ipv4.hdr.dst_addr = htonl(0xc0a80302);
  54   pattern[2].type = RTE_FLOW_ITEM_TYPE_IPV4;
  55   pattern[2].spec = &ipv4;
  56
  57   /* end the pattern array */
  58   pattern[3].type = RTE_FLOW_ITEM_TYPE_END;
  59
  60   /* create the drop action */
  61   actions[0].type = RTE_FLOW_ACTION_TYPE_DROP;
  62   actions[1].type = RTE_FLOW_ACTION_TYPE_END;
  63
  64   /* validate and create the flow rule */
  65   if (!rte_flow_validate(port_id, &attr, pattern, actions, &error))
  66       flow = rte_flow_create(port_id, &attr, pattern, actions, &error);
  67
  68 Output
  69 ~~~~~~
  70
  71 Terminal 1: running sample app with the flow rule disabled::
  72
  73   ./filter-program disable
  74   [waiting for packets]
  75
  76 Terminal 2: running scapy::
  77
  78   $scapy
  79   welcome to Scapy
  80   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.4', dst='192.168.3.1'), \
  81            iface='some interface', count=1)
  82   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.5', dst='192.168.3.2'), \
  83            iface='some interface', count=1)
  84
  85 Terminal 1: output log::
  86
  87   received packet with src ip = 176.80.50.4
  88   received packet with src ip = 176.80.50.5
  89
  90 Terminal 1: running sample the app flow rule enabled::
  91
  92   ./filter-program enabled
  93   [waiting for packets]
  94
  95 Terminal 2: running scapy::
  96
  97   $scapy
  98   welcome to Scapy
  99   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.4', dst='192.168.3.1'),  \
 100            iface='some interface', count=1)
 101   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.5', dst ='192.168.3.2'), \
 102            iface='some interface', count=1)
 103
 104 Terminal 1: output log::
 105
 106   received packet with src ip = 176.80.50.4
 107
 108 Range IPv4 drop
 109 ----------------
 110
 111 Description
 112 ~~~~~~~~~~~
 113
 114 In this example we will create a simple rule that drops packets whose IPv4
 115 destination is in the range 192.168.3.0 to 192.168.3.255. This is done using
 116 a mask.
 117
 118 This code is equivalent to the following testpmd command (wrapped for
 119 clarity)::
 120
 121   testpmd> flow create 0 ingress pattern eth / vlan /
 122                     ipv4 dst spec 192.168.3.0 dst mask 255.255.255.0 /
 123                     end actions drop / end
 124
 125 Code
 126 ~~~~
 127
 128 .. code-block:: c
 129
 130   struct rte_flow_attr attr = {.ingress = 1};
 131   struct rte_flow_item pattern[MAX_PATTERN_IN_FLOW];
 132   struct rte_flow_action actions[MAX_ACTIONS_IN_FLOW];
 133   struct rte_flow_item_eth eth;
 134   struct rte_flow_item_vlan vlan;
 135   struct rte_flow_item_ipv4 ipv4;
 136   struct rte_flow_item_ipv4 ipv4_mask;
 137   struct rte_flow *flow;
 138   struct rte_flow_error error;
 139
 140   /* setting the eth to pass all packets */
 141   pattern[0].type = RTE_FLOW_ITEM_TYPE_ETH;
 142   pattern[0].spec = &eth;
 143
 144   /* set the vlan to pass all packets */
 145   pattern[1] = RTE_FLOW_ITEM_TYPE_VLAN;
 146   pattern[1].spec = &vlan;
 147
 148   /* set the dst ipv4 packet to the required value */
 149   ipv4.hdr.dst_addr = htonl(0xc0a80300);
 150   ipv4_mask.hdr.dst_addr = htonl(0xffffff00);
 151   pattern[2].type = RTE_FLOW_ITEM_TYPE_IPV4;
 152   pattern[2].spec = &ipv4;
 153   pattern[2].mask = &ipv4_mask;
 154
 155   /* end the pattern array */
 156   pattern[3].type = RTE_FLOW_ITEM_TYPE_END;
 157
 158   /* create the drop action */
 159   actions[0].type = RTE_FLOW_ACTION_TYPE_DROP;
 160   actions[1].type = RTE_FLOW_ACTION_TYPE_END;
 161
 162   /* validate and create the flow rule */
 163   if (!rte_flow_validate(port_id, &attr, pattern, actions, &error))
 164       flow = rte_flow_create(port_id, &attr, pattern, actions, &error);
 165
 166 Output
 167 ~~~~~~
 168
 169 Terminal 1: running sample app flow rule disabled::
 170
 171   ./filter-program disable
 172   [waiting for packets]
 173
 174 Terminal 2: running scapy::
 175
 176   $scapy
 177   welcome to Scapy
 178   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.4', dst='192.168.3.1'), \
 179            iface='some interface', count=1)
 180   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.5', dst='192.168.3.2'), \
 181            iface='some interface', count=1)
 182   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.6', dst='192.168.5.2'), \
 183            iface='some interface', count=1)
 184
 185 Terminal 1: output log::
 186
 187   received packet with src ip = 176.80.50.4
 188   received packet with src ip = 176.80.50.5
 189   received packet with src ip = 176.80.50.6
 190
 191 Terminal 1: running sample app flow rule enabled::
 192
 193   ./filter-program enabled
 194   [waiting for packets]
 195
 196 Terminal 2: running scapy::
 197
 198   $scapy
 199   welcome to Scapy
 200   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.4', dst='192.168.3.1'), \
 201            iface='some interface', count=1)
 202   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.5', dst='192.168.3.2'), \
 203            iface='some interface', count=1)
 204   >> sendp(Ether()/Dot1Q()/IP(src='176.80.50.6', dst='192.168.5.2'), \
 205            iface='some interface', count=1)
 206
 207 Terminal 1: output log::
 208
 209   received packet with src ip = 176.80.50.6
 210
 211 Send vlan to queue
 212 ------------------
 213
 214 Description
 215 ~~~~~~~~~~~
 216
 217 In this example we will create a rule that routes all vlan id 123 to queue 3.
 218
 219 This code is equivalent to the following testpmd command (wrapped for
 220 clarity)::
 221
 222   testpmd> flow create 0 ingress pattern eth / vlan vid spec 123 /
 223                     end actions queue index 3 / end
 224
 225 Code
 226 ~~~~
 227
 228 .. code-block:: c
 229
 230   struct rte_flow_attr attr = { .ingress = 1 };
 231   struct rte_flow_item pattern[MAX_PATTERN_IN_FLOW];
 232   struct rte_flow_action actions[MAX_ACTIONS_IN_FLOW];
 233   struct rte_flow_item_eth eth;
 234   struct rte_flow_item_vlan vlan;
 235   struct rte_flow_action_queue queue = { .index = 3 };
 236   struct rte_flow *flow;
 237   struct rte_flow_error error;
 238
 239   /* setting the eth to pass all packets */
 240   pattern[0].type = RTE_FLOW_ITEM_TYPE_ETH;
 241   pattern[0].spec = &eth;
 242
 243   /* set the vlan to pas all packets */
 244   vlan.vid = 123;
 245   pattern[1] = RTE_FLOW_ITEM_TYPE_VLAN;
 246   pattern[1].spec = &vlan;
 247
 248   /* end the pattern array */
 249   pattern[2].type = RTE_FLOW_ITEM_TYPE_END;
 250
 251   /* create the queue action */
 252   actions[0].type = RTE_FLOW_ACTION_TYPE_QUEUE;
 253   actions[0].conf = &queue;
 254   actions[1].type = RTE_FLOW_ACTION_TYPE_END;
 255
 256   /* validate and create the flow rule */
 257   if (!rte_flow_validate(port_id, &attr, pattern, actions, &error))
 258       flow = rte_flow_create(port_id, &attr, pattern, actions, &error);
 259
 260 Output
 261 ~~~~~~
 262
 263 Terminal 1: running sample app flow rule disabled::
 264
 265   ./filter-program disable
 266   [waiting for packets]
 267
 268 Terminal 2: running scapy::
 269
 270   $scapy
 271   welcome to Scapy
 272   >> sendp(Ether()/Dot1Q(vlan=123)/IP(src='176.80.50.4', dst='192.168.3.1'), \
 273            iface='some interface', count=1)
 274   >> sendp(Ether()/Dot1Q(vlan=50)/IP(src='176.80.50.5', dst='192.168.3.2'),  \
 275            iface='some interface', count=1)
 276   >> sendp(Ether()/Dot1Q(vlan=123)/IP(src='176.80.50.6', dst='192.168.5.2'), \
 277            iface='some interface', count=1)
 278
 279 Terminal 1: output log::
 280
 281   received packet with src ip = 176.80.50.4 sent to queue 2
 282   received packet with src ip = 176.80.50.5 sent to queue 1
 283   received packet with src ip = 176.80.50.6 sent to queue 0
 284
 285 Terminal 1: running sample app flow rule enabled::
 286
 287   ./filter-program enabled
 288   [waiting for packets]
 289
 290 Terminal 2: running scapy::
 291
 292   $scapy
 293   welcome to Scapy
 294   >> sendp(Ether()/Dot1Q(vlan=123)/IP(src='176.80.50.4', dst='192.168.3.1'), \
 295            iface='some interface', count=1)
 296   >> sendp(Ether()/Dot1Q(vlan=50)/IP(src='176.80.50.5', dst='192.168.3.2'),  \
 297            iface='some interface', count=1)
 298   >> sendp(Ether()/Dot1Q(vlan=123)/IP(src='176.80.50.6', dst='192.168.5.2'), \
 299            iface='some interface', count=1)
 300
 301 Terminal 1: output log::
 302
 303   received packet with src ip = 176.80.50.4 sent to queue 3
 304   received packet with src ip = 176.80.50.5 sent to queue 1
 305   received packet with src ip = 176.80.50.6 sent to queue 3