docs/features/autoupdater.rst

@@ -7,11 +7,14 @@ Building Images
 ---------------
 
 By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
-during development), but it can be enabled by setting the variable GLUON_BRANCH when building
-to override the default branch set in the set in the site configuration.
+during development), but it can be enabled by setting the variable ``GLUON_AUTOUPDATER_ENABLED`` to ``1`` when building.
+It is also possible to override the default branch during build using the variable ``GLUON_AUTOUPDATER_BRANCH``.
+
+If a default branch is set neither in *site.conf* nor via ``GLUON_AUTOUPDATER_BRANCH``, the default branch is
+implementation-defined. Currently, the branch with the first name in alphabetical order is chosen.
 
 A manifest file for the updater can be generated with `make manifest`. A signing script (using
-``ecdsautils``) can by found in the `contrib` directory. When creating the manifest, the
+``ecdsautils``) can be found in the `contrib` directory. When creating the manifest, the
 ``PRIORITY`` value may be defined by setting ``GLUON_PRIORITY`` on the command line or in ``site.mk``.
 
 ``GLUON_PRIORITY`` defines the maximum number of days that may pass between releasing an update and installation
@@ -27,20 +30,42 @@ in ``site.mk``, care must be taken to pass the same ``GLUON_RELEASE`` to ``make
 as otherwise the generated manifest will be incomplete.
 
 
+Manifest format
+---------------
+
+The manifest starts with a short header, followed by the list of firmwares and signatures.
+The header contains the following information:
+
+.. code-block:: sh
+
+    BRANCH=stable
+    DATE=2020-10-07 00:00:00+02:00
+    PRIORITY=7
+
+- ``BRANCH`` is the autoupdater branch name that needs to match the nodes configuration.
+- ``DATE`` specifies when the time period for the update begins. Nodes will do their regular update during a random minute
+  between 4:00 and 4:59 am. Nodes might not always have a reliable NTP synchronization, which is why a fallback mechanism
+  exists, that checks for an update, and will execute if ``DATE`` is at least 24h in the past.
+- ``PRIORITY`` can be configured as ``GLUON_PRIORITY`` when generating the manifest or in ``site.mk``, and defines
+  the number of days over which the update should be stretched out after ``DATE``. Nodes will calculate a probability
+  based on the time left to determine when to update.
+
+
 Automated nightly builds
 ------------------------
 
 A fully automated nightly build could use the following commands:
 
-::
+.. code-block:: sh
 
     git pull
-    (cd site && git pull)
+    # git -C site pull
     make update
-    make clean
+    make clean GLUON_TARGET=ath79-generic
     NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
-    make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ar71xx-generic GLUON_BRANCH=experimental
-    make manifest GLUON_BRANCH=$GLUON_BRANCH GLUON_RELEASE=$GLUON_RELEASE
+    make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ath79-generic GLUON_RELEASE=$GLUON_RELEASE \
+        GLUON_AUTOUPDATER_BRANCH=experimental GLUON_AUTOUPDATER_ENABLED=1
+    make manifest GLUON_RELEASE=$GLUON_RELEASE GLUON_AUTOUPDATER_BRANCH=experimental
     contrib/sign.sh $SECRETKEY output/images/sysupgrade/experimental.manifest
 
     rm -rf /where/to/put/this/experimental
@@ -74,16 +99,16 @@ These commands can be used on a node:
 
 ::
 
-   # Update with some probability
-   autoupdater
+  # Update with some probability
+  autoupdater
 
 ::
 
-   # Force update check, even when the updater is disabled
-   autoupdater -f
+  # Force update check, even when the updater is disabled
+  autoupdater -f
 
 ::
 
-   # If fallback is true the updater will perform an update only if the timespan
-   # PRIORITY days (as defined in the manifest) and another 24h have passed
-   autoupdater --fallback
+  # If fallback is true the updater will perform an update only if the timespan
+  # PRIORITY days (as defined in the manifest) and another 24h have passed
+  autoupdater --fallback

docs/features/configmode.rst

@@ -14,10 +14,13 @@ Activating Config Mode
 ----------------------
 
 Config Mode is automatically entered at the first boot. You can re-enter
-Config Mode by pressing and holding the RESET/WPS button for about three
-seconds. The device should reboot (all LEDs will turn of briefly) and 
+Config Mode by pressing and holding the RESET/WPS/DECT button for about three
+seconds. The device should reboot (all LEDs will turn off briefly) and
 Config Mode will be available.
 
+If you have access to the console of the node, there is the
+``gluon-enter-setup-mode`` command, which reboots a node into Config Mode.
+
 
 Port Configuration
 ------------------
@@ -35,3 +38,17 @@ Accessing Config Mode
 Config Mode can be accessed at http://192.168.1.1. The node will offer DHCP
 to clients. Should this fail, you may assign an IP from 192.168.1.0/24 to
 your computer manually.
