Merge pull request #1 from hagbard-01/master

Adding wireguard documentation to ch05.

2 files changed, 370 insertions, 0 deletions

diff --git a/docs/ch05-network-interfaces.rst b/docs/ch05-network-interfaces.rst
index 892d17a9..65d081bc 100644
--- a/docs/ch05-network-interfaces.rst
+++ b/docs/ch05-network-interfaces.rst
@@ -158,6 +158,7 @@ VLAN interfaces are shown as <name>.<vlan-id>, e.g. eth1.100:
   eth1.100         192.168.100.1/24                  u/u  VLAN 100
   lo               127.0.0.1/8                       u/u
                   ::1/128
+
 Bridging
 --------
 
@@ -353,3 +354,89 @@ Results in:
       description "Description"
   }
 
+Wireguard VPN Interface
+-----------------------
+
+WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography.
+See https://www.wireguard.com for mor information.
+
+Configuration
+^^^^^^^^^^^^^
+
+Generate the keypair, which creates a public and private part and stores it within vyos.
+
+.. code-block:: sh
+
+  wg01:~$ configure
+  wg01# run generate wireguard keypair
+
+The public key is being shared with your peer(s), your peer will encrypt all traffic to your system using this public key.
+
+.. code-block:: sh
+
+  wg01#run show wireguard pubkey
+  u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=
+
+The next step is to configure your local side as well as the policy based trusted destination addresses.
+If you only initiate a connection, the listen port and endpoint is optional, if you however act as a server and endpoints initiate the connections to your system, you need to define a port your clients can connect to, otherwise it's randomly chosen and may make it difficult with firewall rules, since the port may be a different one when you reboot your system.
+
+You will also need the public key of your peer as well as the network(s) you want to tunnel (allowed-ips) to configure a wireguard tunnel.
+The public key below is always the public key from your peer, not your local one.
+
+**local side**
+
+.. code-block:: sh
+
+  set interfaces wireguard wg01 address '10.1.0.1/24'
+  set interfaces wireguard wg01 description 'VPN-to-wg02'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24'
+  set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.142:12345'
+  set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI='
+  set interfaces wireguard wg01 port '12345'
+  set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01
+
+The last step is to define an interface route for 10.2.0.0/24 to get through the wireguard interface wg01.
+Multiple IPs or networks can be defined and routed, the last check is allowed-ips which either prevents or allows the traffic.
+
+**remote side**
+
+.. code-block:: sh
+
+  set interfaces wireguard wg01 address '10.2.0.1/24'
+  set interfaces wireguard wg01 description 'VPN-to-wg01'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24'
+  set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.124:12345'
+  set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk='
+  set interfaces wireguard wg01 port '12345'
+  set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01
+
+Assure that your firewall rules allow the traffic, in which case you have a working VPN using wireguard.
+
+.. code-block:: sh
+
+  wg01# ping 10.2.0.1
+  PING 10.2.0.1 (10.2.0.1) 56(84) bytes of data.
+  64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=1.16 ms
+  64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=1.77 ms
+
+  wg02# ping 10.1.0.1
+  PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data.
+  64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=4.40 ms
+  64 bytes from 10.1.0.1: icmp_seq=2 ttl=64 time=1.02 ms
+
+An additional layer of symmetric-key crypto can be used on top of the asymmetric crypto, which is optional.
+
+.. code-block:: sh
+
+  wg01# run generate wireguard preshared-key
+  rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=
+
+Copy the key, it is not stored on the local file system.
+Make sure you distribute that key in a safe manner, it's a symmatric key, so only you and your peer should have knowledge if its content.
+
+.. code-block:: sh
+
+  wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+  wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
+
+
diff --git a/docs/ch06-routing.rst b/docs/ch06-routing.rst
new file mode 100644
index 00000000..23677bc8
--- /dev/null
+++ b/docs/ch06-routing.rst
@@ -0,0 +1,283 @@
+Routing
+=======
+
+VyOS is a "router first" network operating system. It supports static routing, policy routing, and dynamic routing using standard protocols (RIP, OSPF, and BGP).
+
+Static
+------
+
+Static routes are manually configured network routes.
+
+A typical use for a static route is a static default route for systems that do not make use of DHCP or dynamic routing protocols: 
+
+.. code-block:: sh
+
+  set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 distance '1'
+
+Another common use of static routes is to blackhole (drop) traffic.
+In the example below, RFC 1918 private IP networks are set as blackhole routes.
+This does not prevent networks within these segments from being used, since the most specific route is always used.
+It does, however, prevent traffic to unknown private networks from leaving the router. Commonly refereed to as leaking.
+
+.. code-block:: sh
+
+  set protocols static route 10.0.0.0/8 blackhole distance '254'
+  set protocols static route 172.16.0.0/12 blackhole distance '254'
+  set protocols static route 192.168.0.0/16 blackhole distance '254'
+
+Note that routes with a distance of 255 are effectively disabled and not installed into the kernel.
+
+RIP
+---
+
+Simple RIP configuration using 2 nodes and redistributing connected interfaces.
+
+**Node 1:** 
+
+.. code-block:: sh
+
+  set interfaces loopback address 10.1.1.1/32
+  set protocols rip network 192.168.0.0/24
+  set protocols rip redistribute connected
+
+**Node 2:**
+
+.. code-block:: sh
+
+  set interfaces loopback address 10.2.2.2/32
+  set protocols rip network 192.168.0.0/24
+  set protocols rip redistribute connected
+
+OSPF
+----
+
+IPv4
+^^^^
+
+A typical configuration using 2 nodes, redistribute loopback address and the node 1 sending the default route:
+
+**Node 1:**
+
+.. code-block:: sh
+
+  set interfaces loopback lo address 10.1.1.1/32
+  set protocols ospf area 0 network 192.168.0.0/24
+  set protocols ospf default-information originate always
+  set protocols ospf default-information originate metric 10
+  set protocols ospf default-information originate metric-type 2
+  set protocols ospf log-adjacency-changes
+  set protocols ospf parameters router-id 10.1.1.1
+  set protocols ospf redistribute connected metric-type 2
+  set protocols ospf redistribute connected route-map CONNECT
+
+  set policy route-map CONNECT rule 10 action permit
+  set policy route-map CONNECT rule 10 match interface lo
+
+**Node 2:**
+
+.. code-block:: sh
+
+  set interfaces loopback lo address 10.2.2.2/32
+  set protocols ospf area 0 network 192.168.0.0/24
+  set protocols ospf log-adjacency-changes
+  set protocols ospf parameters router-id 10.2.2.2
+  set protocols ospf redistribute connected metric-type 2
+  set protocols ospf redistribute connected route-map CONNECT
+
+  set policy route-map CONNECT rule 10 action permit
+  set policy route-map CONNECT rule 10 match interface lo
+
+IPv6
+^^^^
+
+A typical configuration using 2 nodes.
+
+**Node 1:**
+
+.. code-block:: sh
+
+  set protocols ospfv3 area 0.0.0.0 interface eth1
+  set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64
+  set protocols ospfv3 parameters router-id 192.168.1.1
+  set protocols ospfv3 redistribute connected
+
+**Node 2:**
+
+.. code-block:: sh
+
+  set protocols ospfv3 area 0.0.0.0 interface eth1
+  set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64
+  set protocols ospfv3 parameters router-id 192.168.2.1
+  set protocols ospfv3 redistribute connected
+
+BGP
+---
+
+IPv4
+^^^^
+
+A simple eBGP configuration:
+
+**Node 1:**
+
+.. code-block:: sh
+
+  set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2'
+  set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535'
+  set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1'
+  set protocols bgp 65534 network '172.16.0.0/16'
+  set protocols bgp 65534 parameters router-id '192.168.0.1'
+
+**Node 2:**
+
+.. code-block:: sh
+
+  set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2'
+  set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534'
+  set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2'
+  set protocols bgp 65535 network '172.17.0.0/16'
+  set protocols bgp 65535 parameters router-id '192.168.0.2'
+
+
+Don't forget, the CIDR declared in the network statement MUST **exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:**
+
+**Node 1:**
+
+.. code-block:: sh
+
+  set protocols static route 1.0.0.0/16 blackhole distance '254'
+
+**Node 2:**
+
+.. code-block:: sh
+
+  set protocols static route 2.0.0.0/16 blackhole distance '254'
+
+
+IPv6
+^^^^
+
+A simple BGP configuration via IPv6.
+
+**Node 1:**
+
+.. code-block:: sh
+
+  set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2'
+  set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535'
+  set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1'
+  set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast
+  set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48'
+  set protocols bgp 65534 parameters router-id '10.1.1.1'
+
+**Node 2:**
+
+.. code-block:: sh
+
+  set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2'
+  set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534'
+  set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2'
+  set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast
+  set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48'
+  set protocols bgp 65535 parameters router-id '10.1.1.2'
+
+
+Don't forget, the CIDR declared in the network statement **MUST exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:**
+
+**Node 1:**
+
+.. code-block:: sh
+
+  set protocols static route6 2a001:100:1::/48 blackhole distance '254'
+
+**Node 2:**
+
+.. code-block:: sh
+
+  set protocols static route6 2001:db8:2::/48 blackhole distance '254'
+
+Route Filter
+^^^^^^^^^^^^
+
+Route filter can be applied using a route-map:
+
+**Node1:**
+
+.. code-block:: sh
+
+  set policy prefix-list AS65535-IN rule 10 action 'permit'
+  set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16'
+  set policy prefix-list AS65535-OUT rule 10 action 'deny'
+  set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16'
+  set policy prefix-list6 AS65535-IN rule 10 action 'permit'
+  set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48'
+  set policy prefix-list6 AS65535-OUT rule 10 action 'deny'
+  set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48'
+  set policy route-map AS65535-IN rule 10 action 'permit'
+  set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN'
+  set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN'
+  set policy route-map AS65535-IN rule 20 action 'deny'
+  set policy route-map AS65535-OUT rule 10 action 'deny'
+  set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT'
+  set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT'
+  set policy route-map AS65535-OUT rule 20 action 'permit'
+  set protocols bgp 65534 neighbor 2001:db8::2 route-map export 'AS65535-OUT'
+  set protocols bgp 65534 neighbor 2001:db8::2 route-map import 'AS65535-IN'
+
+**Node2:**
+
+.. code-block:: sh
+
+  set policy prefix-list AS65534-IN rule 10 action 'permit'
+  set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16'
+  set policy prefix-list AS65534-OUT rule 10 action 'deny'
+  set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16'
+  set policy prefix-list6 AS65534-IN rule 10 action 'permit'
+  set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48'
+  set policy prefix-list6 AS65534-OUT rule 10 action 'deny'
+  set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48'
+  set policy route-map AS65534-IN rule 10 action 'permit'
+  set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN'
+  set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN'
+  set policy route-map AS65534-IN rule 20 action 'deny'
+  set policy route-map AS65534-OUT rule 10 action 'deny'
+  set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT'
+  set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT'
+  set policy route-map AS65534-OUT rule 20 action 'permit'
+  set protocols bgp 65535 neighbor 2001:db8::1 route-map export 'AS65534-OUT'
+  set protocols bgp 65535 neighbor 2001:db8::1 route-map import 'AS65534-IN'
+
+We could expand on this and also deny link local and multicast in the rule 20 action deny. 
+
+Policy Routing
+==============
+
+VyOS supports Policy Routing, allowing traffic to be assigned to a different routing table. Traffic can be matched using standard 5-tuple matching (source address, destination address, protocol, source port, destination port).
+
+The following example will show how VyOS can be used to redirect web traffic to an external transparent proxy:
+
+.. code-block:: sh
+
+  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:: sh
+
+  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:: sh
+
+  set interfaces ethernet eth1 policy route FILTER-WEB
+
+The route policy functionality in VyOS can also be used to rewrite TCP MSS using the set policy route <name> rule <rule> set tcp-mss <value> directive, modify DSCP value using [...] set dscp <value>, or mark the traffic with an internal ID using [...] set mark <value> for further processing (e.g. QOS) on a per-rule basis for matching traffic.
+
+In addition to 5-tuple matching, additional options such as time-based rules, are available. See the built-in help for a complete list of options.