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

docs: add documentation for fastd L2TPv3 offloading

Browse Source 
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 <felix@kaechele.ca>
This commit is contained in:
Felix Kaechele 2021-06-27 21:02:09 -04:00
parent 4985b21858
commit d0df4c1b72
1 changed files with 44 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/features/vpn.rst
View File

@ -3,21 +3,26 @@ Mesh-VPN
Gluon integrates several OSI-Layer 2 tunneling protocols to Gluon integrates several OSI-Layer 2 tunneling protocols to
enable interconnects between local meshes and provide enable interconnects between local meshes and provide
internetwork access. Available protocols currently are: internetwork access. Available protocol handlers currently are:
- fastd - fastd
- L2TPv3 (via tunneldigger) - tunneldigger
fastd is a lightweight userspace tunneling daemon, that fastd is a lightweight userspace tunneling daemon, that
implements cipher suites that are specifically designed implements cipher suites that are specifically designed
to work well on embedded devices. It offers encryption to work well on embedded devices. It offers encryption
and authentication. Its primary drawback are the necessary and authentication. Its primary drawback is the necessary
context-switches when forwarding packets. 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. but offers no security properties by itself.
The brokering of the tunnel happens through tunneldigger, The brokering of the tunnel can happen through tunneldigger
its primary drawback being the lack of IPv6 support. or fastd (by using the ``l2tp@null`` method).
Tunneldigger's primary drawback being the lack of IPv6 support.
fastd 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 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:** **Site configuration:**
1) Add the feature ``web-mesh-vpn-fastd`` in ``site.mk`` 1) Add the feature ``web-mesh-vpn-fastd`` in ``site.mk``
2) Set ``mesh_vpn.fastd.configurable = true`` in ``site.conf`` 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:** **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 <https://fastd.readthedocs.io/en/stable/manual/config.html#option-offload>`_.
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:** **Config Mode:**