11 This plugin covers specific NAT use-cases that come mostly
12 from the container networking world. On the contrary of the
13 NAT concepts used for e.g. a home gateway, there is no notion
14 of 'outside' and 'inside'. We handle Virtual (or Real) IPs and
15 translations of the packets destined to them
20 Setting up the NAT will consist in the creation of a ``translation``
21 that has several backends. A ``translation`` is 3-tuple containing :
22 a fully qualified IP address a port and a protocol. All packets
23 destined to it (ip, port) will then choose one of the backends,
24 and follow its rewrite rules.
26 A ``backend`` consists of four rewrites components (source & destination
27 address, source & destination port) that shall be applied to packets
28 on the way in, and reverted on the way back.
30 Backends are equally load-balanced with a flow hash. The choice
31 of a ``backend`` for a flow will trigger the creation of a NAT ``session``,
32 that will store the packet rewrite to do and the one to undo
33 until the flow is reset or a timeout is reached
35 A ``session`` is a fully resolved 9-tuple of ``src_ip, src_port, dest_ip, dest_port, proto``
36 to match incoming packets, and their new attributes ``new_src_ip, new_src_port, new_dest_ip, new_dest_port``. It allows for ``backend`` stickiness and a fast-path for established connections.
38 These ``sessions`` expire after 30s for regular ``sessions`` and 1h for established
39 TCP connections. These can be changed in vpp's configuration file
41 .. code-block:: console
48 Traffic is matched by inserting FIB entries, that are represented
49 by a ``client``. These maintain a refcount of the number of ``sessions``
50 and/or ``translations`` depending on them and be cleaned up when
56 In this example, all packets destined to ``30.0.0.2:80`` will be
57 rewritten so that their destination IP is ``20.0.0.1`` and destination
58 port ``8080``. Here ``30.0.0.2`` has to be a virtual IP, it cannot be
59 assigned to an interface
61 .. code-block:: console
63 cnat translation add proto TCP vip 30.0.0.2 80 to ->20.0.0.1 8080
66 If ``30.0.0.2`` is the address of an interface, we can use the following
67 to do the same translation, and additionally change the source.
68 address with ``1.2.3.4``
70 .. code-block:: console
72 cnat translation add proto TCP real 30.0.0.2 80 to 1.2.3.4->20.0.0.1 8080
74 To show existing translations and sessions you can use
76 .. code-block:: console
78 cnat show session verbose
82 SourceNATing outgoing traffic
83 -----------------------------
85 A independent part of the plugin allows changing the source address
86 of outgoing traffic on a per-interface basis.
88 In the following example, all traffic coming from ``tap0`` and NOT
89 going to ``20.0.0.0/24`` will be source NAT-ed with ``30.0.0.1``.
90 On the way back the translation will be undone.
92 NB: ``30.0.0.1`` should be and address known to the FIB (e.g. the
93 address assigned to an interface)
95 .. code-block:: console
97 cnat snat with 30.0.0.1
98 cnat snat exclude 20.0.0.0/24
99 set interface feature tap0 cnat-snat-ip4 arc ip4-unicast
104 In vpp's startup file, you can also configure the bihash sizes for
106 * the translation bihash ``(proto, port) -> translation``
107 * the session bihash ``src_ip, src_port, dest_ip, dest_port, proto -> new_src_ip, new_src_port, new_dest_ip, new_dest_port``
108 * the snat bihash for searching ``snat exclude`` prefixes
110 .. code-block:: console
113 translation-db-memory 64K
114 translation-db-buckets 1024
116 session-db-buckets 1024
124 This plugin is built to be extensible. For now two NAT types are defined, ``cnat_node_vip.c`` and ``cnat_node_snat.c``. They both inherit from ``cnat_node.h`` which provides :
126 * Session lookup : ``rv`` will be set to ``0`` if a session was found
127 * Translation primitives ``cnat_translation_ip4`` based on sessions
128 * A session creation primitive ``cnat_session_create``
130 Creating a session will also create a reverse session (for matching return traffic),
131 and call a NAT node back that will perform the translation.
136 This plugin is still under development, it lacks the following features :
137 * Load balancing doesn't support parametric probabilities
138 * VRFs aren't supported. All rules apply to fib table 0 only
139 * Programmatic session handling (deletion, lifetime updates) aren't supported
140 * ICMP is not yet supported
141 * Traffic matching is only done based on ``(proto, dst_addr, dst_port)`` source matching isn't supported
142 * Statistics & session tracking are still rudimentary.