nils/gluon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #2351 from lemoer/pr_docs_wireguard

Browse Source 
docs: add docs for gluon-mesh-vpn-wireguard
This commit is contained in:
David Bauer 2022-06-09 21:39:22 +02:00 committed by GitHub
commit fa021884cc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 289 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/features/vpn.rst
View File

@ -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/>`__.

1
docs/index.rst
View File

@ -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

81
docs/user/faq.rst
View File

@ -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.

220
docs/user/mtu.rst Normal file
View File

@ -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).

18
docs/user/site.rst
View File

@ -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 = {