Merge pull request #575 from usman-umer/equuleus

updated wireguard docs for equuleus branch

2 files changed, 105 insertions, 38 deletions

diff --git a/docs/_static/images/wireguard_site2site_diagram.jpg b/docs/_static/images/wireguard_site2site_diagram.jpg
new file mode 100644
index 00000000..4a7a95e4
--- /dev/null
+++ b/docs/_static/images/wireguard_site2site_diagram.jpg
diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst
index ddfbe620..2d6baeec 100644
--- a/docs/configuration/interfaces/wireguard.rst
+++ b/docs/configuration/interfaces/wireguard.rst
@@ -1,7 +1,5 @@
 .. _wireguard:
 
-.. include:: /_include/need_improvement.txt
-
 #########
 WireGuard
 #########
@@ -10,10 +8,24 @@ WireGuard is an extremely simple yet fast and modern VPN that utilizes
 state-of-the-art cryptography. See https://www.wireguard.com for more
 information.
 
+****************
+Site to Site VPN
+****************
+
+This diagram corresponds with the example site to site configuration below.
+
+.. figure:: /_static/images/wireguard_site2site_diagram.jpg
+
 *************
 Configuration
 *************
 
+
+
+********
+Keypairs
+********
+
 WireGuard requires the generation of a keypair, which includes a private
 key to decrypt incoming traffic, and a public key for peer(s) to encrypt
 traffic.
@@ -55,8 +67,9 @@ own keypairs.
     vyos@vyos:~$ generate wireguard named-keypairs KP02
 
 
+***********************
 Interface configuration
-=======================
+***********************
 
 The next step is to configure your local side as well as the policy
 based trusted destination addresses. If you only initiate a connection,
@@ -71,18 +84,31 @@ 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**
+**local side - commands**
 
 .. code-block:: none
 
-  set interfaces wireguard wg01 address '10.1.0.1/24'
+  set interfaces wireguard wg01 address '10.1.0.1/30'
   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 address '192.168.0.142'
-  set interfaces wireguard wg01 peer to-wg02 port '12345'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24'
+  set interfaces wireguard wg01 peer to-wg02 address '<Site1 Pub IP>'
+  set interfaces wireguard wg01 peer to-wg02 port '51820'
   set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI='
-  set interfaces wireguard wg01 port '12345'
-  set protocols static route 10.2.0.0/24 interface wg01
+  set interfaces wireguard wg01 port '51820'
+  set protocols static route 192.168.2.0/24 interface wg01
+
+**local side - annotated commands**
+
+.. code-block:: none
+
+  set interfaces wireguard wg01 address '10.1.0.1/30'                     # Address of the wg01 tunnel interface.          
+  set interfaces wireguard wg01 description 'VPN-to-wg02'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' # Subnets that are allowed to travel over the tunnel
+  set interfaces wireguard wg01 peer to-wg02 address '<Site2 Pub IP>'     # Public IP of the peer
+  set interfaces wireguard wg01 peer to-wg02 port '58120'                 # Port of the Peer
+  set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>'            # Public Key of the Peer
+  set interfaces wireguard wg01 port '51820'                              # Port of own server
+  set protocols static route 192.168.2.0/24 interface wg01                # Static route to remote subnet
 
 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
@@ -90,7 +116,7 @@ defined and routed. The last check is allowed-ips which either prevents
 or allows the traffic.
 
 .. note:: You can not assign the same allowed-ips statement to multiple
-   WireGuard peers. This a a design decission. For more information please
+   WireGuard peers. This a a design decision. For more information please
    check the `WireGuard mailing list`_.
 
 .. cfgcmd:: set interfaces wireguard <interface> private-key <name>
@@ -106,33 +132,70 @@ or allows the traffic.
   public key, which needs to be shared with the peer.
 
 
-**remote side**
+**remote side - commands**
 
 .. code-block:: none
 
-  set interfaces wireguard wg01 address '10.2.0.1/24'
+  set interfaces wireguard wg01 address '10.1.0.2/30'
   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 address '192.168.0.124'
-  set interfaces wireguard wg01 peer to-wg02 port '12345'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24'
+  set interfaces wireguard wg01 peer to-wg02 address '<Site1 Pub IP>'
+  set interfaces wireguard wg01 peer to-wg02 port '51820'
   set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk='
