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 show cnat 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 set cnat snat-policy addr 30.0.0.1
98 set cnat snat-policy if-pfx
99 set cnat snat-policy if table include-v4 tap0
100 set cnat snat-policy prefix 20.0.0.0/24
101 set interface feature tap0 cnat-snat-ip4 arc ip4-unicast
103 To show the enforced snat policies:
105 .. code-block:: console
107 show cnat snat-policy
112 In vpp's startup file, you can also configure the bihash sizes for
114 * the translation bihash ``(proto, port) -> translation``
115 * the session bihash ``src_ip, src_port, dest_ip, dest_port, proto -> new_src_ip, new_src_port, new_dest_ip, new_dest_port``
116 * the snat bihash for searching ``snat-policy`` excluded prefixes
118 .. code-block:: console
121 translation-db-memory 64K
122 translation-db-buckets 1024
124 session-db-buckets 1024
132 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 :
134 * Session lookup : ``rv`` will be set to ``0`` if a session was found
135 * Translation primitives ``cnat_translation_ip4`` based on sessions
136 * A session creation primitive ``cnat_session_create``
137 * A reverse session creation primitive ``cnat_rsession_create``
139 Creating a session will also create reverse session matching return traffic unless told otherwise by setting ``CNAT_TR_FLAG_NO_RETURN_SESSION`` on the translation. This will call the NAT nodes on the return flow and perform the inverse translation.
144 This plugin is still under development, it lacks the following features :
145 * Load balancing doesn't support parametric probabilities
146 * VRFs are not supported, all rules apply regardless of the FIB table.
147 * Programmatic session handling (deletion, lifetime updates) aren't supported
148 * translations (i.e. rewriting the destination address) only match on the three
149 tuple ``(proto, dst_addr, dst_port)`` other matches are not supported
150 * Statistics & session tracking are still rudimentary.