Merge branch 'master' into newdirectives

1 files changed, 358 insertions, 60 deletions

diff --git a/docs/nat.rst b/docs/nat.rst
index 714697d3..9607be3d 100644
--- a/docs/nat.rst
+++ b/docs/nat.rst
@@ -1,22 +1,270 @@
 .. _nat:
 
+###
 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 (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
+
+
+* **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
 
-Source NAT
-----------
 
-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.
+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:
@@ -87,10 +335,10 @@ protocol behavior. For this reason, VyOS does not globally drop invalid state
 traffic, instead allowing the operator to make the determination on how the
 traffic is handled.
 
-NAT Reflection/Hairpin NAT
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _hairpin_nat_reflection:
 
-.. note:: Avoiding NAT breakage in the absence of split-DNS
+Hairpin NAT/NAT Reflection
+--------------------------
 
 A typical problem with using NAT and hosting public servers is the ability for
 internal systems to reach an internal server using it's external IP address.
@@ -98,41 +346,87 @@ The solution to this is usually the use of split-DNS to correctly point host
 systems to the internal address when requests are made internally. Because
 many smaller networks lack DNS infrastructure, a work-around is commonly
 deployed to facilitate the traffic by NATing the request from internal hosts
-to the source address of the internal interface on the firewall. This technique
-is commonly referred to as **NAT Reflection**, or **Hairpin NAT**.
+to the source address of the internal interface on the firewall.
 
-In this example, we will be using the example Quick Start configuration above
-as a starting point.
+This technique is commonly referred to as NAT Reflection or Hairpin NAT.
+
+Example:
 
-To setup a NAT reflection rule, we need to create a rule to NAT connections
-from the internal network to the same internal network to use the source
-address of the internal interface.
+* Redirect Microsoft RDP traffic from the outside (WAN, external) world via
+  :ref:`destination-nat` in rule 100 to the internal, private host 192.0.2.40.
+
+* Redirect Microsoft RDP traffic from the internal (LAN, private) network via
+  :ref:`destination-nat` in rule 110 to the internal, private host 192.0.2.40.
+  We also need a :ref:`source-nat` rule 110 for the reverse path of the traffic.
+  The internal network 192.0.2.0/24 is reachable via interfache `eth0.10`.
 
 .. code-block:: none
 
+  set nat destination rule 100 description 'Regular destination NAT from external'
+  set nat destination rule 100 destination port '3389'
+  set nat destination rule 100 inbound-interface 'pppoe0'
+  set nat destination rule 100 protocol 'tcp'
+  set nat destination rule 100 translation address '192.0.2.40'
+
+  set nat destination rule 110 description 'NAT Reflection: INSIDE'
+  set nat destination rule 110 destination port '3389'
+  set nat destination rule 110 inbound-interface 'eth0.10'
+  set nat destination rule 110 protocol 'tcp'
+  set nat destination rule 110 translation address '192.0.2.40'
+
   set nat source rule 110 description 'NAT Reflection: INSIDE'
-  set nat source rule 110 destination address '192.168.0.0/24'
-  set nat source rule 110 outbound-interface 'eth1'
-  set nat source rule 110 source address '192.168.0.0/24'
+  set nat source rule 110 destination address '192.0.2.0/24'
+  set nat source rule 110 outbound-interface 'eth0.10'
+  set nat source rule 110 protocol 'tcp'
+  set nat source rule 110 source address '192.0.2.0/24'
   set nat source rule 110 translation address 'masquerade'
 
 Which results in a configuration of:
 
 .. code-block:: none
 
-  rule 110 {
-      description "NAT Reflection: INSIDE"
-      destination {
-          address 192.168.0.0/24
-      }
-      outbound-interface eth1
-      source {
-          address 192.168.0.0/24
-      }
-      translation {
-          address masquerade
-      }
-  }
+  vyos@vyos# show nat
+   destination {
+       rule 100 {
+           description "Regular destination NAT from external"
+           destination {
+               port 3389
+           }
+           inbound-interface pppoe0
+           protocol tcp
+           translation {
+               address 192.0.2.40
+           }
+       }
+       rule 110 {
+           description "NAT Reflection: INSIDE"
+           destination {
+               port 3389
+           }
+           inbound-interface eth0.10
+           protocol tcp
+           translation {
+               address 192.0.2.40
+           }
+       }
+   }
+   source {
+       rule 110 {
+           description "NAT Reflection: INSIDE"
+           destination {
+               address 192.0.2.0/24
+           }
+           outbound-interface eth0.10
+           protocol tcp
+           source {
+               address 192.0.2.0/24
+           }
+           translation {
+               address masquerade
+           }
+       }
+   }
+
 
 Destination NAT
 ---------------
@@ -242,9 +536,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:
 
@@ -272,11 +563,11 @@ 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
-^^^^^
+**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:
 
@@ -333,14 +624,18 @@ 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 %
@@ -361,10 +656,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:
 
@@ -373,7 +669,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
 
@@ -389,8 +685,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:
 
@@ -406,7 +701,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
 
@@ -427,11 +723,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
 
@@ -448,9 +745,10 @@ If you changed the names of the ESP group and IKE group in the previous step, ma
   set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16'
 
 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: