nat: adding docs for nat44-ed sub plugin

Type: docs

Change-Id: Icfa2bdc9367f8438b53da7c89caec263ed6ab056
Signed-off-by: Filip Varga <fivarga@cisco.com>
Signed-off-by: Dave Wallace <dwallacelf@gmail.com>

1 files changed, 729 insertions, 0 deletions

diff --git a/src/plugins/nat/nat44-ed/nat44_ed_doc.rst b/src/plugins/nat/nat44-ed/nat44_ed_doc.rst
new file mode 100644
index 00000000000..a54531c688c
--- /dev/null
+++ b/src/plugins/nat/nat44-ed/nat44_ed_doc.rst
@@ -0,0 +1,729 @@
+.. _NAT44_Endpoint_Dependent:
+
+.. toctree::
+
+NAT44-ED: NAT44 Endpoint Dependent
+==================================
+
+Introduction
+------------
+
+NAT44-ED is the IPv4 endpoint dependent network address translation
+plugin. The component implements an address and port-dependent mapping
+and address and port-dependent filtering NAT as described in
+`RFC4787 <https://tools.ietf.org/html/rfc4787>`__.
+
+The outside address and port (X1’:x1’) is reused for internal hosts
+(X:x) for different values of Y:y. A flow is matched by {source address,
+destination address, protocol, transport source port, transport
+destination port, fib index}. As long as all these are unique the
+mapping is valid. While a single outside address in theory allows for
+2^16 source ports \* 2^32 destination IP addresses \* 2^16 destination
+ports = 2^64 sessions, this number is much smaller in practice. Few
+destination ports are generally used (80, 443) and a fraction of the IP
+address space is available. The limitation is 2^16 bindings per outside
+IP address to a single destination address and port (Y:y).
+
+The implementation is split, a control-plane / slow-path and a
+data-plane / fast-path. Essentially acting as a flow router. The
+data-plane does a 6-tuple flow lookup (SA, DA, P, SP, DP, FIB) and on a
+match runs the per-flow packet handling instructions on the packet. On a
+flow lookup miss, the packet is punted to the slow-path, where depending
+on policy new sessions are created.
+
+The support set of packet handling instructions is ever-increasing.
+Currently, the implementation supports rewrite of SA, DA, SP, DP and TCP
+MSS. The fast-path also does connection tracking and expiry of older
+sessions.
+
+NAT44-ED uses 6
+tuple\ ``(src address, src port, dst address, dst port, protocol and fib)``\ for
+matching communication.
+
+Structure
+~~~~~~~~~
+
+1) Dynamic NAT
+
+-  also called PAT (Port Address Translation)
+-  supports port overloading
+
+2) Static NAT
+
+-  types of Static NAT:
+
+   a) identity mapping
+
+   -  exceptions to translations
+
+   b) static mapping
+
+   -  supported features:
+
+      1. address only mapping
+
+      -  one to one translation without ports
+
+      2. twice-nat
+
+      -  double-nat, translation of source and destination
+
+      3. self-twice-nat
+
+      -  double nat, translation of source and destination, where
+         external host address is the same as local host address
+
+      4. out2in-only mapping
+
+      -  session is created only from outside interface (out2in feature)
+
+   c) load balanced static mapping
+
+   -  translates one frontend (``addr``:``port``) to multiple backends
+      (``addr``:``port``)
+
+3) Interfaces
+
+a) inside interface (in2out feature) - local to external network
+   translation - feature is before ip4-lookup
+b) outside interface (out2in feature) - external to local network
+   translation - feature is before ip4-lookup
+c) inside & outside interface (classify feature) - local or external
+   network translation - correct type of translation is determined per
+   communication - feature is before ip4-lookup
+d) output interface (output feature) - used for post routing translation
+   - feature is after ip4-lookup
+
+4) Addresses
+
+a) interface address - automatically managed external address - first
+   address of VPP interface
+b) pool address - range of external addresses
+
+5) Logging and Accounting
+
+a) ipfix logging
+b) syslog
+
+6) Miscellaneous Features
+
+a) inter-vrf translation control 1. basic
+
+   -  nat44 plugin enable inside-vrf / outside-vrf
+   -  inside/outside interface vrf’s
+
+      2. advanced
+
+   -  vrf table routing feature
+
+b) udp/tcp/icmp timeouts - configurable timeouts for these protocols
+c) session limiting 1. basic (plugin enable [sessions ] 2. advanced
+   (per vrf table / global limiting)
+d) mss-clamping - MSS (maximum segment size) is by default determined by
+   egress interface MTU (maximum transmission unit) size - used to lower
+   MSS value in VPN tunnel scenarios where additional headers can
+   enlarge the packet beyond MTU causing drops
+e) hairpinning - hosts on the same lan segment communicating via
+   external address
+f) forwarding - if enabled translation only occurs if active session or
+   static configuration exist, rest of the traffic is passed without
+   being translated
+
+Session Table
+-------------
+
+Session table exists per thread and contains pool of sessions that can
+be either expired or not expired. NAT44-ED plugin doesn’t use scavenging
+for clearing expired sessions. Rather then using scavenging plugin uses
+LRU doubly-linked list. LRU contains ordered list of sessions indices.
+Head of the list contains last updated session. Each session holds
+record of the LRU head (tcp transitory, tcp established, udp, icmp or
+unknown lru head). Because of this plugin can reach maximum number of
+sessions without requirement to clear old sessions. During session
+creation if a maximum number of sessions was reached LRU head is
+checked. Expired head record gets deleted and a new session gets
+created. For better performance LRU head records exist. Each time a new
+packet is received session index gets moved to the tail of LRU list.
+
+Terminology
+-----------
+
+IN2OUT (inside to outside translation) OUT2IN (outside to inside
+translation)
+
+NAT (network address translation) PAT (port address translation) MSS
+(maximum segment size) MTU (maximum transmission unit) VRF (virtual
+routing and forwarding)
+
+HAIRPINNING
+
+Dynamic NAT (Minimal Required Configuration)
+--------------------------------------------
+
+::
+
+       +-------------+
+       | 10.0.0.0/24 |
+       +-------------+
+              |
+   +----------------------+
+   | GigabitEthernet0/8/0 |
+   +----------------------+
+   +----------------------+
+   | GigabitEthernet0/a/0 |
+   +----------------------+
+              |
+       +-------------+
+       | 10.0.1.0/24 |
+       +-------------+
+
+1) enable nat plugin
+
+..
+
+   nat44 enable sessions 10000
+
+2) configure NAT interfaces, two options:
+
+a) add inside NAT interface on local VPP interface, add outside NAT
+   interface on external VPP interface
+
+..
+
+   set interface nat44 in GigabitEthernet0/8/0 out GigabitEthernet0/a/0
+
+b) add output NAT interface on external VPP interface
+
+..
+
+   set interface nat44 in GigabitEthernet0/a/0 output-feature
+
+3) configure NAT address
+
+a) add external address range
+
+..
+
+   nat44 add address 10.0.1.1
+
+b) add external VPP interface address
+
+..
+
+   nat44 add interface address GigabitEthernet0/a/0
+
+Static NAT
+----------
+
+Identity Mapping
+~~~~~~~~~~~~~~~~
+
+   nat44 add identity mapping ``ip4-addr``\ \|external ``interface``
+   [``protocol`` ``port``] [vrf ``table-id``] [del]
+
+Static Mapping
+~~~~~~~~~~~~~~
+
+   nat44 add static mapping tcp|udp|icmp local ``addr``
+   [``port|icmp-echo-id``] external ``addr`` [``port|icmp-echo-id``]
+   [vrf ``table-id``] [twice-nat|self-twice-nat] [out2in-only] [exact
+   ``pool-addr``] [del]
+
+Load Balanced Static Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   nat44 add load-balancing back-end protocol tcp|udp external
+   ``addr``:``port`` local ``addr``:``port`` [vrf ``table-id``]
+   probability ``n`` [del]
+
+..
+
+   nat44 add load-balancing static mapping protocol tcp|udp external
+   ``addr``:``port`` local ``addr``:``port`` [vrf ``table-id``]
+   probability ``n`` [twice-nat|self-twice-nat] [out2in-only] [affinity
+   ``timeout-seconds``] [del]
+
+Interfaces
+----------
+
+Inside Interface
+~~~~~~~~~~~~~~~~
+
+::
+
+        NAT INSIDE IF
+   +----------------------+
+   | GigabitEthernet0/8/0 |
+   +----------------------+
+
+..
+
+   set interface nat44 in GigabitEthernet0/8/0 [del]
+
+NAT inside interface is used for translating local to external
+communication. Translates Dynamic and Static NAT traffic. If no matching
+session is found a new session is created for both Dynamic NAT and
+Static NAT. Dynamic NAT sessions can get created only on inside
+interface.
+
+Outside Interface
+~~~~~~~~~~~~~~~~~
+
+::
+
+        NAT OUTSIDE IF
+   +----------------------+
+   | GigabitEthernet0/a/0 |
+   +----------------------+
+
+..
+
+   set interface nat44 out GigabitEthernet0/a/0 [del]
+
+NAT outside interface is used for translating external to local
+communication. Translates Dynamic and Static NAT traffic. New session
+gets created only if no matching session is found and matching Static
+NAT configuration exists.
+
+Inside & Outside Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+       NAT IN AND OUT IF
+   +----------------------+
+   | GigabitEthernet0/8/0 |
+   +----------------------+
+       NAT IN AND OUT IF
+   +----------------------+
+   | GigabitEthernet0/a/0 |
+   +----------------------+
+
+..
+
+   set interface nat44 in GigabitEthernet0/8/0 out GigabitEthernet0/8/0
+   [del]
+
+   set interface nat44 in GigabitEthernet0/a/0 out GigabitEthernet0/a/0
+   [del]
+
+If one VPP interface is configured both as inside and outside NAT
+interface then classification feature is used. By default NAT inside
+interface uses in2out feature and NAT outside uses out2in feature.
+Classification feature determines if the communication should be passed
+to in2out feature or to out2in feature. Traffic will get passed to
+out2in feature if destination address is one of NAT addresses or a
+static mapping in out2in direction flow matches this communication. By
+default all traffic is passed to in2out feature.
+
+Output Interface
+~~~~~~~~~~~~~~~~
+
+::
+
+       +-------------+          +-------------+
+       | 10.0.2.0/24 |          | 10.0.3.0/24 |
+       +-------------+          +-------------+
+              |                        |
+   +----------------------+ +----------------------+
+   | GigabitEthernet0/7/0 | | GigabitEthernet0/8/0 |
+   +----------------------+ +----------------------+
+                     NAT OUTPUT IF
+               +----------------------+
+               | GigabitEthernet0/a/0 |
+               +----------------------+
+                      +----------+
+                      | 10.0.1.1 |
+                      +----------+
+                           |
+                     +-------------+
+                     | 10.0.1.0/24 |
+                     +-------------+
+
+..
+
+   set interface nat44 in GigabitEthernet0/a/0 output-feature [del]
+
+NAT output interface acts as both inside and outside interfaces. Inside
+rules apply for all egress communication on VPP interface and outside
+rules apply for all ingress communication. Compared to inside/outside
+NAT configuration method non of the local interfaces require to be
+configured as inside NAT interfaces. Translation only occurs after
+routing decision has been made and just before leaving NAT output
+interface. In above example all traffic destined for 10.0.1.0/24 from
+10.0.2.0/24 or 10.0.3.0/24 will get translated. NAT output interface
+acts as post-routing feature.
+
+Addresses
+---------
+
+Interface Address
+~~~~~~~~~~~~~~~~~
+
+   nat44 add interface address ``interface`` `twice-nat <#twice-nat>`__
+   [del]
+
+NAT interface address is a standard external pool address that gets auto
+added upon resolving first VPP interface address. Supports both standard
+address and twice-nat address. Twice-nat address is used in conjunction
+with static mapping twice-nat and self-twice-nat feature.
+
+Pool Address
+~~~~~~~~~~~~
+
+   nat44 add address ``ip4-range-start`` [- ``ip4-range-end``]
+   [tenant-vrf ``vrf-id``] `twice-nat <#twice-nat>`__ [del]
+
+Statically configured address or range of addresses that supports both
+standard and twice-nat address. Specifying vrf-id lets user assign
+address/addresses to specific NAT inside interfaces that belong to the
+same vrf table.
+
+Logging
+-------
+
+   nat set logging level ``level``
+
+Configuration of logging level is used only for internal VPP logging.
+
+   nat ipfix logging [domain ``domain-id``] [src-port ``port``]
+   [disable]
+
+Both syslog and ipfix support connection tracking capabilities. Session
+creation, session deletion, maximum sessions exceeded among other things
+are logged by syslog and ipfix.
+
+Miscellaneous
+-------------
+
+VRFs
+~~~~
+
+::
+
+            VRF 0                    VRF 1
+       +-------------+          +-------------+
+       | 10.0.2.0/24 |          | 10.0.3.0/24 |
+       +-------------+          +-------------+
+              |                        |
+        NAT INSIDE IF            NAT INSIDE IF
+   +----------------------+  +----------------------+
+   | GigabitEthernet0/7/0 |  | GigabitEthernet0/8/0 |
+   +----------------------+  +----------------------+
+        NAT OUTSIDE IF           NAT OUTSIDE IF
+   +----------------------+  +----------------------+
+   | GigabitEthernet0/a/0 |  | GigabitEthernet0/b/0 |
+   +----------------------+  +----------------------+
+            VRF 2                      VRF 3
+              |                          |
+              +--------------------------+
+                           |
+        +------------+------------+------------+
+        |            |            |            |
+   +----------+ +----------+ +----------+ +----------+
+   | 10.0.0.1 | | 10.0.0.2 | | 10.0.1.1 | | 10.0.1.2 |
+   +----------+ +----------+ +----------+ +----------+
+    VRF 0 POOL   VRF 1 POOL   VRF 0 POOL   VRF 1 POOL
+
+..
+
+   nat44 add address ``ip4-addr`` [tenant-vrf ``vrf-id``] [del]
+
+   nat44 plugin enable inside-vrf ``vrf-id`` outside-vrf ``vrf-id``
+   [disable]",
+
+Default behavior
+^^^^^^^^^^^^^^^^
+
+By design NAT supports passing communication between VRFs. Passing
+communication between multiple different VRFs is also supported (GE0/7/0
+-> GE0/b/0, GE0/8/0 -> GE0/a/0).
+
+NAT pool address tenant-vrf configuration parameter is used to constrain
+pool address to specific inside VRF. Example communication (in the above
+diagram): 1) from GE0/7/0 -> GE0/b/0 would choose 10.0.1.1 pool address
+2) from GE0/8/0 -> GE0/b/0 would choose 10.0.1.2 pool address
+
+Plugin enable parameters inside-vrf and outside-vrf are used as follows:
+
+Both ``inside-vrf`` and ``outside-vrf`` configuration parameters are
+used in conjunction with Static NAT, inside-vrf is only used for Static
+NAT.
+
+inside VRF: - used only in conjunction with static mappings - default
+inside VRF parameter is used in in2out feature to lookup static mapping
+if mapping can’t be found by inside interface VRF - used as default when
+adding static mappings as in2out vrf
+
+outside VRF: - used in conjunction with static mappings - secondary
+option for looking up static mappings in in2out feature based on outside
+VRF - used as default destination vrf in in2out feature during session
+creation if non of outside interfaces can resolve destination IP address
+
+Session creation default behavior (in2out only): - ingress interface fib
+is used as inside fib - Outside fib is chosen based on ability to
+resolve destination address in one of the outside interface networks. if
+there is no such network that is able to resolve destination a default
+outside fib (outside vrf index) is used.
+
+Default behavior enables use of multiple outside and inside fibs with
+some limitations. The limitation in the default behavior is that if each
+interface belonging to different fib contains default gateway every time
+first interface network fib gets used as outside fib index during
+session creation.
+
+VRF tables
+^^^^^^^^^^
+
+   nat44 vrf table [add|del] ``vrf-id``
+
+..
+
+   nat44 vrf route [add|del] table ``vrf-id`` ``vrf-id``
+
+VRF tables change the default behavior of working with inter-vrf
+communication. Adding empty VRF table disables passing communication
+between VRFs. Adding additional routes to the table makes destination
+VRF decision making algorithm do lookups into these tables. During
+session creation destination VRF in in2out feature is resolved by
+traversing VRF routes in the matching VRF table. If VRF route resolves
+destination IPv4 address then this VRF gets used. If non VRF route can
+resolve destination IPv4 address If VRF route can’t be found source VRF
+will be used. Priority of VRF routes is based on order of configuration.
+
+Timeouts
+~~~~~~~~
+
+   set nat timeout [udp ``sec`` \| tcp-established ``sec``
+   tcp-transitory ``sec`` \| icmp ``sec`` \| reset]
+
+Session Limiting
+~~~~~~~~~~~~~~~~
+
+   nat44 enable sessions ``max-number``
+
+Maximum number of sessions value is used on per-thread (per-worker)
+basis.
+
+   set nat44 session limit ``limit`` [vrf ``table-id``]
+
+Per-vrf session limiting makes it possible to split maximum number of
+sessions between different VRFs.
+
+MSS Clamping
+~~~~~~~~~~~~
+
+   nat mss-clamping ``mss-value``\ \|disable
+
+Forwarding
+~~~~~~~~~~
+
+   nat44 forwarding enable|disable
+
+Additional Configuration Commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   | set nat frame-queue-nelts ``number``
+   | set nat workers ``workers-list``
+   | nat44 del session in|out ``addr``:``port`` tcp|udp|icmp [vrf
+     ``id``] [external-host ``addr``:``port``]
+
+Show commands
+^^^^^^^^^^^^^
+
+::
+
+   show nat workers
+   show nat timeouts
+   show nat44 summary
+   show nat44 sessions
+   show nat44 addresses
+   show nat mss-clamping
+   show nat44 interfaces
+   show nat44 vrf tables
+   show nat44 hash tables
+   nat44 show static mappings
+   show nat44 interface address
+
+Configuration Examples
+----------------------
+
+TWICE-NAT
+~~~~~~~~~
+
+Twice NAT lets you translate both the source and destination address in
+a single rule. Currently, twice NAT44 is supported only for local
+network service session initiated from outside network. Twice NAT static
+mappings can only get initiated (create sessions) from outside network.
+
+Topology
+^^^^^^^^
+
+::
+
+   +--------------------------+
+   | 10.0.0.2/24 (local host) |
+   +--------------------------+
+               |
+   +---------------------------------+
+   | 10.0.0.1/24 (eth0) (nat inside) |
+   | 20.0.0.1/24 (eth1) (nat outside)|
+   +---------------------------------+
+               |
+   +---------------------------+
+   | 20.0.0.2/24 (remote host) |
+   +---------------------------+
+
+In this example traffic will be initiated from remote host. Remote host
+will be accessing local host via twice-nat mapping.
+
+Translation will occur as follows:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+outside to inside translation:
+
+
+   | src address: 20.0.0.2 -> 192.168.160.101
+   | dst address: 20.0.0.1 -> 10.0.0.2
+
+inside to outside translation:
+
+
+   | src address: 10.0.0.2 -> 20.0.0.1
+   | dst address: 192.168.160.101 -> 20.0.0.2
+
+Configuration
+^^^^^^^^^^^^^
+
+Enable nat44-ed plugin:
+
+
+::
+
+   nat44 enable sessions 1000
+
+Configure inside interface:
+
+
+::
+
+   set int state eth0 up
+   set int ip address eth0 10.0.0.1/24
+   set int nat44 in eth0
+
+Configure outside interface:
+
+
+::
+
+   set int state eth1 up
+   set int ip address eth1 20.0.0.1/24
+   set int nat44 out eth1
+
+Configure nat address pools:
+
+
+::
+
+   nat44 add address 20.0.0.1
+   nat44 add address 192.168.160.101 twice-nat
+
+-  alternatively we could use ``nat44 add interface address eth1``
+-  both pools are required
+-  pool ``20.0.0.1`` is used for out2in incoming traffic
+-  special twice-nat pool ``192.168.160.101`` is used for secondary
+   translation
+
+Finally, add twice-nat mapping:
+
+
+   nat44 add static mapping tcp local 10.0.0.2 5201 external 20.0.0.1
+   5201 twice-nat
+
+SELF TWICE-NAT
+~~~~~~~~~~~~~~
+
+Self twice NAT works similar to twice NAT with few exceptions. Self
+twice NAT is a feature that lets client and service running on the same
+host to communicate via NAT device. This means that external address is
+the same address as local address. Self twice NAT static mappings can
+only get initiated (create sessions) from outside network.
+
+.. _topology-self-twice-nat:
+
+Topology
+^^^^^^^^
+
+::
+
+   +--------------------------+
+   | 10.0.0.2/24 (local host) |
+   +--------------------------+
+               |
+   +-------------------------------------------+
+   | 10.0.0.1/24 (eth0) (nat inside & outside) |
+   +-------------------------------------------+
+
+In this example traffic will be initiated from local host. Local host
+will be accessing itself via self-twice-nat mapping.
+
+.. _translation-will-occur-as-follows-1:
+
+Translation will occur as follows:
+''''''''''''''''''''''''''''''''''
+
+.. _outside-to-inside-translation-1:
+
+outside to inside translation:
+
+
+   | src address: 10.0.0.2 -> 192.168.160.101
+   | dst address: 10.0.0.1 -> 10.0.0.2
+
+.. _inside-to-outside-translation-1:
+
+inside to outside translation:
+
+
+   | src address: 10.0.0.2 -> 10.0.0.1
+   | dst address: 192.168.160.101 -> 10.0.0.2
+
+.. _configuration-1:
+
+Configuration
+^^^^^^^^^^^^^
+
+.. _enable-nat44-ed-plugin-1:
+
+Enable nat44-ed plugin:
+
+
+::
+
+   nat44 enable sessions 1000
+
+Configure NAT interface:
+
+
+::
+
+   set int state eth0 up
+   set int ip address eth0 10.0.0.1/24
+   set int nat44 in eth0
+   set int nat44 out eth0
+
+.. _configure-nat-address-pools-1:
+
+Configure nat address pools:
+
+
+::
+
+   nat44 add address 10.0.0.1
+   nat44 add address 192.168.160.101 twice-nat
+
+Finally, add self-twice-nat mapping:
+
+
+   nat44 add static mapping tcp local 10.0.0.2 5201 external 10.0.0.1
+   5201 self-twice-nat