+
+.. image:: configmode.png
+
+Advanced Config Options
+-----------------------
+
+Depending on the installed packages, the advanced config mode allows to configure packages further.
+
+* :doc:`gluon-web-wifi-config enable <wlan-configuration>` radios used for wifi and mesh as well as outdoor mode
+* :doc:`../package/gluon-web-network` allows to configure the used roles (uplink, mesh, client) on each interface
+* :doc:`../package/gluon-web-admin` allows to enter SSH keys or set a password in the `Remote access` section
+* :doc:`../package/gluon-web-cellular` allows to configure SIM card / WWAN settings on supported cellular devices
+
+The advanced config does also allow to upload a sysupgrade file to update the firmware to a different version.

docs/features/dns-cache.rst

+.. _dns-caching:
+
+DNS caching
+===========
+
+User experience may be greatly improved when dns is accelerated. Also, it
+seems like a good idea to keep the number of packages being exchanged
+between node and gateway as small as possible. In order to do this, a
+DNS cache may be used on a node. The dnsmasq instance listening on port
+53 on the node will be reconfigured to answer requests, use a list of
+upstream servers and a specific cache size if the options listed below are
+added to site.conf. Upstream servers are the DNS servers which are normally
+used by the nodes to resolve hostnames (e.g. gateways/supernodes).
+
+There are the following settings:
+    servers
+    cacheentries
+
+To use the node's DNS server, both options should be set. The node will cache at
+most 'cacheentries' many DNS records in RAM. The 'servers' list will be used to
+resolve the received DNS queries if the request cannot be answered from
+cache. Gateways should announce the "next node" address via DHCP and RDNSS (if
+any). Note that not setting 'servers' here will lead to DNS not working: Once
+the gateways all announce the "next node" address for DNS, there is no way for
+nodes to automatically determine DNS servers. They have to be baked into the
+firmware.
+
+If these settings do not exist, the cache is not initialized and RAM usage will
+not increase.
+
+When next_node.name is set, an A record and an AAAA record for the
+next-node IP address are placed in the dnsmasq configuration. This means that
+the content of next_node.name may be resolved even without upstream connectivity.
+It is suggested to use the same name as the DNS server provides:
+e.g. nextnode.location.community.example.org (This way the name also works if a
+client uses static DNS Servers). Hint: If next_node.name does not contain a dot
+some browsers would open the searchpage instead.
+
+::
+
+  dns = {
+    cacheentries = 5000,
+    servers = { '2001:4860:4860::8888', '2001:4860:4860::8844' },
+  },
+
+  next_node = {
+    name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
+    ip6 = '2001:db8:8::1',
+    ip4 = '198.51.100.1',
+  }
+
+
+Each cache entry will occupy about 90 bytes of RAM.

docs/features/dns-forwarder.rst

-DNS forwarder
-=============
-
-A Gluon node can be configured to act as a DNS forwarder. Requests for the
-next-node hostname(s) can be answered locally, without querying the upstream
-resolver.
-
-**Note:** While this reduces answer time and allows to use the next-node
-hostname without upstream connectivity, this feature should not be used for
-next-node hostnames that are FQDN when the zone uses DNSSEC.
-
-One or more upstream resolvers can be configured in the *dns.servers* setting.
-When *next_node.name* is set, A and/or AAAA records for the next-node IP
-addresses are placed in the dnsmasq configuration.
-
-::
-
-  dns = {
-    servers = { '2001:db8::1', },
-  },
-
-  next_node = {
-    name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
-    ip6 = '2001:db8:8::1',
-    ip4 = '198.51.100.1',
-  }

docs/features/monitoring.rst

@@ -24,7 +24,7 @@ Information to be announced is currently split into three categories:
     interfaces. This data can be used to determine the network topology.
 
 All categories will have a ``node_id`` key. It should be used to
-relate data of different catagories.
+relate data of different categories.
 
 Accessing Node Information
 --------------------------
@@ -33,7 +33,7 @@ There are two packages responsible for distribution of the information. For
 one, information is distributed across the mesh using alfred_. Information
 between neighbouring nodes is exchanged using `gluon-respondd`.
 
-.. _alfred: http://www.open-mesh.org/projects/alfred
+.. _alfred: https://www.open-mesh.org/projects/alfred
 
 alfred (mesh bound)
 ~~~~~~~~~~~~~~~~~~~
@@ -47,7 +47,7 @@ installed. Please note that at least one alfred daemon is required to run as
 
 .. _alfred-json: https://github.com/ffnord/alfred-json
 
-The following datatypes are used:
+The following data types are used:
 
 * `nodeinfo`: 158
 * `statistics`: 159
@@ -97,14 +97,15 @@ In order to retrieve statistics data you could run:
 
 You can find more information about alfred in its README_.
 