-  set interfaces wireguard wg01 port '12345'
-  set protocols static route 10.1.0.0/24 interface wg01
+  set interfaces wireguard wg01 port '51820'
+  set protocols static route 192.168.1.0/24 interface wg01
+
+**remote side - annotated commands**
+
+.. code-block:: none
+
+  set interfaces wireguard wg01 address '10.1.0.2/30'                     # Address of the wg01 tunnel interface.
+  set interfaces wireguard wg01 description 'VPN-to-wg01'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24' # Subnets that are allowed to travel over the tunnel
+  set interfaces wireguard wg01 peer to-wg02 address 'Site1 Pub IP'       # Public IP address of the Peer
+  set interfaces wireguard wg01 peer to-wg02 port '51820'                 # Port of the Peer
+  set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>'            # Public key of the Peer  
+  set interfaces wireguard wg01 port '51820'                              # Port of own server
+  set protocols static route 192.168.1.0/24 interface wg01                # Static route to remote subnet
+
+*******************
+Firewall Exceptions
+*******************
+
+For the WireGuard traffic to pass through the WAN interface, you must create a firewall exception.
+
+.. code-block:: none
 
-Assure that your firewall rules allow the traffic, in which case you
-have a working VPN using WireGuard.
+    set firewall name OUTSIDE_LOCAL rule 10 action accept
+    set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related'
+    set firewall name OUTSIDE_LOCAL rule 10 state established enable
+    set firewall name OUTSIDE_LOCAL rule 10 state related enable
+    set firewall name OUTSIDE_LOCAL rule 20 action accept
+    set firewall name OUTSIDE_LOCAL rule 20 description WireGuard_IN
+    set firewall name OUTSIDE_LOCAL rule 20 destination port 51820
+    set firewall name OUTSIDE_LOCAL rule 20 log enable
+    set firewall name OUTSIDE_LOCAL rule 20 protocol udp
+    set firewall name OUTSIDE_LOCAL rule 20 source
+
+You should also ensure that the OUTISDE_LOCAL firewall group is applied to the WAN interface and a direction (local).
 
 .. code-block:: none
 
-  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
+    set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL'
+
+Assure that your firewall rules allow the traffic, in which case you have a working VPN using WireGuard.
+
+.. code-block:: none
 
-  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
+  wg01# ping 192.168.1.1
+  PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data.
+  64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms
+  64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms
+
+  wg02# ping 192.168.2.1
+  PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data.
+  64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms
+  64 bytes from 192.168.2.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. This is optional.
@@ -151,8 +214,10 @@ its content. Make sure you distribute the key in a safe manner,
   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='
 
-Road Warrior Example
---------------------
+
+***********************************
+Remote Access "RoadWarrior" Example
+***********************************
 
 With WireGuard, a Road Warrior VPN config is similar to a site-to-site
 VPN. It just lacks the ``address`` and ``port`` statements.
@@ -182,7 +247,7 @@ the peers. This allows the peers to interact with one another.
     }
 
 The following is the config for the iPhone peer above. It's important to
-note that the ``AllowedIPs`` setting directs all IPv4 and IPv6 traffic
+note that the ``AllowedIPs`` wildcard setting directs all IPv4 and IPv6 traffic
 through the connection.
 
 .. code-block:: none
@@ -198,9 +263,9 @@ through the connection.
     Endpoint = 192.0.2.1:2224
     PersistentKeepalive = 25
 
-
-This MacBook peer is doing split-tunneling, where only the subnets local
-to the server go over the connection.
+However, split-tunneling can be achieved by specifing the remote subnets.
+This ensures that only traffic destined for the remote site is sent over the tunnel.
+All other traffic is unaffected.
 
 .. code-block:: none
 
@@ -252,8 +317,9 @@ Status
         TX:  bytes  packets  errors  dropped  carrier  collisions
                  0        0       0        0        0           0
 
+***************
 Encryption Keys
-===============
+***************
 
 .. opcmd:: show wireguard keypair pubkey <name>
 
@@ -284,15 +350,16 @@ Encryption Keys
     vyos@vyos:~$ delete wireguard keypair default
 
 
-Mobile "RoadWarrior" clients
-============================
+***********************************
+Remote Access "RoadWarrior" clients
+***********************************
 
 Some users tend to connect their mobile devices using WireGuard to their VyOS
 router. To ease deployment one can generate a "per mobile" configuration from
 the VyOS CLI.
 
 .. warning:: From a security perspective it is not recommended to let a third
-  party create the private key for a secured connection. You should create the
+  party create and share the private key for a secured connection. You should create the
   private portion on your own and only hand out the public key. Please keep this
   in mind when using this convenience feature.