Merge pull request #2351 from lemoer/pr_docs_wireguard

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/index.rst

@@ -14,6 +14,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
    user/supported_devices
    user/x86
    user/faq
+   user/mtu
 
 .. toctree::
    :caption: Features

docs/user/faq.rst

@@ -25,84 +25,3 @@ interface. This DNS server must be announced in router advertisements (using
 on *batman-adv*. If your mesh does not have global IPv6 connectivity, you can setup
 your *radvd* not to announce a default route by setting the *default lifetime* to 0;
 in this case, the *radvd* is only used to announce the DNS server.
-
-.. _faq-mtu:
-
-What is a good MTU on the mesh-vpn?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Setting the MTU on the transport interface requires careful consideration, as
-setting it too low will cause excessive fragmentation and setting it too high
-may leave peers with a broken tunnel due to packet loss.
-
-Consider these key values:
-
-- Payload: Allow for the transport of IPv6 packets, by adhering to the minimum MTU
-  of 1280 Byte specified in RFC 2460
-  - and configure `MSS clamping`_ accordingly,
-  - and announce your link MTU via Router Advertisements and DHCP
-
-  .. _MSS clamping: https://www.tldp.org/HOWTO/Adv-Routing-HOWTO/lartc.cookbook.mtu-mss.html
-
-- Encapsulation: Account for the overhead created by the configured mesh protocol
-  encapsulating the payload, which is up to 32 Byte (14 Byte Ethernet + 18 Byte
-  batadv).
-
-- PMTU: What MTU does the path between your gateway and each of its peers support?
-
-For reference, the complete MTU stack looks like this:
-
-.. image:: mtu-diagram_v5.png
-
-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
-lower would cause unnecessary fragmentation for clients which respect the announced
-link MTU.
-
-Example: Our network currently uses batman-adv v15, it therefore requires up
-to 32 Bytes of encapsulation overhead on top of the minimal link MTU required for
-transporting IPv6.::
-
-  \        1312              1294          1280                                 0
-   \---------+-----------------+-------------+----------------------------------+
-    \TAP     |    batadv v15   |   Ethernet  |            Payload               |
-     \-------+-----------------+-------------+----------------------------------+
-      \      ^
-             |
-
-          MTU_LOW = 1280 Byte + 14 Byte + 18 Byte = 1312 Byte
-
-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
-as you have to take into account the tunneling overhead and each peers PMTU, which
-varies between providers.
-The underlying reasons are mostly PPPoE, Tunneling and IPv6 transition technologies
-like DS-Lite.
-
-Example: The peer with the smallest MTU on your network is behind DS-Lite and can
-transport IPv4 packets up to 1436 Bytes in size. Your tunnel uses IPv4 (20 Byte),
-UDP (8 Byte), Fastd (24 byte) and you require TAP (14 Byte) for Layer 2 (Ethernet)
-Tunneling.::
-
-  1436                1416     1408                    1384          1370    \
-    +-------------------+--------+-----------------------+-------------+------\
-    |        IP         |  UDP   |         Fastd         |     TAP     |    bat\
-    +-------------------+--------+-----------------------+-------------+--------\
-                                                                       ^         \
-                                                                       |
-
-       MTU_HIGH = 1436 Byte - 20 Byte - 8 Byte - 24 Byte - 14 Byte = 1370 Byte
-
-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.

docs/user/mtu.rst

+MTU for Mesh-VPN
+================
+
+What is a good MTU on the mesh-vpn?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Setting the MTU on the transport interface requires careful consideration, as
+setting it too low will cause excessive fragmentation and setting it too high
+may leave peers with a broken tunnel due to packet loss.
+
+Consider these key values:
+
+- Payload: Allow for the transport of IPv6 packets, by adhering to the minimum MTU
+  of 1280 Byte specified in RFC 2460
+  - and configure `MSS clamping`_ accordingly,
+  - and announce your link MTU via Router Advertisements and DHCP
+
+  .. _MSS clamping: https://www.tldp.org/HOWTO/Adv-Routing-HOWTO/lartc.cookbook.mtu-mss.html
+
+- Encapsulation: Account for the overhead created by the configured mesh protocol
+  encapsulating the payload, which is up to 32 Byte (14 Byte Ethernet + 18 Byte
+  batadv).
+
+- PMTU: What MTU does the path between your gateway and each of its peers support?
+
+For reference, the complete MTU stack looks like this:
+
+.. image:: mtu-diagram_v5.png
+
+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
+lower would cause unnecessary fragmentation for clients which respect the announced
+link MTU.
+
+Example: Our network currently uses batman-adv v15, it therefore requires up
+to 32 Bytes of encapsulation overhead on top of the minimal link MTU required for
+transporting IPv6.::
+
+  \        1312              1294          1280                                 0
+   \---------+-----------------+-------------+----------------------------------+
+    \TAP     |    batadv v15   |   Ethernet  |            Payload               |
+     \-------+-----------------+-------------+----------------------------------+
+      \      ^
+             |
+
+          MTU_LOW = 1280 Byte + 14 Byte + 18 Byte = 1312 Byte
+
+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
+as you have to take into account the tunneling overhead and each peers PMTU, which
+varies between providers.
+The underlying reasons are mostly PPPoE, Tunneling and IPv6 transition technologies
+like DS-Lite.
+
+Example: The peer with the smallest MTU on your network is behind DS-Lite and can
+transport IPv4 packets up to 1436 Bytes in size. Your tunnel uses IPv4 (20 Byte),
+UDP (8 Byte), Fastd (24 byte) and you require TAP (14 Byte) for Layer 2 (Ethernet)
+Tunneling.::
+
+  1436                1416     1408                    1384          1370    \
+    +-------------------+--------+-----------------------+-------------+------\
+    |        IP         |  UDP   |         Fastd         |     TAP     |    bat\
+    +-------------------+--------+-----------------------+-------------+--------\
+                                                                       ^         \
+                                                                       |
+
+       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 an MTU of 1312 bytes (for fastd and tunneldigger)
+and 1376 bytes (for WireGuard).

docs/user/site.rst

@@ -288,7 +288,7 @@ mesh_vpn
 
   The `enabled` option can be set to true to enable the VPN by default. `mtu`
   defines the MTU of the VPN interface, determining a proper MTU value is described
-  in the :ref:`FAQ <faq-mtu>`.
+  in :doc:`mtu`.
 
   By default the public key of a node's VPN daemon is not added to announced respondd
   data; this prevents malicious ISPs from correlating VPN sessions with specific mesh
@@ -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 = {