diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst
index bc2bf7338b6cee883f390f3e97b2dc79454cb85f..7f9b7bc277d6a959c79873431d09f52577d0d293 100644
--- a/docs/features/vpn.rst
+++ b/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/>`__.
diff --git a/docs/index.rst b/docs/index.rst
index daa91d1d340bd633aa14d71a531f8264e013f2aa..ed9aae0e868f890789af4233e6f60ae1e1d4fb35 100644
--- a/docs/index.rst
+++ b/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
diff --git a/docs/user/faq.rst b/docs/user/faq.rst
index d40fcb5c92c1135161e694de5c065e4e197416d6..ecdf798796478ddfce6f88af7d192a5305060094 100644
--- a/docs/user/faq.rst
+++ b/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.
diff --git a/docs/user/mtu.rst b/docs/user/mtu.rst
new file mode 100644
index 0000000000000000000000000000000000000000..c208ea9cb0570ba29d34b439c65a83fc01136664
--- /dev/null
+++ b/docs/user/mtu.rst
@@ -0,0 +1,220 @@
+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).
diff --git a/docs/user/site.rst b/docs/user/site.rst
index 1784e0ffced9b71e3b942464b8bb2eb00ce146b5..0dfee350fe76e5862d7b7097aeb90e91e4200ef2 100644
--- a/docs/user/site.rst
+++ b/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 = {