From d0df4c1b7263623a5c7e953b6c82290f7c6c0f8f Mon Sep 17 00:00:00 2001 From: Felix Kaechele Date: Sun, 27 Jun 2021 21:02:09 -0400 Subject: [PATCH] docs: add documentation for fastd L2TPv3 offloading Add information on how to add L2TPv3 offloading support to a build using configurable ciphers. Also add notes and pointers regarding the gateway configuration to provide gateway admins with hints on how to modify their configuration to accommodate this new feature. Signed-off-by: Felix Kaechele --- docs/features/vpn.rst | 55 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 44 insertions(+), 11 deletions(-) diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst index 8697baad..7d11c5bb 100644 --- a/docs/features/vpn.rst +++ b/docs/features/vpn.rst @@ -3,21 +3,26 @@ Mesh-VPN Gluon integrates several OSI-Layer 2 tunneling protocols to enable interconnects between local meshes and provide -internetwork access. Available protocols currently are: +internetwork access. Available protocol handlers currently are: - fastd -- L2TPv3 (via tunneldigger) +- tunneldigger fastd is a lightweight userspace tunneling daemon, that implements cipher suites that are specifically designed to work well on embedded devices. It offers encryption -and authentication. Its primary drawback are the necessary -context-switches when forwarding packets. +and authentication. Its primary drawback is the necessary +context switches when forwarding packets. +A kernel-supported L2TPv3 offloading option is available to +work around the context-switching bottleneck but it comes +at the cost of losing the ability to encrypt tunnel connections. -L2TPv3 is an in-kernel tunneling protocol that performs well, +L2TPv3 is an in-kernel tunneling protocol that performs well but offers no security properties by itself. -The brokering of the tunnel happens through tunneldigger, -its primary drawback being the lack of IPv6 support. +The brokering of the tunnel can happen through tunneldigger +or fastd (by using the ``l2tp@null`` method). +Tunneldigger's primary drawback being the lack of IPv6 support. + fastd ----- @@ -26,19 +31,47 @@ Configurable Cipher ^^^^^^^^^^^^^^^^^^^ -From the site configuration fastd can be allowed to offer +From the site configuration, fastd can be allowed to offer toggleable encryption in the config mode with the intent to -increase throughput, although in practice the gain is minimal. +increase throughput. The use of the ``l2tp@null`` method with +offloading enabled can provide a considerable performance gain, +especially on weaker embedded hardware. + +Outside of that the benefit of using the ``null`` method is minimal. **Site configuration:** 1) Add the feature ``web-mesh-vpn-fastd`` in ``site.mk`` 2) Set ``mesh_vpn.fastd.configurable = true`` in ``site.conf`` -3) Optionally add ``null`` to the ``mesh_vpn.fastd.methods`` table if you want "Performance mode" as default (not recommended) +3) Optionally, add ``null`` to the ``mesh_vpn.fastd.methods`` table if you want "Performance mode" as default (not recommended) +4) Optionally, if you are using ``l2tp@null`` you will have to add this before ``null`` in your ``mesh_vpn.fastd.methods`` **Gateway configuration:** -1) Prepend the ``null`` cipher in fastd's method list +If only using the ``null`` method without L2TP and offloading +simply prepend the ``null`` cipher in fastd's method list. + +Using the ``l2tp@null`` method with offloading requires a bit +more preparation on the gateway end. + +Aside from using a version of fastd that supports this feature, +such as v22 and newer, as well as a kernel that has L2TPv3 +support enabled, it is recommended to study the fastd +documentation section pertaining to the ``option-offload`` +`configuration option `_. +To ensure that ``l2tp@null`` is the preferred ``null`` cipher +make sure to place it before the ``null`` cipher in your +configuration. + +Note that in ``multitap`` mode, which is required when using +L2TPv3 offloading, fastd will create one interface per peer +on the gateway's side and it is the administrator's +responsibility to ensure these interfaces are handled +accordingly upon connect and disconnect using scripts and the +``on`` directives. + +For example, in batman-adv based setups this could include +adding or removing the interface from the batman-adv device. **Config Mode:**