docs: update for role-based interface configuration

freifunk-gluon · Feb 22, 2022 · 210cacd · 210cacd
1 parent a671b50
commit 210cacd
Show file tree

Hide file tree

Showing 6 changed files with 53 additions and 22 deletions.
diff --git a/docs/dev/wan.rst → docs/dev/uplink.rst b/docs/dev/wan.rst → docs/dev/uplink.rst
@@ -1,5 +1,5 @@
-WAN support
-===========
+Uplink support
+==============
 
 As the WAN port of a node will be connected to a user's private network, it
 is essential that the node only uses the WAN when it is absolutely necessary.
@@ -11,11 +11,12 @@ There are two cases in which the WAN port is used:
 After the VPN connection has been established, the node should be able to reach
 the mesh's DNS servers and use these for all other name resolution.
 
-If the device does not feature a WAN port, the LAN port is configured as WAN port.
-In case such a device has multiple LAN ports, all these can be used as WAN.
-Devices, which feature a "hybrid" port (labelled as WAN/LAN), this port is used as WAN.
-
-This behavior can be reversed using the ``single_as_lan`` site.conf option.
+If a device has only a single Ethernet port (or group of ports), it will be
+used as an uplink port even when it is not labelled as "WAN" by default. This
+behavior can be controlled using the ``interfaces.single.default_roles``
+site.conf option. It is also possible to alter the interface assignment after
+installation by modifying ``/etc/config/gluon`` and running
+``gluon-reconfigure``.
 
 Routing tables
 ~~~~~~~~~~~~~~

diff --git a/docs/features/multidomain.rst b/docs/features/multidomain.rst
@@ -130,9 +130,7 @@ site.conf only variables
   - authorized_keys
   - default_domain
   - poe_passthrough
-  - mesh_on_wan
-  - mesh_on_lan
-  - single_as_lan
+  - interfaces.*.default_roles
   - setup_mode.skip
   - autoupdater.branch
   - mesh_vpn.enabled

diff --git a/docs/features/private-wlan.rst b/docs/features/private-wlan.rst
@@ -1,8 +1,8 @@
 Private WLAN
 ============
 
-It is possible to set up a private WLAN that bridges the WAN port and is separated from the mesh network.
-Please note that you should not enable ``mesh_on_wan`` simultaneously.
+It is possible to set up a private WLAN that bridges the uplink port and is separated from the mesh network.
+Please note that you should not enable Wired Mesh on the uplink port at the same time.
 
 The private WLAN is encrypted using WPA2 by default. On devices with enough flash and a supported radio,
 WPA3 or WPA2/WPA3 mixed-mode can be used instead of WPA2. For this to work, the ``wireless-encryption-wpa3``

diff --git a/docs/features/wired-mesh.rst b/docs/features/wired-mesh.rst
@@ -50,8 +50,8 @@ 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).
 
-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``.
+It is also possible to enable Mesh-on-WAN and Mesh-on-LAN by default by adding
+the ``mesh`` role to the ``interfaces.*.default_roles`` options in site.conf.
 
 Commandline
 ===========

diff --git a/docs/index.rst b/docs/index.rst
@@ -39,7 +39,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
    dev/hardware
    dev/packages
    dev/upgrade
-   dev/wan
+   dev/uplink
    dev/mac_addresses
    dev/site_library
    dev/build

diff --git a/docs/user/site.rst b/docs/user/site.rst
@@ -399,17 +399,49 @@ mesh_vpn
       },
     }
 
-mesh_on_wan \: optional
-  Enables the mesh on the WAN port (``true`` or ``false``).
+interfaces \: optional
+  Default setup for Ethernet ports.
   ::
 
-    mesh_on_wan = true,
+    interfaces = {
+      lan = {
+        default_roles = { 'client', 'mesh' },
+      },
+      wan = {
+        default_roles = { 'uplink', 'mesh' },
+      },
+      single = {
+        default_roles = { 'uplink', 'mesh' },
+      },
+    },
 
-mesh_on_lan \: optional
-  Enables the mesh on the LAN port (``true`` or ``false``).
-  ::
+  For devices that have two distinct Ethernet ports or port groups (often
+  labelled WAN and LAN), the ``lan`` and ``wan`` sections are used. When there
+  is only one port (group), ``single`` is used instead.
+
+  Available interface roles:
+
+  - ``client``: Port allows regular clients to connect to the mesh
+  - ``uplink``: Port is used to establish Mesh VPN connections
+  - ``mesh``: Wired meshing to another Gluon or Gluon-compatible node
+
+  The ``client`` role requires exclusive control over an interface. When
+  the ``client`` role is assigned to an interface at the same time as other
+  roles (like ``'client', 'mesh'`` in the above example), the other roles take
+  precedence (enabling ``mesh``, but not ``client`` in the example).
+
+  Such a default configuration still fulfills a purpose (and is in fact the
+  recommended way to enable "Mesh-on-LAN" by default): The "LAN interface
+  meshing" checkbox in the advanced network settings will only add or remove
+  the ``mesh`` role, so the ``client`` role must already be in the configuration
+  to make the LAN port a regular client interface when the checkbox is disabled.
+
+  All interface settings are optional. If unset, the following defaults are
+  used:
 
-    mesh_on_lan = true,
+  - ``lan``: ``{ 'client' }``
+  - ``wan``: ``{ 'uplink' }``
+  - ``single``: Same as ``wan``
 
 poe_passthrough \: optional
   Enable PoE passthrough by default on hardware with such a feature.