-.. _README: https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README
+.. _README: https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README.rst
 
 gluon-respondd
 ~~~~~~~~~~~~~~
 
 `gluon-respondd` allows querying neighbouring nodes for their information.
 It is a daemon listening on the multicast address ``ff02::2:1001`` on
-UDP port 1001 on both the bare mesh interfaces and `br-client`. Unicast
+UDP port 1001 on the mesh interface and on the multicast address
+``ff05::2:1001`` on the `br-client` interface. Unicast
 requests are supported as well.
 
 The supported requests are:
@@ -117,13 +118,13 @@ The supported requests are:
 gluon-neighbour-info
 ~~~~~~~~~~~~~~~~~~~~
 
-The programm `gluon-neighbour-info` can be used to retrieve
+The program `gluon-neighbour-info` can be used to retrieve
 information from other nodes.
 
 ::
 
-  gluon-neighbour-info -i wlan0 \
-  -p 1001 -d ff02:0:0:0:0:0:2:1001 \
+  gluon-neighbour-info -i bat0 \
+  -p 1001 -d ff05:0:0:0:0:0:2:1001 \
   -r nodeinfo
 
 An optional timeout may be specified, e.g. `-t 5` (default: 3 seconds). See
@@ -134,5 +135,5 @@ Adding a data provider
 ----------------------
 
 To add a provider, you need to install a shared object into ``/lib/gluon/respondd``.
-For more information, refer to the `respondd README <https://github.com/freifunk-gluon/packages/blob/master/net/respondd/README.md>`_
+For more information, refer to the `respondd README <https://github.com/freifunk-gluon/packages/blob/main/net/respondd/README.md>`_
 and have a look the existing providers.

docs/features/multidomain.rst

@@ -21,18 +21,18 @@ Overview
 Multidomain support allows to build a single firmware with multiple,
 switchable domain configurations. The nomenclature is as follows:
 
--  ``site``: an aggregate over multiple domains
--  ``domain``: mesh network with connectivity parameters that prevent
-   accidental bridging with other domains
--  ``domain code``: unique domain identifier
--  ``domain name``: pretty name for a domain code
+- ``site``: an aggregate over multiple domains
+- ``domain``: mesh network with connectivity parameters that prevent
+  accidental bridging with other domains
+- ``domain code``: unique domain identifier
+- ``domain name``: pretty name for a domain code
 
 By default Gluon builds firmware with a single domain embedded into
 ``site.conf``. To use multiple domains, enable it in ``site.mk``:
 
 ::
 
-    GLUON_MULTIDOMAIN=1
+  GLUON_MULTIDOMAIN=1
 
 In the site repository, create the ``domains/`` directory, which will
 hold your domain configurations. Each domain configuration file is named
@@ -41,26 +41,26 @@ supported.
 
 ::
 
-    site/
-    |-- site.conf
-    |-- site.mk
-    |-- i18n/
-    |-- domains/
-      |-- alpha_centauri.conf
-      |-- beta_centauri.conf
-      |-- gamma_centauri.conf
+  site/
+  |-- site.conf
+  |-- site.mk
+  |-- i18n/
+  |-- domains/
+    |-- alpha_centauri.conf
+    |-- beta_centauri.conf
+    |-- gamma_centauri.conf
 
 The domain configuration ``alpha_centauri.conf`` could look like this.
 
 ::
 
-    {
-      domain_names = {
-        alpha_centauri = 'Alpha Centauri'
-      },
+  {
+    domain_names = {
+      alpha_centauri = 'Alpha Centauri'
+    },
 
-      -- more domain specific config follows below
-    }
+    -- more domain specific config follows below
+  }
 
 In this example “Alpha Centauri” is the user-visible ``domain_name`` for the
 domain_code ``alpha_centauri``. Also note that the domain code
@@ -88,18 +88,25 @@ domain of a router, if and only if one of the above conditions matches.
 Switching the domain
 --------------------
 
-**via commandline**:
+Via commandline
+^^^^^^^^^^^^^^^
 
 ::
 
-    uci set gluon.core.domain="newdomaincode"
-    gluon-reconfigure
-    reboot
+  gluon-switch-domain 'newdomaincode'
 
-**via config mode:**
+When the node is not in config mode, ``gluon-switch-domain`` will automatically
+reboot the node by default. This can be suppressed by passing ``--no-reboot``::
 
-To allow switching the domain via config mode, ``config-mode-domain-select``
-has to be added to GLUON_FEATURES in the site.mk.
+  gluon-switch-domain --no-reboot 'newdomaincode'
+
+Switching the domain without reboot is currently **experimental**.
+
+Via config mode
+^^^^^^^^^^^^^^^
+
+To allow switching the domain via config mode, add ``config-mode-domain-select``
+to the enabled features in the image-customization.lua file.
 
 |image0|
 
