docs/dev/web/i18n.rst

+Internationalization support
+============================
+
+General guidelines
+------------------
+
+* All config mode packages must be fully translatable, with complete English and German texts.
+* All new expert mode packages must be fully translatable. English texts are required.
+* German translations are recommended. Other supported languages, especially French, are
+  nice-to-have, but not required. If you don't know a language well, rather leave the translation
+  blank, so it is obvious that there is no proper translation yet.
+* Existing expert mode packages should be made translatable as soon as possible.
+* The "message IDs" (which are the arguments to the *translate* function) should be the
+  English texts.
+
+i18n support in Gluon
+---------------------
+
+Internationalization support is available in all components (models, view and
+controllers) of *gluon-web*-based packages. Strings are translated using the *translate*,
+*_translate* and *translatef* functions (*translate* for static strings, *translatef*
+for printf-like formatted string; *_translate* works the same as *translate*, but
+will return *nil* instead of the original string when no translation is available).
+
+In views, the special tags ``<%:...%>`` can be used to translate the contained string.
+
+Example from the *gluon-config-mode-geo-location* package:
+
+.. code-block:: lua
+
+  local share_location = s:option(Flag, "location", translate("Show node on the map"))
+
+Note that translations are *namespaced*: each package will only use its own
+translation strings by default. For this purpose, the package name must by
+specified in a package's controller. It is possible to access a different
+translation package using the *i18n* function from models and view, which is
+necessary when strings from the site configuration are used, or packages do not
+have their own controller (which is the case for config mode wizard components).
+
+.. code-block:: lua
+
+  local site_i18n = i18n 'gluon-site'
+  local msg = site_i18n._translate('gluon-config-mode:welcome')
+
+Adding translation templates to Gluon packages
+----------------------------------------------
+
+The i18n support is based on the standard gettext system. For each translatable package,
+a translation template with extension ``.pot`` can be created using the *i18n-scan.pl*
+script in the ``contrib`` directory:
+
+.. code-block:: sh
+
+  cd package/gluon-web-mesh-vpn-fastd
+  mkdir i18n
+  cd i18n
+  ../../../contrib/i18n-scan.pl ../files ../luasrc > gluon-web-mesh-vpn-fastd.pot
+
+The same command can be run again to update the template.
+
+In addition, the Makefile must be adjusted. Instead of OpenWrt's default *package.mk*,
+the Gluon version (``../gluon.mk`` for core packages) must be used. The i18n files must be installed
+and PKG_CONFIG_DEPENDS must be added::
+
+  ...
+  include ../gluon.mk
+
+  PKG_CONFIG_DEPENDS += $(GLUON_I18N_CONFIG)
+  ...
+  define Build/Compile
+    $(call GluonBuildI18N,gluon-web-mesh-vpn-fastd,i18n)
+  endef
+
+  define Package/gluon-web-mesh-vpn-fastd/install
+    ...
+    $(call GluonInstallI18N,gluon-web-mesh-vpn-fastd,$(1))
+  endef
+  ...
+
+
+Adding translations
+-------------------
+
+A new translation file for a template can be added using the *msginit* command:
+
+.. code-block:: sh
+
+  cd package/gluon-web-mesh-vpn-fastd/i18n
+  msginit -l de
+
+This will create the file *de.po* in which the translations can be added.
+
+The translation file can be updated to a new template version using the *msgmerge* command:
+
+.. code-block:: sh
+
+  msgmerge -U de.po gluon-web-mesh-vpn-fastd.pot
+
+After the merge, the translation file should be checked for "fuzzy matched" entries where
+the original English texts have changed. All entries from the translation file should be
+translated in the *.po* file (or removed from it, so the original English texts are displayed
+instead).
+
+Adding support for new languages
+--------------------------------
+
+A list of all languages supported by *gluon-web* can be found in ``package/gluon.mk``.
+New languages just need to be added to *GLUON_SUPPORTED_LANGS*, and a human-readable
+language name must be defined.

docs/dev/web/model.rst

