docs: add docs for gluon-mesh-vpn-wireguard

docs/features/vpn.rst

@@ -33,12 +33,12 @@ no security.
 Tunneldigger's primary drawback is the lack of IPv6 support.
 It also provides less configurability than fastd.
 
-mesh-vpn-wireguard (experimental)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+mesh-vpn-wireguard
+~~~~~~~~~~~~~~~~~~
 
-Wireguard is a new tunneling software that offers modern encryption
-methods and is implemented in the kernel, resulting in high throughput.
-It is implemented in Gluon using the *wgpeerselector* tool.
+WireGuard is an encrypted in-kernel tunneling protocol that
+provides encrypted transmission and at the same time offers
+high throughput.
 
 fastd
 ^^^^^
@@ -119,3 +119,50 @@ The resulting firmware will allow users to choose between secure (encrypted) and
 
 To confirm whether the correct cipher is being used, the log output
 of fastd can be checked using ``logread``.
+
+WireGuard
+^^^^^^^^^
+
+In order to support WireGuard in Gluon, a few technologies are glued together.
+
+**VXLAN:** As Gluon typically relies on batman-adv, the Mesh VPN has to provide
+OSI Layer 2 transport. But WireGuard is an OSI Layer 3 tunneling protocol, so
+additional technology is necessary here. For this, we use VXLAN. In short, VXLAN
+is a well-known technology to encapsulate ethernet packages into IP packages.
+You can think of it as kind of similar to VLAN, but on a different layer. Here,
+we use VXLAN to transport batman-adv traffic over WireGuard.
+
+**wgpeerselector**: To connect all gluon nodes to each other, it is common to
+create a topology where each gluon node is connected to one of the available
+gateways via Mesh VPN respectively. To achieve this, the gluon node should be
+able to select a random gateway to connect to. But such "random selection of a
+peer" is not implemented in WireGuard by default. WireGuard only knows static
+peers. Therefore the *wgpeerselector* has been developed. It randomly selects a
+gateway, tries to establish a connection, and if it fails, tries to connect
+to the next gateway. This approach has several advantages, such as load
+balancing VPN connection attempts and avoiding problems with offline gateways.
+More information about the wgpeerselector and its algorithm can be found
+`here <https://github.com/freifunk-gluon/packages/blob/master/net/wgpeerselector/README.md>`__.
+
+On the gluon node both VXLAN and the wgpeerselector are well integrated and no
+explicit configuation of those tools is necessary, once the general WireGuard
+support has been configured.
+
+Attention must by paid to time synchronization. As WireGuard
+performs checks on timestamps in order to avoid replay attacks, time must
+be synchronized before the Mesh VPN connection is established. This means that
+the NTP servers specified in your site.conf must be publicly available (and not
+only through the mesh). Be aware that if you fail this, you may not directly see
+negative effects. Only when a previously connected node reboots the effect
+comes into play, as the gateway still knows about the old timestamp of the gluon
+node.
+
+Gateway / Supernode Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the gateway side, a software called *wireguard-vxlan-glue* is necessary. It
+is a small daemon that dynamically adds and removes forwarding rules for VXLAN
+interfaces, so traffic is sent correctly into the WireGuard interface. Thereby
+the forwarding rules are only installed if a client is connected, so
+unnecessary traffic in the kernel is avoided. The source can be found
+`here <https://github.com/freifunkh/wireguard-vxlan-glue/>`__.

docs/user/faq.rst

@@ -54,8 +54,8 @@ For reference, the complete MTU stack looks like this:
 
 .. image:: mtu-diagram_v5.png
 
-Minimum MTU
------------
+Example for Minimum MTU
+-----------------------
 
 Calculate the minimum transport MTU by adding the encapsulation overhead to the
 minimum payload MTU required. This is the lowest recommended value, since going
@@ -75,8 +75,8 @@ transporting IPv6.::
 
           MTU_LOW = 1280 Byte + 14 Byte + 18 Byte = 1312 Byte
 
-Maximum MTU
------------
+Example for Maximum MTU
+-----------------------
 
 Calculating the maximum transport MTU is interesting, because it increases the
 throughput, by allowing larger payloads to be transported, but also more difficult
@@ -99,10 +99,149 @@ Tunneling.::
 
        MTU_HIGH = 1436 Byte - 20 Byte - 8 Byte - 24 Byte - 14 Byte = 1370 Byte
 