@@ -116,118 +123,112 @@ site or domain context.
 site.conf only variables
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
--  Used in as initial default values, when the firmware was just flashed
-   and/or the config mode is skipped, so they do not make sense in a
-   domain specific way:
-
-   -  authorized_keys
-   -  default_domain
-   -  poe_passthrough
-   -  mesh_on_wan
-   -  mesh_on_lan
-   -  single_as_lan
-   -  setup_mode.skip
-   -  autoupdater.branch
-   -  mesh_vpn.enabled
-   -  mesh_vpn.pubkey_privacy
-   -  mesh_vpn.bandwidth_limit
-   -  mesh_vpn.bandwidth_limit.enabled
-   -  mesh_vpn.bandwidth_limit.ingress
-   -  mesh_vpn.bandwidth_limit.egress
-
--  Variables that influence the appearance of the config mode,
-   domain-independent because they are relevant before a domain was selected.
-
-   -  config_mode.geo_location.show_altitude
-   -  config_mode.hostname.optional
-   -  config_mode.remote_login
-   -  config_mode.remote_login.show_password_form
-   -  config_mode.remote_login.min_password_length
-   -  hostname_prefix
-   -  mesh_vpn.fastd.configurable
-   -  roles.default
-   -  roles.list
-
--  Specific to a firmware build itself:
-
-   -  site_code
-   -  site_name
-   -  autoupdater.branches.*.name
-   -  autoupdater.branches.*.good_signatures
-   -  autoupdater.branches.*.pubkeys
-
--  We simply do not see any reason, why these variables could be helpful
-   in a domain specific way:
-
-   -  mesh_vpn.fastd.syslog_level
-   -  wifi*.ibss.supported_basic_rates
-   -  wifi*.mesh.supported_basic_rates
-   -  timezone
-   -  regdom
+- Used in as initial default values, when the firmware was just flashed
+  and/or the config mode is skipped, so they do not make sense in a
+  domain specific way:
+
+  - authorized_keys
+  - default_domain
+  - poe_passthrough
+  - interfaces.*.default_roles
+  - setup_mode.skip
+  - autoupdater.branch
+  - mesh_vpn.enabled
+  - mesh_vpn.pubkey_privacy
+  - mesh_vpn.bandwidth_limit
+  - mesh_vpn.bandwidth_limit.enabled
+  - mesh_vpn.bandwidth_limit.ingress
+  - mesh_vpn.bandwidth_limit.egress
+
+- Variables that influence the appearance of the config mode,
+  domain-independent because they are relevant before a domain was selected.
+
+  - config_mode.geo_location.show_altitude
+  - config_mode.hostname.optional
+  - config_mode.remote_login
+  - config_mode.remote_login.show_password_form
+  - config_mode.remote_login.min_password_length
+  - hostname_prefix
+  - mesh_vpn.fastd.configurable
+  - roles.default
+  - roles.list
+
+- Specific to a firmware build itself:
+
+  - site_code
+  - site_name
+  - autoupdater.branches.*.name
+  - autoupdater.branches.*.good_signatures
+  - autoupdater.branches.*.pubkeys
+
+- We simply do not see any reason, why these variables could be helpful
+  in a domain specific way:
+
+  - mesh_vpn.fastd.syslog_level
+  - timezone
+  - regdom
 
 domain.conf only variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
--  Obviously:
+- Obviously:
 
-   -  domain_names
+  - domain_names
 
-      -  a table of domain codes to domain names
-         ``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
+    - a table of domain codes to domain names
+      ``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
 
-   -  hide_domain
+  - hide_domain
 
-      -  prevents a domain name(s) from appearing in config mode, either
-         boolean or array of domain codes
+    - prevents a domain name(s) from appearing in config mode, either
+      boolean or array of domain codes
 
-         -  ``true``, ``false``
-         -  ``{ 'foo', 'bar' }``
+      - ``true``, ``false``
+      - ``{ 'foo', 'bar' }``
 
--  Because each domain is considered as an own layer 2 network, these
-   values should be different in each domain:
+- Because each domain is considered a separate layer 2 network, these
+  values should be different in each domain:
 
-   -  next_node.ip4
-   -  next_node.ip6
-   -  next_node.name
-   -  prefix6
-   -  prefix4
-   -  extra_prefixes6
+  - next_node.ip4
+  - next_node.ip6
+  - next_node.name
+  - prefix6
+  - prefix4
+  - extra_prefixes6
 
--  To prevent accidential bridging of different domains, all meshing
-   technologies should be seperated:
+- To prevent accidental bridging of different domains, all meshing
+  technologies should be separated:
 
-   -  domain_seed (wired mesh)
+  - domain_seed (wired mesh)
 
-      -  must be a random value used to derive the vxlan id for wired meshing
+    - must be a random value used to derive the vxlan id for wired meshing
 
