diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst index bc2bf733..7f9b7bc2 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 `__. + +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 `__. diff --git a/docs/user/faq.rst b/docs/user/faq.rst index d40fcb5c..149a76d1 100644 --- a/docs/user/faq.rst +++ b/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). diff --git a/docs/user/site.rst b/docs/user/site.rst index 1784e0ff..e9c2e729 100644 --- a/docs/user/site.rst +++ b/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 = {