From 655da235208420c0787e4da6bf75877705c8e790 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Fri, 6 Jul 2018 18:55:25 +0200 Subject: [PATCH] docs: features/wired-mesh: add section about VXLAN encapsulation --- docs/features/wired-mesh.rst | 58 +++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/docs/features/wired-mesh.rst b/docs/features/wired-mesh.rst index 2358e276..efa1977a 100644 --- a/docs/features/wired-mesh.rst +++ b/docs/features/wired-mesh.rst @@ -1,5 +1,5 @@ Wired mesh (Mesh-on-WAN/LAN) -============================ +############################ In addition to meshing over WLAN and VPN, it is also possible to configure wired meshing over the LAN or WAN ports. This allows @@ -11,12 +11,41 @@ Enabling Mesh-on-WAN should be avoided if the local network is also bridged with a WLAN access point, as meshing over batman-adv causes large amounts of multicast traffic, which will take up a lot of airtime. -Enabling Mesh-on-LAN will replace the normal "client network" function +Enabling Mesh-on-LAN replaces the normal "client network" function of the LAN ports, as client network ports may never be connected (so care must be taken to always enable Mesh-on-LAN before connecting two nodes' LAN ports). +Wired mesh encapsulation +************************ + +Since version 2018.1, Gluon supports encapsulating wired mesh traffic in +`VXLAN `_, a new standard with +usecases similar to VLANs, but a much greater ID space of 24bit; in addition, VXLAN +packets pass through VLAN-aware switches without any special configuration. + +Encapsulating mesh traffic has two advantages: + +* By using a different VXLAN ID for each site and mesh domain, accidental + wired mesh connections between nodes of different domains will be prevented. + This has special importance when nodes migrate between domains automatically, + as currently possible through different site-specific packages. +* While batman-adv traffic does not interact with non-mesh traffic in the same wired + network in any way (so Gluon nodes can mesh over existing wired networks), this is + not the case for layer 3 mesh protocols like Babel. Encapsulating the traffic allows + to distinguish mesh traffic from unrelated packets. + +As enabling VXLAN encapsulation will prevent wired mesh communication with old nodes +that do not support VXLAN yet, VXLANs can be enabled per-domain using the site configuration +setting *mesh.vxlan*. VXLAN is enabled by default in multidomain setups; in single-domain +site configurations, the *mesh.vxlan* setting is mandatory. We recommend to enable +VXLAN encapsulation in all new sites and domains. + +Non-encapsulated ("legacy") wired meshing will be removed in a future Gluon release. +We cannot give a concrete timeframe for the removal yet; a missing prerequisite is the +implementation of a robust migration path for existing deployments. + Configuration -~~~~~~~~~~~~~ +************* Both Mesh-on-WAN and Mesh-on-LAN can be configured on the "Network" page of the *Advanced settings* (if the package ``gluon-web-network`` is installed). @@ -24,27 +53,20 @@ of the *Advanced settings* (if the package ``gluon-web-network`` is installed). It is also possible to enable Mesh-on-WAN and Mesh-on-LAN by default by adding ``mesh_on_wan = true`` and ``mesh_on_lan = true`` to ``site.conf``. -Commandline configuration -------------------------- +Commandline +=========== -Mesh-on-WAN -........... - -It's possible to enable Mesh-on-WAN like this:: +Enable Mesh-on-WAN:: uci set network.mesh_wan.disabled=0 uci commit network -It may be disabled by running:: +Disable Mesh-on-WAN:: uci set network.mesh_wan.disabled=1 uci commit network - -Mesh-on-LAN -........... - -Configuring Mesh-on-LAN is a bit more complicated:: +Enable Mesh-on-LAN:: uci set network.mesh_lan.disabled=0 for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do @@ -52,7 +74,7 @@ Configuring Mesh-on-LAN is a bit more complicated:: done uci commit network -It may be disabled by running:: +Disable Mesh-on-LAN:: uci set network.mesh_lan.disabled=1 for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do @@ -60,6 +82,6 @@ It may be disabled by running:: done uci commit network -Please note that this configuration has changed in Gluon v2016.1. Using -the old commands on v2016.1 and later will break the corresponding options +Please note that this configuration has changed in Gluon 2016.1. Using +the old commands on 2016.1 and later will break the corresponding options in the *Advanced settings*.