summaryrefslogtreecommitdiff
path: root/docs/configuration
diff options
context:
space:
mode:
Diffstat (limited to 'docs/configuration')
-rw-r--r--docs/configuration/nat/index.rst739
-rw-r--r--docs/configuration/nat/nptv6.rst69
-rw-r--r--docs/configuration/policy/index.rst205
3 files changed, 1013 insertions, 0 deletions
diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst
new file mode 100644
index 00000000..85bd41d5
--- /dev/null
+++ b/docs/configuration/nat/index.rst
@@ -0,0 +1,739 @@
+.. _nat:
+
+###
+NAT
+###
+
+.. toctree::
+ :maxdepth: 1
+ :includehidden:
+
+ nptv6
+
+: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.168.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:
+
+SNAT
+^^^^
+
+:abbr:`SNAT (Source Network Address Translation)` is the most common
+form of :abbr:`NAT (Network Address Translation)` and is typically
+referred to simply as NAT. To be more correct, what most people refer
+to as :abbr:`NAT (Network Address Translation)` 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:
+
+DNAT
+^^^^
+
+:abbr:`DNAT (Destination Network Address Translation)` changes the
+destination address of packets passing through the router, while
+:ref:`source-nat` changes the source address of packets. 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 scenario 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 access internal
+(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
+underlying 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 established connections 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
+ 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
+
+
+Address Conversion
+------------------
+
+Every NAT rule has a translation command defined. The address defined
+for the translation is the address 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
+
+In the example used for the Quick Start configuration above, we
+demonstrate the following configuration:
+
+.. code-block:: none
+
+ set nat source rule 100 outbound-interface 'eth0'
+ set nat source rule 100 source address '192.168.0.0/24'
+ set nat source rule 100 translation address 'masquerade'
+
+Which generates the following configuration:
+
+.. code-block:: none
+
+ rule 100 {
+ outbound-interface eth0
+ source {
+ address 192.168.0.0/24
+ }
+ translation {
+ address masquerade
+ }
+ }
+
+In this example, we use **masquerade** as the translation address
+instead of an IP address. The **masquerade** target is effectively an
+alias to say "use whatever IP address is on the outgoing interface",
+rather than a statically configured IP address. This is useful if you
+use DHCP for your outgoing interface and do not know what the external
+address will be.
+
+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 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: For an ~8,000 host network a source NAT pool of 32 IP addresses
+is recommended.
+
+A pool of addresses can be defined by using a hyphen between two IP
+addresses:
+
+.. code-block:: none
+
+ set nat source rule 100 translation address '203.0.113.32-203.0.113.63'
+
+.. _avoidng_leaky_nat:
+
+Avoiding "leaky" NAT
+--------------------
+
+Linux netfilter will not NAT traffic marked as INVALID. This often
+confuses people into thinking that Linux (or specifically VyOS) has a
+broken NAT implementation because non-NATed traffic is seen leaving an
+external interface. This is actually working as intended, and a packet
+capture of the "leaky" traffic should reveal that the traffic is either
+an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems
+after Linux netfilter considers the connection closed. The most common
+is the additional TCP RST some host implementations send after
+terminating a connection (which is implementation-specific).
+
+In other words, connection tracking has already observed the connection
+be closed and has transition the flow to INVALID to prevent attacks from
+attempting to reuse the connection.
+
+You can avoid the "leaky" behavior by using a firewall policy that drops
+"invalid" state packets.
+
+Having control over the matching of INVALID state traffic, e.g. the
+ability to selectively log, is an important troubleshooting tool for
+observing broken 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.
+
+.. _hairpin_nat_reflection:
+
+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. 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.
+
+Example:
+
+* 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 interface `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.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
+
+ 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
+---------------
+
+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 traffic to a system behind the firewall.
+
+In this example, we will be using the example Quick Start configuration
+above as a starting point.
+
+To setup a destination NAT rule we need to gather:
+
+* The interface traffic will be coming in on;
+* The protocol and port we wish to forward;
+* The IP address of the internal system we wish to forward traffic to.
+
+In our example, we will be forwarding web server traffic to an internal
+web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol
+on port 80. For other common port numbers, see:
+https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers
+
+Our configuration commands would be:
+
+.. code-block:: none
+
+ set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100'
+ set nat destination rule 10 destination port '80'
+ set nat destination rule 10 inbound-interface 'eth0'
+ set nat destination rule 10 protocol 'tcp'
+ set nat destination rule 10 translation address '192.168.0.100'
+
+Which would generate the following NAT destination configuration:
+
+.. code-block:: none
+
+ nat {
+ destination {
+ rule 10 {
+ description "Port Forward: HTTP to 192.168.0.100"
+ destination {
+ port 80
+ }
+ inbound-interface eth0
+ protocol tcp
+ translation {
+ address 192.168.0.100
+ }
+ }
+ }
+ }
+
+.. note:: If forwarding traffic to a different port than it is arriving
+ on, you may also configure the translation port using
+ `set nat destination rule [n] translation port`.
+
+This establishes our Port Forward rule, but if we created a firewall
+policy it will likely block the traffic.
+
+It is important to note that when creating firewall rules that the DNAT
+translation occurs **before** traffic traverses the firewall. In other
+words, the destination address has already been translated to
+192.168.0.100.
+
+So in our firewall policy, we want to allow traffic coming in on the
+outside interface, destined for TCP port 80 and the IP address of
+192.168.0.100.
+
+.. code-block:: none
+
+ set firewall name OUTSIDE-IN rule 20 action 'accept'
+ set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100'
+ set firewall name OUTSIDE-IN rule 20 destination port '80'
+ set firewall name OUTSIDE-IN rule 20 protocol 'tcp'
+ set firewall name OUTSIDE-IN rule 20 state new 'enable'
+
+This would generate the following configuration:
+
+.. code-block:: none
+
+ rule 20 {
+ action accept
+ destination {
+ address 192.168.0.100
+ port 80
+ }
+ protocol tcp
+ state {
+ new enable
+ }
+ }
+
+.. note::
+
+ If you have configured the `INSIDE-OUT` policy, you will need to add
+ 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 IP address to an internal IP address and vice-versa.
+
+Typically, a 1-to-1 NAT rule omits the destination port (all ports) and
+replaces the protocol with either **all** or **ip**.
+
+Then a corresponding SNAT rule is created to NAT outgoing traffic for
+the 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.
+
+Here's an extract of a simple 1-to-1 NAT configuration with one internal
+and one external interface:
+
+.. code-block:: none
+
+ set interfaces ethernet eth0 address '192.168.1.1/24'
+ set interfaces ethernet eth0 description 'Inside interface'
+ set interfaces ethernet eth1 address '192.0.2.30/24'
+ set interfaces ethernet eth1 description 'Outside interface'
+ set nat destination rule 2000 description '1-to-1 NAT example'
+ set nat destination rule 2000 destination address '192.0.2.30'
+ set nat destination rule 2000 inbound-interface 'eth1'
+ set nat destination rule 2000 translation address '192.168.1.10'
+ set nat source rule 2000 description '1-to-1 NAT example'
+ set nat source rule 2000 outbound-interface 'eth1'
+ set nat source rule 2000 source address '192.168.1.10'
+ set nat source rule 2000 translation address '192.0.2.30'
+
+Firewall rules are written as normal, using the internal IP address as
+the source of outbound rules and the destination of inbound 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.
+
+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.
+
+.. figure:: _static/images/nat_before_vpn_topology.png
+ :scale: 100 %
+ :alt: NAT before VPN Topology
+
+ NAT before VPN Topology
+
+
+Configuration
+^^^^^^^^^^^^^
+
+The required configuration can be broken down into 4 major pieces:
+
+* A dummy interface for the provider-assigned IP;
+* NAT (specifically, Source NAT);
+* IPSec IKE and ESP Groups;
+* IPSec VPN tunnels.
+
+
+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.
+
+We only need a single step for this interface:
+
+.. code-block:: none
+
+ set interfaces dummy dum0 address '172.29.41.89/32'
+
+NAT Configuration
+"""""""""""""""""
+
+.. code-block:: none
+
+ set nat source rule 110 description 'Internal to ASP'
+ set nat source rule 110 destination address '172.27.1.0/24'
+ set nat source rule 110 outbound-interface 'any'
+ set nat source rule 110 source address '192.168.43.0/24'
+ set nat source rule 110 translation address '172.29.41.89'
+ set nat source rule 120 description 'Internal to ASP'
+ set nat source rule 120 destination address '10.125.0.0/16'
+ set nat source rule 120 outbound-interface 'any'
+ set nat source rule 120 source address '192.168.43.0/24'
+ set nat source rule 120 translation address '172.29.41.89'
+
+IPSec IKE and ESP
+"""""""""""""""""
+
+The ASP has documented their IPSec requirements:
+
+* IKE Phase:
+
+ * aes256 Encryption
+ * sha256 Hashes
+
+* ESP Phase:
+
+ * aes256 Encryption
+ * sha256 Hashes
+ * DH Group 14
+
+
+Additionally, we want to use VPNs only on our eth1 interface (the
+external interface in the image above)
+
+.. code-block:: none
+
+ set vpn ipsec ike-group my-ike ikev2-reauth 'no'
+ set vpn ipsec ike-group my-ike key-exchange 'ikev1'
+ set vpn ipsec ike-group my-ike lifetime '7800'
+ set vpn ipsec ike-group my-ike proposal 1 dh-group '14'
+ set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256'
+ set vpn ipsec ike-group my-ike proposal 1 hash 'sha256'
+
+ set vpn ipsec esp-group my-esp compression 'disable'
+ set vpn ipsec esp-group my-esp lifetime '3600'
+ set vpn ipsec esp-group my-esp mode 'tunnel'
+ set vpn ipsec esp-group my-esp pfs 'disable'
+ set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256'
+ set vpn ipsec esp-group my-esp proposal 1 hash 'sha256'
+
+ 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.
+
+.. code-block:: none
+
+ set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret'
+ set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE'
+ set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate'
+ set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp'
+ set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike'
+ set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit'
+ set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46'
+ set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32'
+ set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24'
+ set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32'
+ 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.
+
+Start by checking for IPSec SAs (Security Associations) with:
+
+.. code-block:: none
+
+ $ show vpn ipsec sa
+
+ Peer ID / IP Local ID / IP
+ ------------ -------------
+ 198.51.100.243 203.0.113.46
+
+ Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto
+ ------ ----- ------------- ------- ---- ----- ------ ------ -----
+ 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all
+ 1 up 0.0/0.0 aes256 sha256 no 865 3600 all
+
+That looks good - we defined 2 tunnels and they're both up and running.
diff --git a/docs/configuration/nat/nptv6.rst b/docs/configuration/nat/nptv6.rst
new file mode 100644
index 00000000..f4e08325
--- /dev/null
+++ b/docs/configuration/nat/nptv6.rst
@@ -0,0 +1,69 @@
+.. include:: _include/need_improvement.txt
+
+.. _nptv6:
+
+#####
+NPTv6
+#####
+
+:abbr:`NPTv6 (Network Prefix Translation)` is a form of NAT for IPv6. It's
+described in :rfc:`6296`.
+
+**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.
+
+Let's assume the following network configuration:
+
+* eth0 : LAN
+* eth1 : WAN1, with 2001:db8:e1::/48 routed towards it
+* eth2 : WAN2, with 2001:db8:e2::/48 routed towards it
+
+Regarding LAN hosts addressing, why would you choose 2001:db8:e1::/48 over
+2001:db8:e2::/48? What happens when you get a new provider with a different
+routed IPv6 subnet?
+
+The solution here is to assign to your hosts ULAs_ and to prefix-translate
+their address to the right subnet when going through your router.
+
+* LAN Subnet : fc00:dead:beef::/48
+* WAN 1 Subnet : 2001:db8:e1::/48
+* WAN 2 Subnet : 2001:db8:e2::/48
+
+* eth0 addr : fc00:dead:beef::1/48
+* eth1 addr : 2001:db8:e1::1/48
+* 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.
+
+.. code-block:: none
+
+ set rule 10 source prefix 'fc00:dead:beef::/48'
+ set rule 10 outbound-interface 'eth1'
+ set rule 10 translation prefix '2001:db8:e1::/48'
+ set rule 20 source prefix 'fc00:dead:beef::/48'
+ set rule 20 outbound-interface 'eth2'
+ set rule 20 translation prefix '2001:db8:e2::/48'
+
+Resulting in the following ip6tables rules:
+
+.. code-block:: none
+
+ Chain VYOS_DNPT_HOOK (1 references)
+ pkts bytes target prot opt in out source destination
+ 0 0 NETMAP all eth1 any anywhere 2001:db8:e1::/48 to:fc00:dead:beef::/48
+ 0 0 NETMAP all eth2 any anywhere 2001:db8:e2::/48 to:fc00:dead:beef::/48
+ 0 0 RETURN all any any anywhere anywhere
+ Chain VYOS_SNPT_HOOK (1 references)
+ pkts bytes target prot opt in out source destination
+ 0 0 NETMAP all any eth1 fc00:dead:beef::/48 anywhere to:2001:db8:e1::/48
+ 0 0 NETMAP all any eth2 fc00:dead:beef::/48 anywhere to:2001:db8:e2::/48
+ 0 0 RETURN all any any anywhere anywhere
+
+.. _ULAs: https://en.wikipedia.org/wiki/Unique_local_address
diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst
new file mode 100644
index 00000000..4be494e5
--- /dev/null
+++ b/docs/configuration/policy/index.rst
@@ -0,0 +1,205 @@
+.. include:: ../_include/need_improvement.txt
+
+######
+Policy
+######
+
+Routing Policies could be used to tell the router (self or neighbors) what
+routes and their attributes needs to be put into the routing table.
+
+There could be a wide range of routing policies. Some examples are below:
+
+* Set some metric to routes learned from a particular neighbor
+* Set some attributes (like AS PATH or Community value) to advertised routes to neighbors
+* Prefer a specific routing protocol routes over another routing protocol running on the same router
+
+Example
+=======
+
+**Policy definition:**
+
+.. code-block:: none
+
+ # Create policy
+ set policy route-map setmet rule 2 action 'permit'
+ set policy route-map setmet rule 2 set as-path-prepend '2 2 2'
+
+ # Apply policy to BGP
+ set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet'
+ set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound'
+
+Using 'soft-reconfiguration' we get the policy update without bouncing the
+neighbor.
+
+**Routes learned before routing policy applied:**
+
+.. code-block:: none
+
+ vyos@vos1:~$ show ip bgp
+ BGP table version is 0, local router ID is 192.168.56.101
+ Status codes: s suppressed, d damped, h history, * valid, > best, i - internal,
+ r RIB-failure, S Stale, R Removed
+ Origin codes: i - IGP, e - EGP, ? - incomplete
+
+ Network Next Hop Metric LocPrf Weight Path
+ *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path
+
+ Total number of prefixes 1
+
+**Routes learned after routing policy applied:**
+
+.. code-block:: none
+
+ vyos@vos1:~$ sho ip b
+ BGP table version is 0, local router ID is 192.168.56.101
+ Status codes: s suppressed, d damped, h history, * valid, > best, i - internal,
+ r RIB-failure, S Stale, R Removed
+ Origin codes: i - IGP, e - EGP, ? - incomplete
+
+ Network Next Hop Metric LocPrf Weight Path
+ *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i
+
+ Total number of prefixes 1
+ vyos@vos1:~$
+
+You now see the longer AS path.
+
+
+.. include:: ../_include/need_improvement.txt
+
+.. _routing-pbr:
+
+###
+PBR
+###
+
+:abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to
+different routing tables. Traffic can be matched using standard 5-tuple
+matching (source address, destination address, protocol, source port,
+destination port).
+
+Transparent Proxy
+=================
+
+The following example will show how VyOS can be used to redirect web
+traffic to an external transparent proxy:
+
+.. code-block:: none
+
+ set policy route FILTER-WEB rule 1000 destination port 80
+ set policy route FILTER-WEB rule 1000 protocol tcp
+ set policy route FILTER-WEB rule 1000 set table 100
+
+This creates a route policy called FILTER-WEB with one rule to set the
+routing table for matching traffic (TCP port 80) to table ID 100
+instead of the default routing table.
+
+To create routing table 100 and add a new default gateway to be used by
+traffic matching our route policy:
+
+.. code-block:: none
+
+ set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2
+
+This can be confirmed using the ``show ip route table 100`` operational
+command.
+
+Finally, to apply the policy route to ingress traffic on our LAN
+interface, we use:
+
+.. code-block:: none
+
+ set interfaces ethernet eth1 policy route FILTER-WEB
+
+
+Multiple Uplinks
+================
+
+VyOS Policy-Based Routing (PBR) works by matching source IP address
+ranges and forwarding the traffic using different routing tables.
+
+Routing tables that will be used in this example are:
+
+* ``table 10`` Routing table used for VLAN 10 (192.168.188.0/24)
+* ``table 11`` Routing table used for VLAN 11 (192.168.189.0/24)
+* ``main`` Routing table used by VyOS and other interfaces not
+ participating in PBR
+
+.. figure:: ../_static/images/pbr_example_1.png
+ :scale: 80 %
+ :alt: PBR multiple uplinks
+
+ Policy-Based Routing with multiple ISP uplinks
+ (source ./draw.io/pbr_example_1.drawio)
+
+Add default routes for routing ``table 10`` and ``table 11``
+
+.. code-block:: none
+
+ set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1
+ set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2
+
+Add policy route matching VLAN source addresses
+
+.. code-block:: none
+
+ set policy route PBR rule 20 set table '10'
+ set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10'
+ set policy route PBR rule 20 source address '192.168.188.0/24'
+
+ set policy route PBR rule 30 set table '11'
+ set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11'
+ set policy route PBR rule 30 source address '192.168.189.0/24'
+
+Apply routing policy to **inbound** direction of out VLAN interfaces
+
+.. code-block:: none
+
+ set interfaces ethernet eth0 vif 10 policy route 'PBR'
+ set interfaces ethernet eth0 vif 11 policy route 'PBR'
+
+
+**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11)
+from PBR
+
+.. code-block:: none
+
+ set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut'
+ set policy route PBR rule 10 destination address '192.168.188.0/24'
+ set policy route PBR rule 10 destination address '192.168.189.0/24'
+ set policy route PBR rule 10 set table 'main'
+
+These commands allow the VLAN10 and VLAN20 hosts to communicate with
+each other using the main routing table.
+
+Local route
+===========
+
+The following example allows VyOS to use :abbr:`PBR (Policy-Based Routing)` for traffic, which originated from the router itself.
+That solution for multiple ISP's and VyOS router will respond from the same interface that the packet was received.
+Also, it used, if we want that one VPN tunnel to be through one provider, and the second through another.
+
+* ``192.168.1.254`` IP addreess on VyOS eth1 from ISP1
+* ``192.168.2.254`` IP addreess on VyOS eth2 from ISP2
+* ``table 10`` Routing table used for ISP1
+* ``table 11`` Routing table used for ISP2
+
+
+.. code-block:: none
+
+ set policy local-route rule 101 set table '10'
+ set policy local-route rule 101 source '192.0.1.254'
+ set policy local-route rule 102 set table '11'
+ set policy local-route rule 102 source '192.0.2.254'
+ set protocols static table 10 route '0.0.0.0/0' next-hop '192.0.1.1'
+ set protocols static table 11 route '0.0.0.0/0' next-hop '192.0.2.2'
+
+Add multiple source IP in one rule with same priority
+
+.. code-block:: none
+
+ set policy local-route rule 101 set table '10'
+ set policy local-route rule 101 source '192.0.1.254'
+ set policy local-route rule 101 source '192.0.1.253'
+ set policy local-route rule 101 source '203.0.113.0/24'
+
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-23 01:02:26 +0000