-   -  wifi*.ibss.ssid
-   -  wifi*.ibss.bssid
-   -  wifi*.mesh.id
-   -  mesh_vpn.fastd.groups.*.peers.remotes
-   -  mesh_vpn.fastd.groups.*.peers.key
-   -  mesh_vpn.tunneldigger.brokers
+  - wifi*.mesh.id
+  - mesh_vpn.fastd.groups.*.peers.remotes
+  - mesh_vpn.fastd.groups.*.peers.key
 
--  Clients consider WiFi networks sharing the same ESSID as if they were
-   the same L2 network and try to reconfirm and reuse previous
-   addressing. If multiple neighbouring domains shared the same ESSID,
-   the roaming experience of clients would degrade.
+- Clients consider WiFi networks sharing the same ESSID as if they were
+  the same L2 network and try to reconfirm and reuse previous
+  addressing. If multiple neighbouring domains shared the same ESSID,
+  the roaming experience of clients would degrade.
 
-   -  wifi*.ap.ssid
+  - wifi*.ap.ssid
 
 - Some values should be only set in legacy domains and not in new domains.
-   -  mesh.vxlan
 
-       -  By default, this value is `true`. It should be only set to `false`
-          for one legacy domain, since vxlan prevents accidental wired
-          merges of domains. For old domains this value is still available
-          to keep compatibility between all nodes in one domain.
+  - mesh.vxlan
+
+    - By default, this value is `true`. It should be only set to `false`
+      for one legacy domain, since vxlan prevents accidental wired
+      merges of domains. For old domains this value is still available
+      to keep compatibility between all nodes in one domain.
 
-   -  next_node.mac
+  - next_node.mac
 
-       -  For new domains, the default value should be used, since there is
-          no need for a special mac (or domain specific mac). For old domains
-          this value is still available to keep compatibility between all
-          nodes in one domain.
+    - For new domains, the default value should be used, since there is
+      no need for a special mac (or domain specific mac). For old domains
+      this value is still available to keep compatibility between all
+      nodes in one domain.
 
 Example config
 --------------

docs/features/private-wlan.rst

 Private WLAN
 ============
 
-It is possible to set up a private WLAN that bridges the WAN port and is seperated 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``
+feature has to be enabled as a feature.
+
+It is recommended to enable IEEE 802.11w management frame protection for WPA2/WPA3 networks, however this
+can lead to connectivity problems for older clients. In this case, management frame protection can be
+made optional or completely disabled in the advanced settings tab.
 
 The private WLAN can be enabled through the config mode if the package ``gluon-web-private-wifi`` is installed.
 You may also enable a private WLAN using the command line::
@@ -19,7 +27,7 @@ You may also enable a private WLAN using the command line::
   uci set wireless.wan_radio$RID.ssid="$SSID"
   uci set wireless.wan_radio$RID.key="$KEY"
   uci set wireless.wan_radio$RID.disabled=0
-  uci set wireless.wan_radio$RID.macaddr="$($(echo "lua -e print(require('gluon.util').generate_mac(3+4*$RID))"))"
+  uci set wireless.wan_radio$RID.macaddr=$(lua -e "print(require('gluon.util').generate_mac(3+4*$RID))")
   uci commit
   wifi
 

docs/features/roles.rst

@@ -2,8 +2,8 @@ Roles
 =====
 
 It is possible to define a set of roles you want to distinguish at backend side. One node can own one
-role which it will announce via alfred inside the mesh. This will make it easier to differentiate
-nodes when parsing alfred data. E.g to count only **normal** nodes and not the gateways
+role which it will announce via respondd/announced inside the mesh. This will make it easier to differentiate
+nodes when parsing respondd data. E.g to count only **normal** nodes and not the gateways
 or servers (nodemap). A lot of things are possible.
 
 For this the section ``roles`` in ``site.conf`` is needed::
@@ -28,7 +28,7 @@ If you want node owners to change the defined roles via config-mode you can add
 
 The role is saved in ``gluon-node-info.system.role``. To change the role using command line do::
 
-  uci set gluon-node-info.system.role="$ROLE"
+  uci set gluon-node-info.@system[0].role="$ROLE"
   uci commit
 
 Please replace ``$ROLE`` by the role you want the node to own.

docs/features/status-page.rst

+Status-Page
+===========
+
+When the feature ``gluon-status-page`` is enabled, Gluon nodes run a HTTP server with status information on all IP addresses of ``br-client``.
+This makes it possible to check information of the node in realtime.
+
+If the mesh protocol ``gluon-mesh-batman-adv`` is installed too, the package ``gluon-status-page-mesh-batman-adv`` is added too according to the :ref:`user-site-feature-flags`
+
+.. _status-page-example-picture:
+
+Example Picture
+---------------
+
+The left side of the status page contains Overview information.
+In the middle, current monitoring information abut the system, number of clients, radios, amount of traffic and connected mesh-vpn if any are shown.
+The right side of the Status-Page contains information about Neighbours to this node through :doc:`wired-mesh` as well as wireless mesh.
+
+.. image:: status-page.png
+
+Mesh Graphs
+-----------
+
+When wireless mesh is enabled, the mesh interfaces show realtime Graphs about the received signal strength (RSSI) in dBm.
+
+Neighbours
+----------
+
+The list of neighbours at first shows the mac-address of the neighbour it sees.
+The status-page sends a second request to ``http://[ipv6]/cgi-bin/dyn/neighbours-nodeinfo?mesh-vpn`` which triggers the lookup of neighbour information on the node itself.
+Through this, the actual nodenames of the neighbours are shown on the status-page as can be seen in the :ref:`status-page-example-picture`.

