nat: add overview description about Network Address Translation

1 files changed, 287 insertions, 37 deletions

diff --git a/docs/nat.rst b/docs/nat.rst
index 916f6aba..8aafe300 100644
--- a/docs/nat.rst
+++ b/docs/nat.rst
@@ -4,22 +4,267 @@
 NAT
 ###
 
+:abbr:`NAT (Network Address Translation)` is a common method of remapping one
+IP address space into another by modifying network address information in the
+IP header of packets while they are in transit across a traffic routing device.
+The technique was originally used as a shortcut to avoid the need to readdress
+every host when a network was moved. It has become a popular and essential tool
+in conserving global address space in the face of IPv4 address exhaustion. One
+Internet-routable IP address of a NAT gateway can be used for an entire private
+network.
+
+IP masquerading is a technique that hides an entire IP address space, usually
+consisting of private IP addresses, behind a single IP address in another,
+usually public address space. The hidden addresses are changed into a single
+(public) IP address as the source address of the outgoing IP packets so they
+appear as originating not from the hidden host but from the routing device
+itself. Because of the popularity of this technique to conserve IPv4 address
+space, the term NAT has become virtually synonymous with IP masquerading.
+
+As network address translation modifies the IP address information in packets,
+NAT implementations may vary in their specific behavior in various addressing
+cases and their effect on network traffic. The specifics of NAT behavior are
+not commonly documented by vendors of equipment containing NAT implementations.
+
+The computers on an internal network can use any of the addresses set aside by
+the :abbr:`IANA (Internet Assigned Numbers Authority)` for private addressing
+(see :rfc:`1918`). These reserved IP addresses are not in use on the Internet,
+so an external machine will not directly route to them. The following addresses
+are reserved for private use:
+
+* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8)
+* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12)
+* 192.168.0.0 to 192.168.255.255 (CIDR: 192.268.0.0/16)
+
+
+If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses :rfc:`1918`
+address space to number customer gateways, the risk of address collision, and
+therefore routing failures, arises when the customer network already uses an
+:rfc:`1918` address space.
+
+This prompted some ISPs to develop a policy within the :abbr:`ARIN (American
+Registry for Internet Numbers)` to allocate new private address space for CGNs,
+but ARIN deferred to the IETF before implementing the policy indicating that
+the matter was not a typical allocation issue but a reservation of addresses
+for technical purposes (per :rfc:`2860`).
+
+IETF published :rfc:`6598`, detailing a shared address space for use in ISP
+CGN deployments that can handle the same network prefixes occurring both on
+inbound and outbound interfaces. ARIN returned address space to the :abbr:`IANA
+(Internet Assigned Numbers Authority)` for this allocation.
+
+The allocated address block is 100.64.0.0/10.
+
+Devices evaluating whether an IPv4 address is public must be updated to
+recognize the new address space. Allocating more private IPv4 address space for
+NAT devices might prolong the transition to IPv6.
+
+Overview
+========
+
+Different NAT Types
+-------------------
+
 .. _source-nat:
 
