diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst index c1ed93366b9467574170079d0ef277292cb9200f..bc2bf7338b6cee883f390f3e97b2dc79454cb85f 100644 --- a/docs/features/vpn.rst +++ b/docs/features/vpn.rst @@ -1,57 +1,121 @@ -Mesh-VPN +Mesh VPN ======== -Gluon integrates several OSI-Layer 2 tunneling protocols to -enable interconnects between local meshes and provide -internetwork access. Available protocols currently are: +Gluon integrates several layer 2 tunneling protocols to +allow connections between local meshes through the internet. -- fastd -- L2TPv3 (via tunneldigger) +Protocol handlers +^^^^^^^^^^^^^^^^^ -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 -context-switches when forwarding packets. - -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. +and authentication. +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. + +mesh-vpn-tunneldigger +~~~~~~~~~~~~~~~~~~~~~ + +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 -toggleable encryption in the config mode with the intent to -increase throughput, although in practice the gain is minimal. +The following methods are currently recommended: -**Site configuration:** +- ``salsa2012+umac``: Encrypted + authenticated +- ``null+salsa2012+umac``: Unencrypted, authenticated +- ``null@l2tp``: Unencrypted, unauthenticated -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) +Multiple methods can be listed in ``site.conf``. The first listed method +supported by both the node and its peer will be used. -**Gateway configuration:** +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``. -1) Prepend the ``null`` cipher in fastd's method list +Configurable Method +~~~~~~~~~~~~~~~~~~~ +From the site configuration, fastd can be allowed to offer +toggleable encryption in the config mode with the intent to +increase throughput. + +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. + +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@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 +<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, fastd's unix -socket can be interrogated, after installing for example `socat`. - -:: - - opkg update - opkg install socat - socat - UNIX-CONNECT:/var/run/fastd.mesh_vpn.socket +To confirm whether the correct cipher is being used, the log output +of fastd can be checked using ``logread``.