docs/features/tls.rst

+TLS support
+===========
+
+The generic TLS implementation which is currently used by OpenWRT can be installed or added as dependency through the package ``gluon-tls``.
+This removes the need for community packages to depend on a specific TLS implementation (like mbedtls, OpenSSL or WolfSSL).
+
+This package is an alias for the current TLS implementation used.
+To allow for easy usage of communicating through HTTPS from the node, typical Certificate Authorities (CAs) are included through the package ``ca-bundle`` .
+
+* Starting with OpenWRT 23.05, mbedtls is the default TLS layer - this is reflected in Gluon :ref:`v2023.2 <releases-v2023.2-minor-changes>`. HTTPS is used by default to communicate with OpenWRT opkg servers.

docs/features/vpn.rst

-Mesh-VPN
+.. _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.
+
+Protocols overview
+^^^^^^^^^^^^^^^^^^
+
+For a comprehensive comparison and evaluation of the supported and formerly supported VPN methods that best suit your needs, refer to the following table (Be sure to scroll to the right):
+
++---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
+| Gluon VPN method                      | IPv4 | IPv6     | Authentication | Encryption                 | Kernelspace forwarding | MTU overhead     | Multithreading | Single interface for all |
+|                                       |      |          |                | (no→faster,insecure [1]_)  | (yes→faster)           | (bytes @v4) [7]_ |                | peers                    |
++=======================================+======+==========+================+============================+========================+==================+================+==========================+
+| fastd, encrypted                      | yes  | yes      | optional [2]_  | yes                        | no                     | low (98)         | no             | optional                 |
++---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
+| fastd, null                           | yes  | yes      | optional [2]_, | no                         | no                     | low (98)         | no             | optional                 |
+|                                       |      |          | partial [3]_   |                            |                        |                  |                |                          |
++---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
+| fastd, ``null@l2tp``, with offloading | yes  | yes      | optional [2]_, | no                         | yes                    | low (82)         |                | optional                 |
+|                                       |      |          | partial [3]_   |                            |                        |                  |                |                          |
++---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
+| fastd, ``null@l2tp``, no offloading   | yes  | yes      | optional [2]_, | no                         | no                     | low (82)         | no             | optional                 |
+|                                       |      |          | partial [3]_   |                            |                        |                  |                |                          |
++---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
+| Tunneldigger (L2TP - deprecated) [6]_ | yes  | no [4]_  | no             | no                         | yes                    | low (82)         |                | no                       |
++---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
+| WireGuard + VXLAN                     | yes  | yes      | yes            | yes                        | yes                    | high (162)       | yes [5]_       | yes                      |
++---------------------------------------+------+----------+----------------+----------------------------+------------------------+------------------+----------------+--------------------------+
+
+.. [1] No encryption allows internet providers to read and alter mesh traffic.
+.. [2] The Gateway can ignore authentication for the initial connection request, via ``"on verify 'true'"``. However, a node→gateway handshake authentication with valid fastd keys in the site.conf is still required.
+.. [3] Initial connection request can be authenticated, however, payload data is not authenticated afterward.
+
+
+.. [4] https://github.com/wlanslovenija/tunneldigger/issues/75
+.. [5] https://www.wireguard.com/performance/
+.. [6] https://github.com/ffac/community-packages/tree/master/ff-mesh-vpn-tunneldigger
+.. [7] :ref:`mtu`
+
+Additional, notable compatibility features
+""""""""""""""""""""""""""""""""""""""""""
+
+* fastd: multiple encrypted and unencrypted methods can be handled by one daemon
+* fastd: a ``null@l2tp`` peer with offloading is fully compatible with a peer with ``null@l2tp`` without offloading
+* fastd+WireGuard: a single secret can be used for both fastd and WireGuard via :ref:`gluon-mesh-vpn-key-translate <gluon-mesh-vpn-key-translate>`, so no need for a node owner switching to (or from) Wireguard from (or to) fastd to submit a new key
+
+
+Core Protocol handlers
+^^^^^^^^^^^^^^^^^^^^^^
 
-- fastd
-- L2TPv3 (via tunneldigger)
+There are currently two supported protocol handlers which
+can be selected as a feature:
 
-fastd is a lightweight userspace tunneling daemon, that
+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.
+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-wireguard
+""""""""""""""""""
 
