From 210cacdf55d2a0017b7360dd059240033e2470e3 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Mon, 24 Jan 2022 00:18:02 +0100 Subject: [PATCH] docs: update for role-based interface configuration --- docs/dev/{wan.rst => uplink.rst} | 15 ++++++----- docs/features/multidomain.rst | 4 +-- docs/features/private-wlan.rst | 4 +-- docs/features/wired-mesh.rst | 4 +-- docs/index.rst | 2 +- docs/user/site.rst | 46 +++++++++++++++++++++++++++----- 6 files changed, 53 insertions(+), 22 deletions(-) rename docs/dev/{wan.rst => uplink.rst} (86%) diff --git a/docs/dev/wan.rst b/docs/dev/uplink.rst similarity index 86% rename from docs/dev/wan.rst rename to docs/dev/uplink.rst index ec9d942b..4d48168d 100644 --- a/docs/dev/wan.rst +++ b/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 index 80cae0de..43f343bb 100644 --- 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 index 3c26c8f8..41664b73 100644 --- 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 index 7f99c3c0..b48ec072 100644 --- 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 index d8e39465..72648a9a 100644 --- 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 index 79e7ca1e..5b2e0eeb 100644 --- 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. - mesh_on_lan = true, + 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: + + - ``lan``: ``{ 'client' }`` + - ``wan``: ``{ 'uplink' }`` + - ``single``: Same as ``wan`` poe_passthrough \: optional Enable PoE passthrough by default on hardware with such a feature.