-Source NAT
-==========
+Source NAT (SNAT)
+^^^^^^^^^^^^^^^^^
+
+Source NAT is the most common form of NAT and is typically referred to simply
+as NAT. To be more correct, what most people refer to as NAT is actually the
+process of :abbr:`PAT (Port Address Translation)`, or NAT Overload. SNAT is
+typically used by internal users/private hosts to access the Internet - the
+source address is translated and thus kept private.
+
+.. _destination-nat:
+
+Destination NAT (DNAT)
+^^^^^^^^^^^^^^^^^^^^^^
+
+While :ref:`source-nat` changes the source address of packets, DNAT changes
+the destination address of packets passing through the router. DNAT is
+typically used when an external (public) host needs to initiate a session with
+an internal (private) host. A customer needs to access a private service
+behind the routers public IP. A connection is established with the routers
+public IP address on a well known port and thus all traffic for this port is
+rewritten to address the internal (private) host.
+
+.. _bidirectional-nat:
+
+Bidirectional NAT
+^^^^^^^^^^^^^^^^^
+
+This is a common szenario where both :ref:`source-nat` and
+:ref:`destination-nat` are configured at the same time. It's commonly used then
+internal (private) hosts need to establish a connection with external resources
+and external systems need to acces sinternal (private) resources.
+
+NAT, Routing, Firewall Interaction
+----------------------------------
+
+There is a very nice picture/explanation in the Vyatta documentation which
+should be rewritten here.
+
+NAT Ruleset
+-----------
+
+:abbr:`NAT (Network Address Translation)` is configured entirely on a series
+of so called `rules`. Rules are numbered and evaluated by the underlaying OS
+in numerical order! The rule numbers can be changes by utilizing the
+:cfgcmd:`rename` and :cfgcmd`copy` commands.
+
+.. note:: Changes to the NAT system only affect newly established connections.
+   Already establiushed ocnnections are not affected.
+
+.. hint:: When designing your NAT ruleset leave some space between consecutive
+   rules for later extension. Your ruleset could start with numbers 10, 20, 30.
+   You thus can later extend the ruleset and place new rules between existing
+   ones.
+
+Rules will be created for both :ref:`source-nat` and :ref:`destination-nat`.
+
+For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and
+:ref:`destination-nat` needs to be created.
+
+.. _traffic-filters:
+
+Traffic Filters
+---------------
+
+Traffic Filters are used to control which packets will have the defined NAT
+rules applied. Five different filters can be applied within a NAT rule
+
+* **outbound-interface** - applicable only to :ref:`source-nat`. It configures
+  the interface which is used for the outside traffic that this translation rule
+  applies to.
+
+  Example:
+
+  .. code-block:: none
+
+    set nat source rule 20 outbound-interface eth0
+
+* **inbound-interface** - applicable only to :ref:`destination-nat`. It
+  configures the interface which is used for the inside traffic the the
+  translation rule applies to.
+
+  Example:
+
+  .. code-block:: none
+
+    set nat destination rule 20 inbound-interface eth1
+
+* **protocol** - specify which types of protocols this translation rule applies
+  to. Only packets matching the specified protocol are NATed. By default this
+  applies to `all` protocols.
+
+  Example:
+
+  * Set SNAT rule 20 to only NAT TCP and UDP packets
+  * Set DNAT rule 20 to only NAT UDP packets
+
+  .. code-block:: none
+
+    set nat source rule 20 protocol tcp_udp
+    set nat destination rule 20 protocol udp
+
+* **source** - specifies which packets the NAT translation rule applies to
+  based on the packets source IP address and/or source port. Only matching
+  packets are considered for NAT.
+
+  Example:
+
+  * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 network
+  * Set SNAT rule 30 to only NAT packets arriving from the 192.0.3.0/24 network
+    with a source port of 80 and 443
+
+  .. code-block:: none
+
+    set nat source rule 20 source address 192.0.2.0/24
+    set nat source rule 30 source address 192.0.3.0/24
+    set nat source rule 30 source port 80,443
 