-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.
+WireGuard is an encrypted in-kernel tunneling protocol that
+provides encrypted transmission and at the same time offers
+high throughput.
 
 fastd
------
+^^^^^
 
-Configurable Cipher
-^^^^^^^^^^^^^^^^^^^
+.. _VPN fastd methods:
 
+Methods
+"""""""
 
-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.
+fastd offers various different connection "methods" with different
+security properties that can be configured in the site configuration.
 
-**Site configuration:**
+The following methods are currently recommended:
 
-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)
+- ``salsa2012+umac``: Encrypted + authenticated
+- ``null+salsa2012+umac``: Unencrypted, authenticated
+- ``null@l2tp``: Unencrypted, unauthenticated
 
-**Gateway configuration:**
+Multiple methods can be listed in ``site.conf``. The first listed method
+supported by both the node and its peer will be used.
 
-1) Prepend the ``null`` cipher in fastd's method list
+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``.
 
 
-**Config Mode:**
-The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport.
+.. _vpn-gateway-configuration:
 
-.. image:: fastd_mode.gif
+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 supernodes that
+don't use offloading as long as both use the ``null@l2tp`` method.
+
+
+.. _vpn-gateway-configuration-offloading:
+
+Offloading on Gateways / Supernodes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Unix socket:**
-To confirm whether the correct cipher is being used, fastds unix
-socket can be interrogated, after installing for example `socat`.
+To enable L2TP offloading on the supernodes, 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>`_.
 
-::
+However, the important changes to the fastd config on your Supernode are:
+
+    - | Set ``mode multitap;``
+      | Every peer gets their own interface.
+
+    - | Replace ``interface "foo":`` with ``interface "peer-%k";``
+      | ``%k`` is substituted for a portion of the peers public key.
+
+    - | Set ``offload l2tp yes;``
+      | This tells fastd to use the l2tp kernel module.
+
+    - | Set ``persist interface no;``
+      | This tells fastd to only keep interfaces around while the connection is active.
+
+Note that in ``multitap`` mode, which is required when using L2TP offloading,
+fastd will create one interface per peer on the supernode's. This allows
+offloading the L2TP forwarding into the kernel space. But this also means added
+complexity with regards to handling those interfaces.
+
+There are two main options on how you can handle this:
+
+    -  create ``on up`` and ``on down`` hooks
+
+        - to handle interface setup and destruction
+        - preferably using the async keyword, so hooks are not blocking fastd
+
+    - use a daemon like systemd-networkd
+
+Examples for both options can be found in the
+`Wiki <https://github.com/freifunk-gluon/gluon/wiki/fastd-l2tp-offloading-on-supernodes>`_.
+
+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)
+
+Config Mode
+~~~~~~~~~~~
+
+The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport.
+
+.. image:: fastd_mode.gif
 
-       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``.
+
+WireGuard
+^^^^^^^^^
+
+In order to support WireGuard in Gluon, a few technologies are glued together.
+
+**VXLAN:** As Gluon typically relies on batman-adv, the Mesh VPN has to provide
+OSI Layer 2 transport. But WireGuard is an OSI Layer 3 tunneling protocol, so
+additional technology is necessary here. For this, we use VXLAN. In short, VXLAN
+is a well-known technology to encapsulate ethernet packages into IP packages.
+You can think of it as kind of similar to VLAN, but on a different layer. Here,
+we use VXLAN to transport batman-adv traffic over WireGuard.
+
+**wgpeerselector**: To connect all gluon nodes to each other, it is common to
+create a topology where each gluon node is connected to one of the available
+gateways via Mesh VPN respectively. To achieve this, the gluon node should be
+able to select a random gateway to connect to. But such "random selection of a
+peer" is not implemented in WireGuard by default. WireGuard only knows static
+peers. Therefore the *wgpeerselector* has been developed. It randomly selects a
+gateway, tries to establish a connection, and if it fails, tries to connect
+to the next gateway. This approach has several advantages, such as load
+balancing VPN connection attempts and avoiding problems with offline gateways.
+More information about the wgpeerselector and its algorithm can be found
+`here <https://github.com/freifunk-gluon/packages/blob/main/net/wgpeerselector/README.md>`__.
+
+On the gluon node both VXLAN and the wgpeerselector are well integrated and no
+explicit configuration of those tools is necessary, once the general WireGuard
+support has been configured.
+
+Attention must by paid to time synchronization. As WireGuard
+performs checks on timestamps in order to avoid replay attacks, time must
+be synchronized before the Mesh VPN connection is established. This means that
+the NTP servers specified in your site.conf must be publicly available (and not
+only through the mesh). Be aware that if you fail this, you may not directly see
+negative effects. Only when a previously connected node reboots the effect
+comes into play, as the gateway still knows about the old timestamp of the gluon
+node.
+
+.. _gluon-mesh-vpn-key-translate:
+
+gluon-mesh-vpn-key-translate
+""""""""""""""""""""""""""""
+
+Many communities already possess a collection of active fastd-keys when they
+plan migrating their community to WireGuard.
+These public keys known on the server-side can be derived into their WireGuard
+equivalent using `gluon-mesh-vpn-key-translate <https://github.com/AiyionPrime/gluon-mesh-vpn-key-translate>`__.
+The routers do the necessary reencoding of the private key seamlessly
+when updating firmware from fastd to the WireGuard variant.
+
+Gateway / Supernode Configuration
+"""""""""""""""""""""""""""""""""
+
+On the gateway side, a software called *wireguard-vxlan-glue* is necessary. It
+is a small daemon that dynamically adds and removes forwarding rules for VXLAN
+interfaces, so traffic is sent correctly into the WireGuard interface. Thereby
+the forwarding rules are only installed if a client is connected, so
+unnecessary traffic in the kernel is avoided. The source can be found
+`here <https://github.com/freifunkh/wireguard-vxlan-glue/>`__.

