From cbef4c299a90ed2c371b9620f513e1f4cfde863f Mon Sep 17 00:00:00 2001 From: Tom Herbers Date: Mon, 15 Aug 2022 15:04:33 +0200 Subject: [PATCH 1/2] docs: vpn: fix titles and move fastd Supernode / Gateway Configuration --- docs/features/vpn.rst | 56 +++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 32 deletions(-) diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst index 7f9b7bc2..cf6c7ea7 100644 --- a/docs/features/vpn.rst +++ b/docs/features/vpn.rst @@ -11,7 +11,7 @@ There are currently three protocol handlers which can be selected via ``GLUON_FEATURES`` in ``site.mk``: mesh-vpn-fastd -~~~~~~~~~~~~~~ +"""""""""""""" fastd is a lightweight userspace tunneling daemon that implements cipher suites that are specifically designed @@ -25,7 +25,7 @@ at the cost of losing the ability to protect tunnel connections against eavesdropping or manipulation. mesh-vpn-tunneldigger -~~~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""""" Tunneldigger always uses L2TPv3, generally achieving the same performance as fastd with the ``null@l2tp`` method, but offering @@ -34,7 +34,7 @@ Tunneldigger's primary drawback is the lack of IPv6 support. It also provides less configurability than fastd. mesh-vpn-wireguard -~~~~~~~~~~~~~~~~~~ +"""""""""""""""""" WireGuard is an encrypted in-kernel tunneling protocol that provides encrypted transmission and at the same time offers @@ -44,7 +44,7 @@ fastd ^^^^^ Methods -~~~~~~~ +""""""" fastd offers various different connection "methods" with different security properties that can be configured in the site configuration. @@ -63,8 +63,24 @@ considerable performance gain, especially on weaker embedded hardware. For L2TP offloading, the ``mesh-vpn-fastd-l2tp`` feature needs to be enabled in ``site.mk``. + +.. _vpn-gateway-configuration: + +Gateway / Supernode Configuration +""""""""""""""""""""""""""""""""" + +When only using the ``null`` or ``null@l2tp`` methods without offloading, +simply add these methods to the front of the method list. ``null@l2tp`` +should always appear before ``null`` in the configuration when both are enabled. +fastd v22 or newer is needed for the ``null@l2tp`` method. + +It is often not necessary to enable L2TP offloading on supernodes for +performance reasons. Nodes using offloading can communicate with supornodes that +don't use offloading as long as both use the ``null@l2tp`` method. + + Configurable Method -~~~~~~~~~~~~~~~~~~~ +""""""""""""""""""" From the site configuration, fastd can be allowed to offer toggleable encryption in the config mode with the intent to @@ -76,7 +92,7 @@ performance gains provided by the latter (compared to the encrypted and authenticated methods) are very small. Site configuration ------------------- +~~~~~~~~~~~~~~~~~~ 1) Add the feature ``web-mesh-vpn-fastd`` in ``site.mk`` @@ -86,32 +102,8 @@ Site configuration Optionally, add ``null@l2tp`` to the ``mesh_vpn.fastd.methods`` table if you want "Performance mode" as default (not recommended) -Gateway / Supernode Configuration ---------------------------------- - -When only using the ``null`` or ``null@l2tp`` methods without offloading, -simply add these methods to the front of the method list. ``null@l2tp`` -should always appear before ``null`` in the configuration when both are enabled. -fastd v22 or newer is needed for the ``null@l2tp`` method. - -It is often not necessary to enable L2TP offloading on supernodes for -performance reasons. Nodes using offloading can communicate with supornodes that -don't use offloading as long as both use the ``null@l2tp`` method. - -To enable L2TP offloading on the supornodes as well, it is recommended to study -the fastd documentation section pertaining to the `offload configuration option -`_. - -Note that in ``multitap`` mode, which is required when using -L2TP offloading, fastd will create one interface per peer -on the supernode's side and it is the administrator's -responsibility to ensure that these interfaces are handled correctly. -In batman-adv-based setups this involves adding the dynamically created -interfaces to an batadv interface using fastd's ``on up`` scripts or some -network configuration daemon like systemd-networkd. - Config Mode ------------ +~~~~~~~~~~~ The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport. @@ -158,7 +150,7 @@ 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 From e2064e36e319fd34b6c9e3b60c5de13938a2211d Mon Sep 17 00:00:00 2001 From: Tom Herbers Date: Mon, 15 Aug 2022 15:09:07 +0200 Subject: [PATCH 2/2] docs: vpn: add fastd Supernode offloading recommendations closes freifunk-gluon/gluon#2603 Co-authored-by: Martin Weinelt --- docs/features/vpn.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst index cf6c7ea7..95d0ee27 100644 --- a/docs/features/vpn.rst +++ b/docs/features/vpn.rst @@ -79,6 +79,46 @@ performance reasons. Nodes using offloading can communicate with supornodes that don't use offloading as long as both use the ``null@l2tp`` method. +.. _vpn-gateway-configuration-offloading: + +Offloading on Gateways / Supernodes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable L2TP offloading on the supornodes, it is recommended to study the +fastd documentation section pertaining to the `offload configuration option +`_. + +However, the important changes to the fastd config on your Supernode are: + + - | Set ``mode multitap;`` + | Every peer gets their own interface. + + - | Replace ``interface "foo":`` with ``interface "peer-%k";`` + | ``%k`` is substituted for a portion of the peers public key. + + - | Set ``offload l2tp yes;`` + | This tells fastd to use the l2tp kernel module. + + - | Set ``persist interface no;`` + | This tells fastd to only keep interfaces arround while the connection is active. + +Note that in ``multitap`` mode, which is required when using L2TP offloading, +fastd will create one interface per peer on the supernode's. This allows +offloading the L2TP forwarding into the kernel space. But this also means added +copmlexity with regards to handling those interfaces. + +There are two main options on how you can handle this: + + - create ``on up`` and ``on down`` hooks + + - to handle interface setup and destruction + - preferrably using the async keyword, so hooks are not blocking fastd + + - use a daemon like systemd-networkd + +Examples for both options can be found in the +`Wiki `_. + Configurable Method """""""""""""""""""