-Source NAT is typically referred to simply as NAT. To be more correct, what
-most people refer to as NAT is actually the process of **Port Address
-Translation (PAT)**, or **NAT Overload**. The process of having many internal
-host systems communicate to the Internet using a single or subset of IP
-addresses.
+
+* **destination** - specify which packets the translation will be applied to,
+  only based on the destination address and/or port number configured.
+
+  .. note:: If no destination is specified the rule will match on any
+     destination address and port.
+
+  Example:
+
+  * Configure SNAT rule (40) to only NAT packets with a destination address of
+    192.0.2.1.
+
+  .. code-block:: none
+
+    set nat source rule 40 destination address 192.0.2.1
+
+
+Address Conversion
+------------------
+
+Every NAT rule has a translation command defined. The address defined for the
+translation is the addrass used when the address information in a packet is
+replaced.
+
+Source Address
+^^^^^^^^^^^^^^
+
+For :ref:`source-nat` rules the packets source address will be replaced with
+the address specified in the translation command. A port translation can also
+be specified and is part of the translation address.
+
+.. note:: The translation address must be set to one of the available addresses
+   on the configured `outbound-interface` or it must be set to `masquerade`
+   which will use the primary IP address of the `outbound-interface` as its
+   translation address.
+
+.. note:: When using NAT for a large number of host systems it recommended that
+   a minimum of 1 IP address is used to NAT every 256 private host systems.
+   This is due to the limit of 65,000 port numbers available for unique
+   translations and a reserving an average of 200-300 sessions per host system.
+
+Example:
+
+* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20
+* Use address `masquerade` (the interfaces primary address) on rule 30
+* For a large amount of private machines behind the NAT your address pool might
+  to be bigger. Use any address in the range 100.64.0.10 - 100.64.0.20 on SNAT
+  rule 40 when doing the translation
+
+
+.. code-block:: none
+
+  set nat source rule 20 translation address 100.64.0.1
+  set nat source rule 30 translation address 'masquerade'
+  set nat source rule 40 translation address 100.64.0.10-100.64.0.20
+
+
+Destination Address
+^^^^^^^^^^^^^^^^^^^
+
+For :ref:`destination-nat` rules the packets destination address will be
+replaced by the specified address in the `translation address` command.
+
+Example:
+
+* DNAT rule 10 replaces the destination address of an inbound packet with
+  192.0.2.10
+
+.. code-block:: none
+
+  set nat destination rule 10 translation address 192.0.2.10
+
+
+Configuration Examples
+======================
 
 To setup SNAT, we need to know:
 
-* The internal IP addresses we want to translate;
-* The outgoing interface to perform the translation on;
-* The external IP address to translate to.
+* The internal IP addresses we want to translate
+* The outgoing interface to perform the translation on
+* The external IP address to translate to
 
 In the example used for the Quick Start configuration above, we demonstrate
 the following configuration:
@@ -138,7 +383,7 @@ Which results in a configuration of:
   }
 
 Destination NAT
-===============
+---------------
 
 DNAT is typically referred to as a **Port Forward**. When using VyOS as a NAT
 router and firewall, a common configuration task is to redirect incoming
@@ -231,7 +476,7 @@ This would generate the following configuration:
   additional rules to permit inbound NAT traffic.
 
 1-to-1 NAT
-==========
+----------
 
 Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT
 configuration, both DNAT and SNAT are used to NAT all traffic from an external
@@ -245,9 +490,6 @@ internal IP to a reserved external IP. This dedicates an external IP address
 to an internal IP address and is useful for protocols which don't have the
 notion of ports, such as GRE.
 
-1-to-1 NAT example
-------------------
-
 Here's an extract of a simple 1-to-1 NAT configuration with one internal and
 one external interface:
 
@@ -270,15 +512,16 @@ Firewall rules are written as normal, using the internal IP address as the
 source of outbound rules and the destination of inbound rules.
 
 NPTv6
-=====
+-----
 
 NPTv6 stands for Network Prefix Translation. It's a form of NAT for IPv6. It's
 described in :rfc:`6296`. NPTv6 is supported in linux kernel since version 3.13.
 
 **Usage**
 
-NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the external IPv6 prefix is dynamic,
-as it prevents the need for renumbering of internal hosts when the extern prefix changes.
+NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the
+external IPv6 prefix is dynamic, as it prevents the need for renumbering of
+internal hosts when the extern prefix changes.
 
 Let's assume the following network configuration:
 
@@ -302,7 +545,7 @@ their address to the right subnet when going through your router.
 * eth2 addr : 2001:db8:e2::1/48
 
 VyOS Support
-------------
+^^^^^^^^^^^^
 
 NPTv6 support has been added in VyOS 1.2 (Crux) and is available through
 `nat nptv6` configuration nodes.
