cnat: flag to disable rsession

[vpp.git] / src / plugins / cnat / cnat.rst

diff --git a/src/plugins/cnat/cnat.rst b/src/plugins/cnat/cnat.rst
index 3cb08bc..b0426f3 100644 (file)
--- a/src/plugins/cnat/cnat.rst
+++ b/src/plugins/cnat/cnat.rst
@@ -9,7 +9,7 @@ Overview
 ________
 
 This plugin covers specific NAT use-cases that come mostly
-from the container networking world. On the contraty of the
+from the container networking world. On the contrary of the
 NAT concepts used for e.g. a home gateway, there is no notion
 of 'outside' and 'inside'. We handle Virtual (or Real) IPs and
 translations of the packets destined to them
@@ -33,9 +33,9 @@ that will store the packet rewrite to do and the one to undo
 until the flow is reset or a timeout is reached
 
 A ``session`` is a fully resolved 9-tuple of ``src_ip, src_port, dest_ip, dest_port, proto``
-to match incoming packets, and their new attributes ``new_src_ip, new_src_port, new_dest_ip, new_dest_port``. It allows for ``backend`` stickyness and a fast-path for established connections.
+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.
 
-These ``sessions`` expire after 30s for regular ``sessions`` and 1h for estabished
+These ``sessions`` expire after 30s for regular ``sessions`` and 1h for established
 TCP connections. These can be changed in vpp's configuration file
 
 .. code-block:: console
@@ -64,7 +64,7 @@ assigned to an interface
 
 
 If ``30.0.0.2`` is the address of an interface, we can use the following
-to do the same translation, and additionnaly change the source.
+to do the same translation, and additionally change the source.
 address with ``1.2.3.4``
 
 .. code-block:: console
@@ -75,17 +75,17 @@ To show existing translations and sessions you can use
 
 .. code-block:: console
 
-  cnat show session verbose
-  cant show translation
+  show cnat session verbose
+  show cnat translation
 
 
 SourceNATing outgoing traffic
 -----------------------------
 
-A independant part of the plugin allows changing the source address
+A independent part of the plugin allows changing the source address
 of outgoing traffic on a per-interface basis.
 
-In the following example, all traffic comming from ``tap0`` and NOT
+In the following example, all traffic coming from ``tap0`` and NOT
 going to ``20.0.0.0/24`` will be source NAT-ed with ``30.0.0.1``.
 On the way back the translation will be undone.
 
@@ -94,9 +94,17 @@ address assigned to an interface)
 
 .. code-block:: console
 
-  cnat snat with 30.0.0.1
-  cnat snat exclude 20.0.0.0/24
-  set interface feature tap0 ip4-cnat-snat arc ip4-unicast
+  set cnat snat-policy addr 30.0.0.1
+  set cnat snat-policy if-pfx
+  set cnat snat-policy if table include-v4 tap0
+  set cnat snat-policy prefix 20.0.0.0/24
+  set interface feature tap0 cnat-snat-ip4 arc ip4-unicast
+
+To show the enforced snat policies:
+
+.. code-block:: console
+
+  show cnat snat-policy
 
 Other parameters
 ----------------
@@ -105,7 +113,7 @@ In vpp's startup file, you can also configure the bihash sizes for
 
 * the translation bihash ``(proto, port) -> translation``
 * the session bihash ``src_ip, src_port, dest_ip, dest_port, proto -> new_src_ip, new_src_port, new_dest_ip, new_dest_port``
-* the snat bihash for searching ``snat exclude`` prefixes
+* the snat bihash for searching ``snat-policy`` excluded prefixes
 
 .. code-block:: console
 
@@ -126,19 +134,19 @@ This plugin is built to be extensible. For now two NAT types are defined, ``cnat
 * Session lookup : ``rv`` will be set to ``0`` if a session was found
 * Translation primitives ``cnat_translation_ip4`` based on sessions
 * A session creation primitive ``cnat_session_create``
+* A reverse session creation primitive ``cnat_rsession_create``
 
-Creating a session will also create a reverse session (for matching return traffic),
-and call a NAT node back that will perform the translation.
+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.
 
 Known limitations
 _________________
 
-This plugin is still under developpment, it lacks the following features :
+This plugin is still under development, it lacks the following features :
 * Load balancing doesn't support parametric probabilities
-* VRFs aren't supported. All rules apply to fib table 0 only
+* VRFs are not supported, all rules apply regardless of the FIB table.
 * Programmatic session handling (deletion, lifetime updates) aren't supported
-* ICMP is not yet supported
-* Traffic matching is only done based on ``(proto, dst_addr, dst_port)`` source matching isn't supported
+* translations (i.e. rewriting the destination address) only match on the three
+tuple ``(proto, dst_addr, dst_port)`` other matches are not supported
 * Statistics & session tracking are still rudimentary.