+Models
+======
+
+Models are defined in the ``model`` subdirectory of a gluon-web application
+(``/lib/gluon/config-mode/model`` for the config mode; the status
+page does not use any models). Model support is not part of the gluon-web core
+anymore, but is provided by the *gluon-web-model* package.
+
+Each model defines one or more forms to display on a page, and how the submitted
+form data is handled.
+
+Let's start with an example:
+
+.. code-block:: lua
+
+  local f = Form(translate('Hostname'))
+
+  local s = f:section(Section)
+
+  local o = s:option(Value, 'hostname', translate('Hostname'))
+  o.default = uci:get_first('system', 'system', 'hostname')
+  function o:write(data)
+    uci:set('system', uci:get_first('system', 'system'), 'hostname', data)
+    uci:commit('system')
+  end
+
+  return f
+
+The top-level element of a model is always a *Form*, but it is also possible for
+a model to return multiple forms, which are displayed one below the other.
+
+A *Form* has one or more *Sections*, and each *Section* has different types
+of options.
+
+All of these elements have an *id*, which is used to identify them in the HTML
+form and handlers. If no ID is given, numerical IDs will be assigned automatically,
+but using explicitly named elements is often advisable (and it is required if a
+form does not always include the same elements, i.e., some forms, sections or
+options are added conditionally). IDs are hierarchical, so in the above example,
+the *Value* would get the ID ``1.1.hostname`` (value *hostname* in first section
+of first form).
+
+Classes and methods
+-------------------
+
+  - *Form* (*title*, *description*, *id*)
+
+    - *Form:section* (*type*, *title*, *description*, *id*)
+
+      Creates a new section of the given type (usually *Section*).
+
+    - *Form:write* ()
+
+      Is called after the form has been submitted (but only if the data is valid). It
+      is called last (after all options' *write* methods) and is usually used
+      to commit changed UCI packages.
+
+      The default implementation of *write* doesn't do anything, but it can be
+      overridden.
+
+  - *Section* (usually instantiated through *Form:section*)
+
+    - *Section:option* (*type*, *id*, *title*, *description*)
+
+      Creates a new option of the given type. Option types:
+
+        - *Value*: simple text entry
+        - *TextValue*: multiline text field
+        - *ListValue*: radio buttons or dropdown selection
+        - *DynamicList*: variable number of text entry fields
+        - *Flag*: checkbox
+
+Most option types share the same properties and methods:
+
+  - *default*: default value
+  - *optional*: value may be empty
+  - *datatype*: one of the types described in :ref:`web-model-datatypes`
+
+    By default (when *datatype* is *nil*), all values are accepted.
+
+  - *state*: has one of the values *FORM_NODATA*, *FORM_VALID* and *FORM_INVALID*
+    when read in a form handler
+
+    An option that has not been submitted because of its dependencies will have
+    the state *FORM_NODATA*, *FORM_INVALID* if the submitted value is not valid
+    according to the set *datatype*, and *FORM_VALID* otherwise.
+
+  - *data*: can be read in form handlers to get the submitted value
+
+  - *depends* (*self*, *option*, *value*): adds a dependency on another option
+
+    The option will only be shown when the passed option has the given value. This
+    is mainly useful when the other value is a *Flag* or *ListValue*.
+
+  - *depends* (*self*, *deps*): adds a dependency on multiple other options
+
+    *deps* must be a table with options as keys and values as values. The option
+    will only be shown when all passed options have the corresponding values.
+
+    Multiple alternative dependencies can be added by calling *depends* repeatedly.
+
+  - *value* (*self*, *value*, *text*): adds a choice to a *ListValue*
+
+  - *write* (*self*, *data*): is called with the submitted value when all form data is valid.
+
+    Does not do anything by default, but can be overridden.
+
+The *default* value, the *value* argument to *depends* and the output *data* always have
+the same type, which is usually a string (or *nil* for optional values). Exceptions
+are:
+
+  - *Flag* uses boolean values
+  - *DynamicList* uses a table of strings
+
+Despite its name, the *datatype* setting does not affect the returned value type,
+but only defines a validator the check the submitted value with.
+
+For a more complete example that actually makes use of most of these features,
+have a look at the model of the *gluon-web-network* package.
+
+.. _web-model-datatypes:
+
+Data types
+----------
+
+  - *integer*: an integral number
+  - *uinteger*: an integral number greater than or equal to zero
+  - *float*: a number
+  - *ufloat*: a number greater than or equal to zero
+  - *ipaddr*: an IPv4 or IPv6 address
+  - *ip4addr*: an IPv4 address
+  - *ip6addr*: an IPv6 address
+  - *wpakey*: a string usable as a WPA key (either between 8 and 63 characters, or 64 hex digits)
+  - *range* (*min*, *max*): a number in the given range (inclusive)
+  - *min* (*min*): a number greater than or equal to the given minimum
+  - *max* (*max*): a number less than or equal to the given maximum
+  - *irange* (*min*, *max*): an integral number in the given range (inclusive)
+  - *imin* (*min*): an integral number greater than or equal to the given minimum
+  - *imax* (*max*): an integral number less than or equal to the given maximum
+  - *minlength* (*min*): a string with the given minimum length
+  - *maxlength* (*max*): a string with the given maximum length
+
+Differences from LuCI
+---------------------
+
+  - LuCI's *SimpleForm* and *SimpleSection* are called *Form* and *Section*, respectively
+  - Is it not possible to add options to a *Form* directly, a *Section* must always
+    be created explicitly
+  - Many of LuCI's CBI classes have been removed, most importantly the *Map*
+  - The *rmempty* option attribute does not exist, use *optional* instead
+  - Only the described data types are supported
+  - Form handlers work completely differently (in particular, a *Form*'s *handle*
+    method should usually not be overridden in *gluon-web*)

docs/dev/web/view.rst

+Views
+=====
+
+The template parser reads views from the ``view`` subdirectory of a
+gluon-web application (``/lib/gluon/config-mode/view`` for the config mode,
+``lib/gluon/status-page/view`` for the status page).
+Writing own views should usually be avoided in favour of using :doc:`model`
+with their predefined views.
+
+Views are partial HTML pages, with additional template tags that allow
+to embed Lua code and translation strings. The following tags are defined:
+
+  - ``<%`` ... ``%>`` evaluates the enclosed Lua expression.
+  - ``<%|`` ... ``%>`` evaluates the enclosed Lua expression and prints its value.
+  - ``<%=`` ... ``%>`` evaluates the enclosed Lua expression and prints its value
+    *without escaping HTML entities*. This is useful when the value contains HTML code.
+  - ``<%+`` ... ``%>`` includes another template.
+  - ``<%:`` ... ``%>`` translates the enclosed string using the loaded i18n catalog.
+  - ``<%_`` ... ``%>`` translates the enclosed string *without escaping HTML entities*
+    in the translation. This only makes sense when the i18n catalog contains HTML code.
+  - ``<%#`` ... ``%>`` is a comment.
+
+All of these also come in the whitespace-stripping variants ``<%-`` and ``-%>`` that
+remove all whitespace before or after the tag.
+
+Complex combinations of HTML and Lua code are possible, for example:
+
+.. code-block:: text
+
+  <div>
+    <% if foo then %>
+      Content
+    <% end %>
+  </div>
+
+
+Variables and functions
+-----------------------
+
+Many call sites define additional variables (for example, model templates can
+access the model as *self* and a unique element ID as *id*), but the following
+variables and functions should always be available for the embedded Lua code:
+
+  - *renderer*: :ref:`web-controller-template-renderer`
+  - *http*: :ref:`web-controller-http`
+  - *request*: Table containing the path components of the current page
+  - *url* (*path*): returns the URL for the given path, which is passed as a table of path components.
+  - *attr* (*key*, *value*): Returns a string of the form ``key="value"``
+    (with a leading space character before the key).
+
+    *value* is converted to a string (tables are serialized as JSON) and HTML entities
+    are escaped. Returns an empty string when *value* is *nil* or *false*.
+  - *include* (*template*): Includes another template.
+  - *node* (*path*, ...): Returns the controller node for the given page (passed as
+    one argument per path component).
+
+    Use ``node(unpack(request))`` to get the node for the current page.
+  - *pcdata* (*str*): Escapes HTML entities in the passed string.
+  - *urlencode* (*str*): Escapes the passed string for use in an URL.
+  - *translate*, *_translate*, *translatef* and *i18n*: see :doc:`i18n`

docs/features/authorized-keys.rst

@@ -8,7 +8,7 @@ If you select this package, add a list of authorized keys to ``site.conf`` like
 
   {
     authorized_keys = { 'ssh-rsa AAA.... user1@host',
-                        'ssh-rsa AAA.... user2@host },
+                        'ssh-rsa AAA.... user2@host' },
     hostname_prefix = ...
     ...
 

docs/features/autoupdater.rst

@@ -7,29 +7,65 @@ 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, ``GLUON_PRIORITY`` can
-be set on the command line, or it can be taken from the ``site.mk``.
+``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
+of the images. The update probability will start at 0 after the release time declared in the manifest file
+by the variable DATE and then slowly rise up to 1 when ``GLUON_PRIORITY`` days have passed. The autoupdater checks
+for updates hourly (at a random minute of the hour), but usually only updates during its run between
+4am and 5am, except when the whole ``GLUON_PRIORITY`` days and another 24 hours have passed.
+
+``GLUON_PRIORITY`` may be an integer or a decimal fraction.
+
+If ``GLUON_RELEASE`` is passed to ``make`` explicitly or it is generated dynamically
+in ``site.mk``, care must be taken to pass the same ``GLUON_RELEASE`` to ``make manifest``,
+as otherwise the generated manifest will be incomplete.
+
+
+Manifest format
+---------------
 
-The priority defines the maximum number of days that may pass between releasing an update and installation
-of the images. The update probability with start at 0 after the release time mentioned in the manifest
-and then slowly rise to 1 after the number of days given by the priority has passed.
+The manifest starts with a short header, followed by the list of firmwares and signatures.
+The header contains the following information:
 
-The priority may be an integer or a decimal fraction.
+.. 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 -j5 GLUON_TARGET=ar71xx-generic GLUON_BRANCH=experimental
-    make manifest GLUON_BRANCH=experimental
+    make clean GLUON_TARGET=ath79-generic
+    NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
+    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
@@ -59,7 +95,7 @@ The server must be available via IPv6.
 Command Line
 ------------
 
-These commands can be used on a node.
+These commands can be used on a node:
 
 ::
 
@@ -71,4 +107,8 @@ These commands can be used on a node.
   # 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

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/announce.rst → docs/features/monitoring.rst

-Announcing Node Information
-===========================
+Node monitoring
+===============
 
 Gluon is capable of announcing information about each node to the mesh
 and to neighbouring nodes. This allows nodes to learn each others hostname,
@@ -8,7 +8,7 @@ IP addresses, location, software versions and various other information.
 Format of collected data
 ------------------------
 
-Information to be announced is currently split into two categories:
+Information to be announced is currently split into three categories:
 
   nodeinfo
     In this category (mostly) static information is collected. If
@@ -19,17 +19,21 @@ Information to be announced is currently split into two categories:
     This category holds fast changing data, like traffic counters, uptime,
     system load or the selected gateway.
 
-Both categories will have a ``node_id`` key by default. It should be used to
-match data from *statistics* to *nodeinfo*.
+  neighbours
+    `neighbours` contains information about all neighbouring nodes of all
+    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 categories.
 
 Accessing Node Information
 --------------------------
 
 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-announced`.
+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)
 ~~~~~~~~~~~~~~~~~~~
@@ -41,10 +45,15 @@ retrieve the data you'll need both a local alfred daemon and alfred-json_
 installed. Please note that at least one alfred daemon is required to run as
 `master`.
 
-.. _alfred-json: https://github.com/tcatm/alfred-json
+.. _alfred-json: https://github.com/ffnord/alfred-json
+
+The following data types are used:
+
+* `nodeinfo`: 158
+* `statistics`: 159
+* `neighbours`: 160
 
-`nodeinfo` is distributed as alfred datatype `158`, while `statistics` uses
-`159`. Both are compressed using GZip (alfred-json can handle the decompression).
+All data is compressed using GZip (alfred-json can handle the decompression).
 
 In order to retrieve statistics data you could run:
 
@@ -88,76 +97,43 @@ In order to retrieve statistics data you could run:
 
 You can find more information about alfred in its README_.
 
-.. _README: http://www.open-mesh.org/projects/alfred/repository/revisions/master/entry/README
+.. _README: https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README.rst
 
-gluon-announced
-~~~~~~~~~~~~~~~
+gluon-respondd
+~~~~~~~~~~~~~~
 
-`gluon-announced` allows querying neighbouring nodes for their `nodeinfo`.
+`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 the bare mesh interfaces.
+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:
+
+* ``nodeinfo``, ``statistics``, ``neighbours``: Returns the data of single category uncompressed.
+* ``GET nodeinfo``, ...: Returns the data of one or multiple categories (separated by spaces)
+  compressed using the `deflate` algorithm (without a gzip header). The data may
+  be decompressed using zlib and many zlib bindings using -15 as the window size parameter.
 
 gluon-neighbour-info
 ~~~~~~~~~~~~~~~~~~~~
 
-A programm called `gluon-neighbour-info` has been developed to retrieve
-information from neighbours.
+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
 
-On optional timeout may be specified, e.g. `-t 5` (default: 3 seconds).
-
-Adding a fact
--------------
+An optional timeout may be specified, e.g. `-t 5` (default: 3 seconds). See
+the usage information printed by ``gluon-neighbour-info -h`` for more information
+about the supported arguments.
 
-To add a fact just add a file to either ``/lib/gluon/announce/nodeinfo.d/`` or
-``/lib/gluon/announce/statistics.d/``.
+Adding a data provider
+----------------------
 
-The file must contain a lua script and its name will become the key for the
-resulting JSON object. A simple script adding a ``hostname`` field might look
-like this:
-
-::
-
-  return uci:get_first('system', 'system', 'hostname')
-
-The directory structure will be converted to a JSON object, i.e. you may
-create subdirectories. So, if the directories look like this
-
-::
-
-  .
-  ├── hardware
-  │   └── model
-  ├── hostname
-  ├── network
-  │   └── mac
-  ├── node_id
-  └── software
-      └── firmware
-
-the resulting JSON would become:
-
-::
-
-  # /lib/gluon/announce/announce.lua nodeinfo
-  {
-     "hardware" : {
-        "model" : "TP-Link TL-MR3420 v1"
-     },
-     "hostname" : "mr3420-test",
-     "network" : {
-        "mac" : "90:f6:52:82:06:02"
-     },
-     "node_id" : "90f652820602",
-     "software" : {
-        "firmware" : {
-           "base" : "gluon-v2014.2-32-ge831099",
-           "release" : "0.4.1+0-exp20140720"
-        }
-     }
-  }
+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/main/net/respondd/README.md>`_
+and have a look the existing providers.

docs/features/multidomain.rst

+Multidomain Support
+===================
+
+Preamble
+--------
+
+There comes a time when a mesh network grows past sensible boundaries.
+As broadcast traffic grows, mesh networks experience scaling issues and
+using them becomes very unpleasant. An approach to solve this follows
+the well-known “divide and conquer” paradigm and splits a large network
+into multiple smaller networks. These smaller networks start with a
+dedicated layer 2 network each, which are interconnected via their
+gateways by layer 3 routing. Gluon is already field-tested handling a
+single domain and the multidomain feature allows for the reconfiguration
+of key parameters that decide which domain a node participates in,
+without the need of a distinct set of firmware images for each mesh domain.
+
+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
+
+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
+
+In the site repository, create the ``domains/`` directory, which will
+hold your domain configurations. Each domain configuration file is named
+after its primary ``domain_code``, additional domain codes and names are
+supported.
+
+::
+
+  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'
+    },
+
+    -- 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
+``alpha_centauri`` matches the filename ``alpha_centauri.conf``.
+
+Additional domain codes/names can be added to ``domain_names``, which
+are treated as aliases for the their domain configuration. Aliases can
+be used to offer more fine-grained and well-recognizable domain choices
+to users. Having multiple aliases on a single domain is a helpful
+precursor to splitting the domain into even smaller blocks.
+
+Furthermore you have to specify the ``default_domain`` in the ``site.conf``.
+This domain is applied in following cases:
+
+- When the config mode is skipped.
+- When a domain is removed in a new firmware release, the default_domain
+  will be chosen then.
+- When a user selects a wrong domain code via uci.
+
+Please note, that this value is saved to uci, so changing the `default_domain`
+value in the `site.conf` in a new firmware release only affects the actual
+domain of a router, if and only if one of the above conditions matches.
+
+
+Switching the domain
+--------------------
+
+Via commandline
+^^^^^^^^^^^^^^^
+
+::
+
+  gluon-switch-domain 'newdomaincode'
+
+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``::
+
+  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|
+
+Allowed site variables
+----------------------
+
+Internally the site variables are merged from the ``site.conf`` and the
+selected ``domain.conf``, so the most variables are also allowed in
+``site.conf`` and in ``domain.conf``. But there are some exceptions,
+which do not make sense in a domain or site specific way. The following
+sections give an overview over variables that are only usable in either
+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
+  - 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:
+
+  - domain_names
+
+    - a table of domain codes to domain names
+      ``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
+
+  - hide_domain
+
+    - prevents a domain name(s) from appearing in config mode, either
+      boolean or array of domain codes
+
+      - ``true``, ``false``
+      - ``{ 'foo', 'bar' }``
+
+- 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
+
+- To prevent accidental bridging of different domains, all meshing
+  technologies should be separated:
+
+  - domain_seed (wired mesh)
+
+    - must be a random value used to derive the vxlan id for wired meshing
+
+  - 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.
+
+  - 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.
+
+  - 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.
+
+Example config
+--------------
+
+site.mk
+^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/site.mk
+  :language: makefile
+
+site.conf
+^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/site.conf
+  :language: lua
+
+domains/alpha_centauri.conf
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/domains/alpha_centauri.conf
+  :language: lua
+
+i18n/en.po
+^^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/i18n/en.po
+  :language: po
+
+i18n/de.po
+^^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/i18n/de.po
+  :language: po
+
+modules
+^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/modules
+  :language: makefile
+
+
+.. |image0| image:: multidomain_configmode.gif

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 can be enabled through the config mode if the package ``gluon-luci-private-wifi`` is installed.
+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::
 
-  uci set wireless.wan_radio0=wifi-iface
-  uci set wireless.wan_radio0.device=radio0
-  uci set wireless.wan_radio0.network=wan
-  uci set wireless.wan_radio0.mode=ap
-  uci set wireless.wan_radio0.encryption=psk2
-  uci set wireless.wan_radio0.ssid="$SSID"
-  uci set wireless.wan_radio0.key="$KEY"
-  uci set wireless.wan_radio0.disabled=0
+  RID=0
+  SSID="privateWLANname"
+  KEY="yoursecret1337password"
+
+  uci set wireless.wan_radio$RID=wifi-iface
+  uci set wireless.wan_radio$RID.device=radio$RID
+  uci set wireless.wan_radio$RID.network=wan
+  uci set wireless.wan_radio$RID.mode=ap
+  uci set wireless.wan_radio$RID.encryption=psk2
+  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=$(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::
@@ -11,22 +11,24 @@ For this the section ``roles`` in ``site.conf`` is needed::
   roles = {
     default = 'node',
     list = {
-      node = 'Normal Node',
-      test = 'Test Node',
-      backbone = 'Backbone Node',
-      service = 'Service Node',
+      'node',
+      'test',
+      'backbone',
+      'service',
     },
   },
 
+The strings to display in the web interface are configured per language in the
+``i18n/en.po``, ``i18n/de.po``, etc. files of the site repository using message IDs like
+``gluon-web-node-role:role:node`` and ``gluon-web-node-role:role:backbone``.
+
 The value of ``default`` is the role every node will initially own. This value should be part of ``list`` as well.
 If you want node owners to change the defined roles via config-mode you can add the package
-``gluon-luci-node-role`` to your ``site.mk``. Then, you can select one of the defined roles from a dropdown list
-where the right-handed value is the one which is displayed and the left-handed key the one which is configured into 
-the system.
+``gluon-web-node-role`` to your ``site.mk``.
 
 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
+========
+
+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
+^^^^^^^^^^^^^^^^^^^^^^
+
+There are currently two supported protocol handlers which
+can be selected as a feature:
+
+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.
+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
+""""""""""""""""""
+
+WireGuard is an encrypted in-kernel tunneling protocol that
+provides encrypted transmission and at the same time offers
+high throughput.
+
+fastd
+^^^^^
+
+.. _VPN fastd methods:
+
+Methods
+"""""""
+
+fastd offers various different connection "methods" with different
+security properties that can be configured in the site configuration.
+
+The following methods are currently recommended:
+
+- ``salsa2012+umac``: Encrypted + authenticated
+- ``null+salsa2012+umac``: Unencrypted, authenticated
+- ``null@l2tp``: Unencrypted, unauthenticated
+
+Multiple methods can be listed in ``site.conf``. The first listed method
+supported by both the node and its peer will be used.
+
+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``.
+
+
+.. _vpn-gateway-configuration:
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+
+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

 Wired mesh (Mesh-on-WAN/LAN)
-============================
+############################
 
 In addition to meshing over WLAN and VPN, it is also possible to
-configured wired meshing over the LAN or WAN ports. This allows
+configure wired meshing over the LAN or WAN ports. This allows
 nodes to be connected directly or over wireless bridges.
 
 Mesh-on-WAN can be enabled in addition to the mesh VPN, so multiple nodes
@@ -11,55 +11,123 @@ 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 <https://en.wikipedia.org/wiki/Virtual_Extensible_LAN>`_, a new standard with
+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:
+
+* 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 *Expert Mode* (if the package ``gluon-luci-portconfig`` is installed).
+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
+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 add_list gluon.iface_wan.role='mesh'
+  uci commit gluon
+
+Disable Mesh-on-WAN::
+
+  uci del_list gluon.iface_wan.role='mesh'
+  uci commit gluon
 
-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``.
+Enable Mesh-on-LAN::
 
-Commandline configuration
--------------------------
+  uci add_list gluon.iface_lan.role='mesh'
+  uci commit gluon
 
-Mesh-on-WAN
-...........
+Disable Mesh-on-LAN::
 
-It's possible to enable Mesh-on-WAN like this::
+  uci del_list gluon.iface_lan.role='mesh'
+  uci commit gluon
 
-  uci set network.mesh_wan.auto=1
-  uci commit
+For devices with a single interface, instead of `iface_lan` and `iface_wan` configuration is
+done with `iface_single`.
 
-It may be disabled by running::
+Enable Mesh-on-Single::
 
-  uci set network.mesh_wan.auto=0
-  uci commit
+  uci add_list gluon.iface_single.role='mesh'
+  uci commit gluon
 
+Disable Mesh-on-Single::
 
-Mesh-on-LAN
-...........
+  uci del_list gluon.iface_single.role='mesh'
+  uci commit gluon
 
-Configuring Mesh-on-LAN is a bit more complicated::
+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 network.mesh_lan.auto=1
-  for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
-    uci del_list network.client.ifname=$ifname
-  done
-  uci commit
+  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
 
-It may be disabled by running::
+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.
 
-  uci set network.mesh_lan.auto=0
-  for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
-    uci add_list network.client.ifname=$ifname
-  done
-  uci commit
+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 v2015.2. Using
-the old commands on v2015.2 will break the corresponding Export Mode
-settings.
+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*.

docs/features/wlan-configuration.rst

+WLAN configuration
+==================
+
+Gluon allows to configure 2.4GHz and 5GHz radios independently. The configuration
+may include one or both of the two networks "client" (AP mode) and "mesh" (802.11s
+mode), which can be used simultaneously. See :doc:`../user/site` for details on the
+configuration.
+
+Outdoor mode
+------------
+
+Configuring the node for outdoor use tunes the 5 GHz radio to a frequency and transmission power that conforms with the local regulatory requirements. 
+It also enables dynamic frequency selection (DFS; radar detection).
+At the same time, mesh functionality is disabled as it requires neighbouring nodes to stay on the same channel permanently.
+
+Upgrade behaviour
+-----------------
+
+For each of these networks, the site configuration may define a `disabled` flag (by
+default, all configured networks are enabled). This flag is merely a default setting,
+on upgrades the existing setting is always retained (as this setting may have been changed
+by the user). This means that it is not possible to enable or disable an existing network
+configurations during upgrades.
+
+During upgrades the wifi channel of the 2.4GHz and 5GHz radio will be restored to the channel
+configured in the site.conf. The channel width will be reset to Gluon's default. If you need to preserve
+these settings during upgrades you can configure this via the uci section ``gluon-core.wireless``::
+
+  uci set gluon.wireless.preserve_channels='1'
+
+When channels should be preserved, toggling the outdoor mode will have no effect on the channel settings.
+Therefore, the Outdoor mode settings won't be displayed in config mode.
+Keep in mind that nodes running wifi interfaces on custom channels can't mesh with default nodes anymore!