Documentation/networking/nf_flowtable.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ====================================
   4 Netfilter's flowtable infrastructure
   5 ====================================
   6
   7 This documentation describes the software flowtable infrastructure available in
   8 Netfilter since Linux kernel 4.16.
   9
  10 Overview
  11 --------
  12
  13 Initial packets follow the classic forwarding path, once the flow enters the
  14 established state according to the conntrack semantics (ie. we have seen traffic
  15 in both directions), then you can decide to offload the flow to the flowtable
  16 from the forward chain via the 'flow offload' action available in nftables.
  17
  18 Packets that find an entry in the flowtable (ie. flowtable hit) are sent to the
  19 output netdevice via neigh_xmit(), hence, they bypass the classic forwarding
  20 path (the visible effect is that you do not see these packets from any of the
  21 netfilter hooks coming after the ingress). In case of flowtable miss, the packet
  22 follows the classic forward path.
  23
  24 The flowtable uses a resizable hashtable, lookups are based on the following
  25 7-tuple selectors: source, destination, layer 3 and layer 4 protocols, source
  26 and destination ports and the input interface (useful in case there are several
  27 conntrack zones in place).
  28
  29 Flowtables are populated via the 'flow offload' nftables action, so the user can
  30 selectively specify what flows are placed into the flow table. Hence, packets
  31 follow the classic forwarding path unless the user explicitly instruct packets
  32 to use this new alternative forwarding path via nftables policy.
  33
  34 This is represented in Fig.1, which describes the classic forwarding path
  35 including the Netfilter hooks and the flowtable fastpath bypass.
  36
  37 ::
  38
  39                                          userspace process
  40                                           ^              |
  41                                           |              |
  42                                      _____|____     ____\/___
  43                                     /          \   /         \
  44                                     |   input   |  |  output  |
  45                                     \__________/   \_________/
  46                                          ^               |
  47                                          |               |
  48       _________      __________      ---------     _____\/_____
  49      /         \    /          \     |Routing |   /            \
  50   -->  ingress  ---> prerouting ---> |decision|   | postrouting |--> neigh_xmit
  51      \_________/    \__________/     ----------   \____________/          ^
  52        |      ^                          |               ^                |
  53    flowtable  |                     ____\/___            |                |
  54        |      |                    /         \           |                |
  55     __\/___   |                    | forward |------------                |
  56     |-----|   |                    \_________/                            |
  57     |-----|   |                 'flow offload' rule                       |
  58     |-----|   |                   adds entry to                           |
  59     |_____|   |                     flowtable                             |
  60        |      |                                                           |
  61       / \     |                                                           |
  62      /hit\_no_|                                                           |
  63      \ ? /                                                                |
  64       \ /                                                                 |
  65        |__yes_________________fastpath bypass ____________________________|
  66
  67                Fig.1 Netfilter hooks and flowtable interactions
  68
  69 The flowtable entry also stores the NAT configuration, so all packets are
  70 mangled according to the NAT policy that matches the initial packets that went
  71 through the classic forwarding path. The TTL is decremented before calling
  72 neigh_xmit(). Fragmented traffic is passed up to follow the classic forwarding
  73 path given that the transport selectors are missing, therefore flowtable lookup
  74 is not possible.
  75
  76 Example configuration
  77 ---------------------
  78
  79 Enabling the flowtable bypass is relatively easy, you only need to create a
  80 flowtable and add one rule to your forward chain::
  81
  82         table inet x {
  83                 flowtable f {
  84                         hook ingress priority 0; devices = { eth0, eth1 };
  85                 }
  86                 chain y {
  87                         type filter hook forward priority 0; policy accept;
  88                         ip protocol tcp flow offload @f
  89                         counter packets 0 bytes 0
  90                 }
  91         }
  92
  93 This example adds the flowtable 'f' to the ingress hook of the eth0 and eth1
  94 netdevices. You can create as many flowtables as you want in case you need to
  95 perform resource partitioning. The flowtable priority defines the order in which
  96 hooks are run in the pipeline, this is convenient in case you already have a
  97 nftables ingress chain (make sure the flowtable priority is smaller than the
  98 nftables ingress chain hence the flowtable runs before in the pipeline).
  99
 100 The 'flow offload' action from the forward chain 'y' adds an entry to the
 101 flowtable for the TCP syn-ack packet coming in the reply direction. Once the
 102 flow is offloaded, you will observe that the counter rule in the example above
 103 does not get updated for the packets that are being forwarded through the
 104 forwarding bypass.
 105
 106 More reading
 107 ------------
 108
 109 This documentation is based on the LWN.net articles [1]_\ [2]_. Rafal Milecki
 110 also made a very complete and comprehensive summary called "A state of network
 111 acceleration" that describes how things were before this infrastructure was
 112 mainlined [3]_ and it also makes a rough summary of this work [4]_.
 113
 114 .. [1] https://lwn.net/Articles/738214/
 115 .. [2] https://lwn.net/Articles/742164/
 116 .. [3] http://lists.infradead.org/pipermail/lede-dev/2018-January/010830.html
 117 .. [4] http://lists.infradead.org/pipermail/lede-dev/2018-January/010829.html