docs/features/wired-mesh.rst

@@ -20,7 +20,7 @@ Wired mesh encapsulation
 
 Since version 2018.1, Gluon supports encapsulating wired mesh traffic in
 `VXLAN <https://en.wikipedia.org/wiki/Virtual_Extensible_LAN>`_, a new standard with
-usecases similar to VLANs, but a much greater ID space of 24bit; in addition, VXLAN
+use cases 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:
@@ -50,38 +50,84 @@ 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 your
+:ref:`site.conf<user-site-interfaces>`.
+
+
+.. _wired-mesh-commandline:
 
 Commandline
 ===========
 
+Starting with release 2022.1, the wired network configuration is rebuilt from ``/etc/config/gluon``
+upon each ``gluon-reconfigure``.
+Therefore the network configuration is overwritten at least with every firmware upgrade.
+
+Every interface has a list of roles assigned to it which can be ``client``, ``mesh`` or ``uplink``.
+
+When the client role is assigned to an interface in combination with other roles
+(like 'client', 'mesh' in the Mesh-on-LAN example below), the other roles take
+precedence, enabling mesh but not client in the previous example.
+
+The setup/config-mode interface is every interface with the role ``client`` which makes removing
+it from interfaces not only unnecessary, but generally unrecommended.
+
+In order to make persistent changes to the router's configuration it's necessary to:
+
+* change the sections in ``/etc/config/gluon`` e.g. using uci (see examples below)
+* call ``gluon-reconfigure`` to re-generate ``/etc/config/network``
+* apply the networking changes, either through executing ``service network restart`` or by performing a ``reboot``
+
 Enable Mesh-on-WAN::
 
-  uci set network.mesh_wan.disabled=0
-  uci commit network
+  uci add_list gluon.iface_wan.role='mesh'
+  uci commit gluon
 
 Disable Mesh-on-WAN::
 
-  uci set network.mesh_wan.disabled=1
-  uci commit network
+  uci del_list gluon.iface_wan.role='mesh'
+  uci commit gluon
 
 Enable Mesh-on-LAN::
 
-  uci set network.mesh_lan.disabled=0
-  for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
-    uci del_list network.client.ifname=$ifname
-  done
-  uci commit network
+  uci add_list gluon.iface_lan.role='mesh'
+  uci commit gluon
 
 Disable Mesh-on-LAN::
 
-  uci set network.mesh_lan.disabled=1
-  for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
-    uci add_list network.client.ifname=$ifname
-  done
-  uci commit network
+  uci del_list gluon.iface_lan.role='mesh'
+  uci commit gluon
+
+For devices with a single interface, instead of `iface_lan` and `iface_wan` configuration is
+done with `iface_single`.
+
+Enable Mesh-on-Single::
+
+  uci add_list gluon.iface_single.role='mesh'
+  uci commit gluon
+
+Disable Mesh-on-Single::
+
+  uci del_list gluon.iface_single.role='mesh'
+  uci commit gluon
+
+Furthermore it is possible to make use of 802.1Q VLAN.
+The following statements would create a VLAN with id 8 on ``eth0`` and join the mesh network with it::
+
+  uci set gluon.iface_lan_vlan8=interface
+  uci set gluon.iface_lan_vlan8.name='eth0.8'
+  uci add_list gluon.iface_lan_vlan8.role='mesh'
+  uci commit gluon
+
+Other VLAN-interfaces could be configured on the same parent interface in order to have
+all three roles available on ``eth0`` without having them interfere with each other.
+This feature comes in especially handy for the persistent configuration of virtual machines
+as offloader for bigger installations.
+
+A ``reboot`` is not sufficient to apply an altered configuration; calling ``gluon-reconfigure`` before is
+mandatory in order for changes to take effect.
 
-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
+Please note that this configuration has changed in Gluon 2022.1. Using
+the old commands on 2022.1 and later will break the corresponding options
 in the *Advanced settings*.