wireguard: updated wireguard docs for crux branch (#574)

* updated wireguard docs for crux branch

* modified commands for crux

* replaced interface address with endpoint & ports

1 files changed, 252 insertions, 81 deletions

diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst
index a7241613..d738c017 100644
--- a/docs/configuration/interfaces/wireguard.rst
+++ b/docs/configuration/interfaces/wireguard.rst
@@ -1,148 +1,319 @@
 .. _wireguard:
 
-WireGuard VPN Interface
------------------------
+#########
+WireGuard
+#########
 
 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
-^^^^^^^^^^^^^
+*************
 
-Wireguard requires the generation of a keypair, a private key which will decrypt
-incoming traffic and a public key, which the peer(s) will use to encrypt traffic.
 
-Generate a keypair
-~~~~~~~~~~~~~~~~~~
 
-Generate the keypair, which creates a public and private part and stores it
-within VyOS.
-It will be used per default on any configured wireguard interface, even if
-multiple interfaces are being configured.
+********
+Keypairs
+********
 
-.. code-block:: none
+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.
 
-  wg01:~$ configure
-  wg01# run generate wireguard keypair
+Generate Keypair
+================
 
-The public key is being shared with your peer(s), your peer will encrypt all
-traffic to your system using this public key.
+.. opcmd:: generate wireguard keypair
 
-.. code-block:: none
+   It generates the keypair, which includes the public and private parts,
+   and stores it within VyOS. It will be used per default on any configured
+   WireGuard interface, even if multiple interfaces are being configured.
+
+.. opcmd:: show wireguard pubkey 
+
+   It shows the public key to be shared with your peer(s). Your peer will
+   encrypt all traffic to your system using this public key.
 
-  wg01# run show wireguard pubkey
-  u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=
+   .. code-block:: none
 
-Wireguard Interface configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+     vyos@vyos:~$ show wireguard pubkey
+     hW17UxY7zeydJNPIyo3UtGnBHkzTK/NeBOrDSIU9Tx0=
 
-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.
+***********************
+Interface configuration
+***********************
 
-**local side**
+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 address/port is optional; however, if you act as a
+server and endpoints initiate the connections to your system, you need to
+define a port your clients can connect to, otherwise the port is randomly
+chosen and may make connection difficult with firewall rules, since the port
+may be different each time the system is rebooted.
+
+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 - 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 endpoint '192.168.0.142:12345'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24'
+  set interfaces wireguard wg01 peer to-wg02 endpoint '<Site1 Pub IP:51820>
   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
+  set interfaces wireguard wg01 port '51820'
+  set protocols static route 192.168.2.0/24 interface wg01
 
-.. note:: The `endpoint` must be an IP and not a fully qualified domain name (FQDN). Using a FQDN will result in unexpected behavior.
+**local side - annotated commands**
 
-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.
+.. 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 endpoint '<Site1 Pub IP:51820>
+  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
+defined and routed. The last check is allowed-ips which either prevents
+or allows the traffic.
 
-**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 endpoint '192.168.0.124:12345'
+  set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24'
+  set interfaces wireguard wg01 peer to-wg02 endpoint '<Site1 Pub IP:51820>
   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
+  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 endpoint '<Site1 Pub IP:51820>
+  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
+
+    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
+
+    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.
+Assure that your firewall rules allow the traffic, in which case you have a working VPN using WireGuard.
 
 .. 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
+  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 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
+  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, which is optional.
+asymmetric crypto. This is optional.
 
 .. code-block:: none
 
   wg01# run generate wireguard preshared-key
   rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=
 
-Copy the key, as it is not stored on the local file system. Make sure you
-distribute that key in a safe manner, it's a symmetric key, so only you and
-your peer should have knowledge of its content.
+Copy the key, as it is not stored on the local filesystem. Because it
+is a symmetric key, only you and your peer should have knowledge of
+its content. Make sure you distribute the key in a safe manner,
 
 .. code-block:: none
 
   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='
 
-Operational commands
-^^^^^^^^^^^^^^^^^^^^
 
-**Show interface status**
+***********************************
+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.
+
+In the following example, the IPs for the remote clients are defined in
+the peers. This allows the peers to interact with one another.
 
 .. code-block:: none
 
-  vyos@wg01# run show interfaces wireguard wg01
+    wireguard wg0 {
+        address 10.172.24.1/24
+        address 2001:DB8:470:22::1/64
+        description RoadWarrior
+        peer MacBook {
+            allowed-ips 10.172.24.30/32
+            allowed-ips 2001:DB8:470:22::30/128
+            persistent-keepalive 15
+            pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc=
+        }
+        peer iPhone {
+            allowed-ips 10.172.24.20/32
+            allowed-ips 2001:DB8:470:22::20/128
+            persistent-keepalive 15
+            pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00=
+        }
+        port 2224
+    }
+
+The following is the config for the iPhone peer above. It's important to
+note that the ``AllowedIPs`` wildcard setting directs all IPv4 and IPv6 traffic
+through the connection.
+
+.. code-block:: none
 
-  interface: wg01
-  public key: xHvgSJC8RTClfvjc0oX6OALxU6GGLapjthjw7x82CSw=
-  private key: (hidden)
-  listening port: 12345
+    [Interface]
+    PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf=
+    Address = 10.172.24.20/24, 2001:DB8:470:22::20/64
+    DNS = 10.0.0.53, 10.0.0.54
 
-  peer: 9Ek3R30mG6Vk+GHsENtPF0b9Ul+ftxx4dDBa1bdBxX8=
-  endpoint: 192.168.0.142:12345
-  allowed ips: 10.2.0.0/24
-  latest handshake: 4 minutes, 22 seconds ago
-  transfer: 860 B received, 948 B sent
+    [Peer]
+    PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+    AllowedIPs = 0.0.0.0/0, ::/0
+    Endpoint = 192.0.2.1:2224
+    PersistentKeepalive = 25
 
-**Show public key of the default key**
+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
 
-  vyos@wg01# run show wireguard keypair pubkey default
-  FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM=
+    [Interface]
+    PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go=
+    Address = 10.172.24.30/24, 2001:DB8:470:22::30/64
 
+    [Peer]
+    PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc=
+    AllowedIPs = 10.172.24.30/24, 2001:DB8:470:22::/64
+    Endpoint = 192.0.2.1:2224
+    PersistentKeepalive = 25
 
-**Delete wireguard keypairs**
 
-.. code-block:: none
+********************
+Operational Commands
+********************
+
+Status
+======
+
+.. opcmd:: show interfaces wireguard
+
+  Get a list of all wireguard interfaces
+
+  .. code-block:: none
+
+    Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+    Interface        IP Address                        S/L  Description
+    ---------        ----------                        ---  -----------
+    wg0              10.0.0.1/24                       u/u
+
+
+.. opcmd:: show interfaces wireguard <interface>
+
+  Show general information about specific WireGuard interface
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show interfaces wireguard wg01
+    interface: wg0
+      address: 10.0.0.1/24
+      public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE=
+      private key: (hidden)
+      listening port: 41751
+
+        RX:  bytes  packets  errors  dropped  overrun       mcast
+                 0        0       0        0        0           0
+        TX:  bytes  packets  errors  dropped  carrier  collisions
+                 0        0       0        0        0           0
+
+***************
+Encryption Keys
+***************
+
+.. opcmd:: show wireguard keypair pubkey <name>
+
+  Show public key portion for specified key. This can be either the ``default``
+  key, or any other named key-pair.
+
+  The ``default`` keypair
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show wireguard keypair pubkey default
+    FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM=
+
+  Name keypair ``KP01``
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show wireguard keypair pubkey KP01
+    HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM=
+
+.. opcmd:: delete wireguard keypair pubkey <name>
+
+  Delete a keypair, this can be either the ``default`` key, or any other
+  named key-pair.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ delete wireguard keypair default
+
+.. stop_vyoslinter
 
-  vyos@wg01# wireguard keypair default
+.. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html
 
+.. start_vyoslinter