+
+Tables for Different VPN Providers
+----------------------------------
+
+VPN Protocol Overhead (IPv4)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Overhead of the VPN protocol layers in bytes on top of an Ethernet frame.
+
++----------+-------+--------------+-----------+
+|          | fastd | Tunneldigger | Wireguard |
++==========+=======+==============+===========+
+| IPv4     | 20    | 20           | 20        |
++----------+-------+--------------+-----------+
+| UDP      | 8     | 8            | 8         |
++----------+-------+--------------+-----------+
+| Protocol | 24    | 8            | 32        |
++----------+-------+--------------+-----------+
+| TAP      | 14    | 14           | /         |
++----------+-------+--------------+-----------+
+| Sum      | 66    | 50           | 60        |
++----------+-------+--------------+-----------+
+
+Intermediate Layer Overhead
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Overhead of additional layers on top of the VPN packet needed for different VPN
+providers.
+
++------------+-------+--------------+-----------+
+|            | fastd | Tunneldigger | Wireguard |
++============+=======+==============+===========+
+| IPv6       | /     | /            | 40        |
++------------+-------+--------------+-----------+
+| vxlan      | /     | /            | 16        |
++------------+-------+--------------+-----------+
+| Ethernet   | /     | /            | 14        |
++------------+-------+--------------+-----------+
+| Batman v15 | 18    | 18           | 18        |
++------------+-------+--------------+-----------+
+| Ethernet   | 14    | 14           | 14        |
++------------+-------+--------------+-----------+
+| Sum        | 32    | 32           | 102       |
++------------+-------+--------------+-----------+
+
+Minimum MTU
+^^^^^^^^^^^
+
+Calculation of different derived MTUs based on a 1280 byte payload to
+avoid fragmentation.
+
+Suggestions:
+
+- This configuration is only suggested for fastd and Tunneldigger.
+
+- For WireGuard, this configuration is **unsuitable**. To obtain a 1280 byte
+  payload with our protocol stack (see below), the Ethernet frame payload would
+  be 1442 bytes long (for IPv4). As we assume that the WAN network might have
+  a (worst case) MTU of only 1436 (with DSLite), this packet would be too long
+  for the WAN network.
+
++-------------------------------+-------+--------------+-----------+
+|                               | fastd | Tunneldigger | Wireguard |
++===============================+=======+==============+===========+
+| max unfragmented payload\*    | 1280  | 1280         | 1280      |
++-------------------------------+-------+--------------+-----------+
+| intermed layer overhead       | 32    | 32           | 102       |
++-------------------------------+-------+--------------+-----------+
+| VPN MTU\*\*                   | 1312  | 1312         | 1382      |
++-------------------------------+-------+--------------+-----------+
+| protocol overhead (IPv4)      | 66    | 50           | 60        |
++-------------------------------+-------+--------------+-----------+
+| min acceptable WAN MTU (IPv4) | 1378  | 1362         | **1442**  |
++-------------------------------+-------+--------------+-----------+
+| min acceptable WAN MTU (IPv6) | 1398  | 1382         | 1462      |
++-------------------------------+-------+--------------+-----------+
+
+\* Maximum size of payload going into the bat0 interface, that will not be
+fragmented by batman.
+
+\*\* This is the MTU that is set in the site.conf.
+
+Maximum MTU
+^^^^^^^^^^^
+
+Calculation of different derived MTUs based on a maximum WAN MTU of 1436.
+
+Sugestions:
+
+- This configuration can be used for fastd and Tunneldigger.
+
+- For WireGuard, this is the recommended configuration. batman-adv will
+  fragment larger packets transparently to avoid packet loss.
+
++-------------------------------+-------+--------------+-----------+
+|                               | fastd | Tunneldigger | Wireguard |
++===============================+=======+==============+===========+
+| min acceptable WAN MTU (IPv4) | 1436  | 1436         | 1436      |
++-------------------------------+-------+--------------+-----------+
+| protocol overhead (IPv4)      | 66    | 50           | 60        |
++-------------------------------+-------+--------------+-----------+
+| VPN MTU\*\*                   | 1370  | 1386         | 1376      |
++-------------------------------+-------+--------------+-----------+
+| intermed layer overhead       | 32    | 32           | 102       |
++-------------------------------+-------+--------------+-----------+
+| max unfragmented payload\*    | 1338  | 1354         | 1274      |
++-------------------------------+-------+--------------+-----------+
+| min acceptable WAN MTU (IPv6) | 1398  | 1382         | 1462      |
++-------------------------------+-------+--------------+-----------+
+
+\* Maximum size of payload going into the bat0 interface, that will not be
+fragmented by batman.
+
+\*\* This is the MTU that is set in the site.conf.
+
+Suggested MSS Values
+^^^^^^^^^^^^^^^^^^^^
+
+It is highly advised to use MSS clamping for TCP on the gateways/supernodes in
+order to avoid the fragmentation mechanism of batman whenever possible.
+Especially on small embedded devices, fragmentation costs performance.
+
+As batmans fragmentation is transparent to the TCP layer, clamping the MSS
+automatically to the PMTU does not work. Instead, the MSS must be specified
+explicitly. In iptables, this is done via :code:`-j TCPMSS --set-mss X`,
+whereby :code:`X` is the desired MSS.
+
+Since the MSS is specified in terms of payload of a TCP packet, the MSS is
+different for IPv4 and IPv6. Here are some examples for different max
+unfragmented payloads:
+
++---------------------------------+------+------+------+------+
+| max unfragmented payload        | 1274 | 1280 | 1338 | 1354 |
++=================================+======+======+======+======+
+| suggested MSS (IPv4, -40 bytes) | 1234 | 1240 | 1298 | 1314 |
++---------------------------------+------+------+------+------+
+| suggested MSS (IPv6, -60 bytes) | 1214 | 1220 | 1278 | 1294 |
++---------------------------------+------+------+------+------+
+
 Conclusion
-----------
+^^^^^^^^^^
 
 Determining the maximum MTU can be a tedious process, especially since the PMTU
 of peers could change at any time. The general recommendation for maximized
-compatibility is therefore the minimum MTU of 1312 Byte, which works well with
-both IPv4 and IPv6.
+compatibility is therefore an MTU of 1312 bytes (for fastd and tunneldigger)
+and 1376 bytes (for WireGuard).

docs/user/site.rst

@@ -385,7 +385,21 @@ mesh_vpn
 
       tunneldigger = {
         mtu = 1312,
-        brokers = {'vpn1.alpha-centauri.freifunk.net'}
+        brokers = {'vpn1.alpha-centauri.freifunk.net'},
+      },
+
+      wireguard = {
+        mtu = 1376,
+        peers = {
+          vpn1 = {
+            public_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=',
+            endpoint = 'vpn1.alpha-centauri.freifunk.net:51810',
+          },
+          vpn2 = {
+            public_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=',
+            endpoint = 'vpn2.alpha-centauri.freifunk.net:51810',
+          },
+        },
       },
 
       bandwidth_limit = {