docs: update Mesh VPN documentation

- Restructure page
- Add information on how to add L2TPv3 offloading support to a build
  using configurable ciphers. The null method is not reocmmended anymore.
- 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.
- Mention wireguard support

Based-on-patch-by: Felix Kaechele <felix@kaechele.ca>

docs/features/vpn.rst

@@ -1,57 +1,121 @@
-Mesh-VPN
+Mesh VPN
 ========
 
-Gluon integrates several OSI-Layer 2 tunneling protocols to
+Gluon integrates several layer 2 tunneling protocols to
-enable interconnects between local meshes and provide
+allow connections between local meshes through the internet.
-internetwork access. Available protocols currently are:
 
-- fastd
+Protocol handlers
-- L2TPv3 (via tunneldigger)
+^^^^^^^^^^^^^^^^^
 
-fastd is a lightweight userspace tunneling daemon, that
+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
 to work well on embedded devices. It offers encryption
-and authentication. Its primary drawback are the necessary
+and authentication.
-context-switches when forwarding packets.
+The primary drawback of fastd's encrypted connection modes
+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 protect tunnel connections
+against eavesdropping or manipulation.
 
-L2TPv3 is an in-kernel tunneling protocol that performs well,
+mesh-vpn-tunneldigger
-but offers no security properties by itself.
+~~~~~~~~~~~~~~~~~~~~~
-The brokering of the tunnel happens through tunneldigger,
+
-its primary drawback being the lack of IPv6 support.
+Tunneldigger always uses L2TPv3, generally achieving the same
+performance as fastd with the ``null@l2tp`` method, but offering
+no security.
+Tunneldigger's primary drawback is the lack of IPv6 support.
+It also provides less configurability than fastd.
+
+mesh-vpn-wireguard (experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
 
 fastd
------
+^^^^^
 
-Configurable Cipher
+Methods
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~
 
+fastd offers various different connection "methods" with different
+security properties that can be configured in the site configuration.
 
-From the site configuration fastd can be allowed to offer
+The following methods are currently recommended:
+
+- ``salsa2012+umac``: Encrypted + authenticated
+- ``null+salsa2012+umac``: Unencrypted, authenticated
+- ``null@l2tp``: Unencrypted, unauthenticated
+
+Multiple methods can be listed in ``site.conf``. The first listed method
+supported by both the node and its peer will be used.
+
+The use of the ``null@l2tp`` method with offloading enabled can provide a
+considerable performance gain, especially on weaker embedded hardware.
+For L2TP offloading, the ``mesh-vpn-fastd-l2tp`` feature needs to be enabled in
+``site.mk``.
+
+Configurable Method
+~~~~~~~~~~~~~~~~~~~
+
+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.
 
-**Site configuration:**
+There is also an older unprotected method ``null``. Use of the newer
+``null@l2tp`` method is generally recommended over ``null``, as the
+performance gains provided by the latter (compared to the encrypted
+and authenticated methods) are very small.
 
-1) Add the feature ``web-mesh-vpn-fastd`` in ``site.mk``
+Site configuration
-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)
 
-**Gateway 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@l2tp`` to the ``mesh_vpn.fastd.methods`` table if you want
+  "Performance mode" as default (not recommended)
 
-1) Prepend the ``null`` cipher in fastd's method list
+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
+<https://fastd.readthedocs.io/en/stable/manual/config.html#option-offload>`_.
+
+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
+-----------
 
-**Config Mode:**
 The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport.
 
 .. image:: fastd_mode.gif
 
-**Unix socket:**
+To confirm whether the correct cipher is being used, the log output
-To confirm whether the correct cipher is being used, fastd's unix
+of fastd can be checked using ``logread``.
-socket can be interrogated, after installing for example `socat`.
-
-::
-
-  opkg update
-  opkg install socat
-  socat - UNIX-CONNECT:/var/run/fastd.mesh_vpn.socket