@@ -333,16 +576,20 @@ Resulting in the following ip6tables rules:
 
 
 NAT before VPN
-==============
+--------------
 
-Some application service providers (ASPs) operate a VPN gateway to provide access to their internal resources,
-and require that a connecting organisation translate all traffic to the service provider network to a source address provided by the ASP.
+Some application service providers (ASPs) operate a VPN gateway to provide
+access to their internal resources, and require that a connecting organisation
+translate all traffic to the service provider network to a source address
+provided by the ASP.
 
 Example Network
----------------
+^^^^^^^^^^^^^^^
 
 Here's one example of a network environment for an ASP.
-The ASP requests that all connections from this company should come from 172.29.41.89 - an address that is assigned by the ASP and not in use at the customer site.
+The ASP requests that all connections from this company should come from
+172.29.41.89 - an address that is assigned by the ASP and not in use at the
+customer site.
 
 .. figure:: _static/images/nat_before_vpn_topology.png
    :scale: 100 %
@@ -352,7 +599,7 @@ The ASP requests that all connections from this company should come from 172.29.
 
 
 Configuration
--------------
+^^^^^^^^^^^^^
 
 The required configuration can be broken down into 4 major pieces:
 
@@ -363,10 +610,11 @@ The required configuration can be broken down into 4 major pieces:
 
 
 Dummy interface
-^^^^^^^^^^^^^^^
+"""""""""""""""
 
-The dummy interface allows us to have an equivalent of the Cisco IOS Loopback interface - a router-internal interface we can use for IP addresses the router must know about,
-but which are not actually assigned to a real network.
+The dummy interface allows us to have an equivalent of the Cisco IOS Loopback
+interface - a router-internal interface we can use for IP addresses the router
+must know about, but which are not actually assigned to a real network.
 
 We only need a single step for this interface:
 
@@ -375,7 +623,7 @@ We only need a single step for this interface:
   set interfaces dummy dum0 address '172.29.41.89/32'
 
 NAT Configuration
-^^^^^^^^^^^^^^^^^
+"""""""""""""""""
 
 .. code-block:: none
 
@@ -391,8 +639,7 @@ NAT Configuration
   set nat source rule 120 translation address '172.29.41.89'
 
 IPSec IKE and ESP
-^^^^^^^^^^^^^^^^^
-
+"""""""""""""""""
 
 The ASP has documented their IPSec requirements:
 
@@ -408,7 +655,8 @@ The ASP has documented their IPSec requirements:
   * DH Group 14
 
 
-Additionally, we want to use VPNs only on our eth1 interface (the external interface in the image above)
+Additionally, we want to use VPNs only on our eth1 interface (the external
+interface in the image above)
 
 .. code-block:: none
 
@@ -429,11 +677,12 @@ Additionally, we want to use VPNs only on our eth1 interface (the external inter
   set vpn ipsec ipsec-interfaces interface 'eth1'
 
 IPSec VPN Tunnels
-^^^^^^^^^^^^^^^^^
+"""""""""""""""""
 
-We'll use the IKE and ESP groups created above for this VPN.
-Because we need access to 2 different subnets on the far side, we will need two different tunnels.
-If you changed the names of the ESP group and IKE group in the previous step, make sure you use the correct names here too.
+We'll use the IKE and ESP groups created above for this VPN. Because we need
+access to 2 different subnets on the far side, we will need two different
+tunnels. If you changed the names of the ESP group and IKE group in the previous
+step, make sure you use the correct names here too.
 
 .. code-block:: none
 
@@ -452,7 +701,8 @@ If you changed the names of the ESP group and IKE group in the previous step, ma
 Testing and Validation
 """"""""""""""""""""""
 
-If you've completed all the above steps you no doubt want to see if it's all working.
+If you've completed all the above steps you no doubt want to see if it's all
+working.
 
 Start by checking for IPSec SAs (Security Associations) with: