docs/features/monitoring.rst

@@ -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
@@ -104,7 +104,8 @@ 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:
@@ -122,8 +123,8 @@ 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

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,119 +123,113 @@ 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*.supported_rates
-   -  wifi*.basic_rate
-   -  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 accidental bridging of different domains, all meshing
-   technologies should be separated:
+- 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
+  - mesh_vpn.tunneldigger.brokers
 
--  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.
+- Some values should be only set in legacy domains and not in new domains.
 
-   -  mesh.vxlan
+  - 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.
+    - 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 separated from the mesh network.
-Please note that you should not enable ``mesh_on_wan`` simultaneously.
+It is possible to set up a private WLAN that bridges the uplink port and is separated from the mesh network.
+Please note that you should not enable Wired Mesh on the uplink port at the same time.
+
+The private WLAN is encrypted using WPA2 by default. On devices with enough flash and a supported radio,
+WPA3 or WPA2/WPA3 mixed-mode can be used instead of WPA2. For this to work, the ``wireless-encryption-wpa3``
+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::

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/vpn.rst

-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.
 
-- fastd
-- L2TPv3 (via tunneldigger)
+Protocol handlers
+^^^^^^^^^^^^^^^^^
 
-fastd is a lightweight userspace tunneling daemon, that
+There are currently three 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. Its primary drawback are the necessary
-context-switches when forwarding packets.
-
-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.
+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-tunneldigger
+"""""""""""""""""""""
+
+Tunneldigger always uses L2TPv3, generally achieving the same
+performance as fastd with the ``null@l2tp`` method, but offering
+no security.
+Tunneldigger's primary drawback is the lack of IPv6 support.
+It also provides less configurability than fastd.
+
+mesh-vpn-wireguard
+""""""""""""""""""
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
 
-**Unix socket:**
-To confirm whether the correct cipher is being used, fastds unix
-socket can be interrogated, after installing for example `socat`.
+    - | 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/master/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

@@ -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*.

docs/features/wlan-configuration.rst

@@ -2,10 +2,9 @@ WLAN configuration
 ==================
 
 Gluon allows to configure 2.4GHz and 5GHz radios independently. The configuration
-may include any or all of the three networks "client" (AP mode), "mesh" (802.11s
-mode) and "ibss" (adhoc mode), which can be used simultaneously (using "mesh" and
-"ibss" at same time should be avoided though as weaker hardware usually can't handle the additional
-load). See :doc:`../user/site` for details on 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.
 
 Upgrade behaviour
 -----------------
@@ -16,19 +15,12 @@ on upgrades the existing setting is always retained (as this setting may have be
 by the user). This means that it is not possible to enable or disable an existing network
 configurations during upgrades.
 
-For the "mesh" and "ibss" networks, the default setting only has an effect if none
-of the two has existed before. If a new configuration has been added for "mesh" or "ibss",
-while the other of the two has already existed before, the enabled/disabled state of the
-existing configuration will also be set for the new configuration.
-
-This allows upgrades to change from IBSS to 11s and vice-versa while retaining the
-"wireless meshing is enabled/disabled" property configured by the user regardless
-of the used mode.
-
 During upgrades the wifi channel of the 2.4GHz and 5GHz radio will be restored to the channel
-configured in the site.conf. If you need to preserve a user defined wifi channel during upgrades
-you can configure this via the uci section ``gluon-core.wireless``::
+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-core.@wireless[0].preserve_channels='1'
+  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!

docs/index.rst

@@ -6,449 +6,80 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
 
 
 .. toctree::
-   :caption: User Documentation
-   :maxdepth: 2
+  :caption: User Documentation
+  :maxdepth: 2
 
-   user/getting_started
-   user/site
-   user/x86
-   user/faq
+  user/getting_started
+  user/site
+  user/supported_devices
+  user/x86
+  user/faq
+  user/mtu
 
 .. toctree::
-   :caption: Features
-   :maxdepth: 2
-
-   features/configmode
-   features/autoupdater
-   features/wlan-configuration
-   features/private-wlan
-   features/wired-mesh
-   features/dns-forwarder
-   features/monitoring
-   features/multidomain
-   features/authorized-keys
-   features/roles
-   features/vpn
+  :caption: Features
+  :maxdepth: 2
+
+  features/configmode
+  features/autoupdater
+  features/wlan-configuration
+  features/private-wlan
+  features/wired-mesh
+  features/dns-cache
+  features/monitoring
+  features/multidomain
+  features/authorized-keys
+  features/roles
+  features/vpn
 
 .. toctree::
-   :caption: Developer Documentation
-   :maxdepth: 2
-
-   dev/basics
-   dev/hardware
-   dev/packages
-   dev/upgrade
-   dev/wan
-   dev/mac_addresses
-   dev/site_library
+  :caption: Developer Documentation
+  :maxdepth: 2
+
+  dev/basics
+  dev/hardware
+  dev/packages
+  dev/upgrade
+  dev/uplink
+  dev/mac_addresses
+  dev/site_library
+  dev/build
+  dev/debugging
 
 .. toctree::
-   :caption: gluon-web Reference
-   :maxdepth: 1
+  :caption: gluon-web Reference
+  :maxdepth: 1
 
-   dev/web/controller
-   dev/web/model
-   dev/web/view
-   dev/web/i18n
-   dev/web/config-mode
+  dev/web/controller
+  dev/web/model
+  dev/web/view
+  dev/web/i18n
+  dev/web/config-mode
 
 .. toctree::
-   :caption: Packages
-   :maxdepth: 1
-
-   package/gluon-client-bridge
-   package/gluon-config-mode-domain-select
-   package/gluon-ebtables-filter-multicast
-   package/gluon-ebtables-filter-ra-dhcp
-   package/gluon-ebtables-limit-arp
-   package/gluon-ebtables-source-filter
-   package/gluon-radv-filterd
-   package/gluon-scheduled-domain-switch
-   package/gluon-web-admin
-   package/gluon-web-logging
+  :caption: Packages
+  :maxdepth: 1
+
+  package/gluon-client-bridge
+  package/gluon-config-mode-domain-select
+  package/gluon-ebtables-filter-multicast
+  package/gluon-ebtables-filter-ra-dhcp
+  package/gluon-ebtables-limit-arp
+  package/gluon-ebtables-source-filter
+  package/gluon-hoodselector
+  package/gluon-logging
+  package/gluon-mesh-batman-adv
+  package/gluon-mesh-wireless-sae
+  package/gluon-radv-filterd
+  package/gluon-scheduled-domain-switch
+  package/gluon-web-admin
+  package/gluon-web-logging
 
 .. toctree::
-   :caption: Releases
-   :maxdepth: 1
-
-   releases/v2018.2.1
-   releases/v2018.2
-   releases/v2018.1.4
-   releases/v2018.1.3
-   releases/v2018.1.2
-   releases/v2018.1.1
-   releases/v2018.1
-   releases/v2017.1.8
-   releases/v2017.1.7
-   releases/v2017.1.6
-   releases/v2017.1.5
-   releases/v2017.1.4
-   releases/v2017.1.3
-   releases/v2017.1.2
-   releases/v2017.1.1
-   releases/v2017.1
-   releases/v2016.2.7
-   releases/v2016.2.6
-   releases/v2016.2.5
-   releases/v2016.2.4
-   releases/v2016.2.3
-   releases/v2016.2.2
-   releases/v2016.2.1
-   releases/v2016.2
-   releases/v2016.1.6
-   releases/v2016.1.5
-   releases/v2016.1.4
-   releases/v2016.1.3
-   releases/v2016.1.2
-   releases/v2016.1.1
-   releases/v2016.1
-   releases/v2015.1.2
-   releases/v2015.1.1
-   releases/v2015.1
-   releases/v2014.4
-   releases/v2014.3.1
-   releases/v2014.3
-
-
-Supported Devices & Architectures
----------------------------------
-
-ar71xx-generic
-^^^^^^^^^^^^^^
-
-* 8devices
-
-  - Carambola 2
-
-* ALFA Network
-
-  - AP121
-  - AP121F
-  - AP121U
-  - Hornet-UB
-  - Tube2H
-  - N2
-  - N5
-
-* Allnet
-
-  - ALL0315N
-
-* AVM
-
-  - Fritz!Box 4020 [#avmflash]_
-  - Fritz!WLAN Repeater 300E [#avmflash]_
-  - Fritz!WLAN Repeater 450E [#avmflash]_
-
-* Buffalo
-
-  - WZR-HP-AG300H / WZR-600DHP
-  - WZR-HP-G300NH
-  - WZR-HP-G300NH2
-  - WZR-HP-G450H
-
-* D-Link
-
-  - DAP-1330 (A1)
-  - DIR-505 (A1, A2)
-  - DIR-825 (B1)
-
-* GL Innovations
-
-  - GL-AR150
-  - GL-AR300M
-  - GL-AR750 [#ath10k]_
-  - GL-iNet 6408A (v1)
-  - GL-iNet 6416A (v1)
-
-* Linksys
-
-  - WRT160NL
-
-* Netgear
-
-  - WNDR3700 (v1, v2, v5)
-  - WNDR3800
-  - WNDRMAC (v2)
-
-* OCEDO
-
-  - Koala [#ath10k]_
-
-* Onion
-
-  - Omega
-
-* OpenMesh
-
-  - A40
-  - A60
-  - MR600 (v1, v2)
-  - MR900 (v1, v2)
-  - MR1750 (v1, v2) [#ath10k]_
-  - OM2P (v1, v2, v4)
-  - OM2P-HS (v1, v2, v3, v4)
-  - OM2P-LC
-  - OM5P
-  - OM5P-AN
-  - OM5P-AC (v1, v2) [#ath10k]_
-
-* TP-Link
-
-  - Archer C5 (v1) [#ath10k]_
-  - Archer C59 (v1) [#80211s]_
-  - Archer C7 (v2, v4, v5) [#ath10k]_
-  - CPE210 (v1.0, v1.1, v2.0)
-  - CPE220 (v1.1)
-  - CPE510 (v1.0, v1.1)
-  - CPE520 (v1.1)
-  - RE450 [#ath10k]_
-  - TL-WDR3500 (v1)
-  - TL-WDR3600 (v1)
-  - TL-WDR4300 (v1)
-  - TL-WR710N (v1, v2.1)
-  - TL-WR810N (v1)
-  - TL-WR842N/ND (v1, v2, v3)
-  - TL-WR1043N/ND (v1, v2, v3, v4, v5)
-  - TL-WR2543N/ND (v1)
-  - WBS210 (v1.20)
-  - WBS510 (v1.20)
-
-* Ubiquiti
-
-  - Air Gateway
-  - Air Gateway LR
-  - Air Gateway PRO
-  - Air Router
-  - Bullet M2/M5
-  - Loco M2/M5
-  - Loco M2/M5 XW
-  - Nanostation M2/M5
-  - Nanostation M2/M5 XW
-  - Picostation M2
-  - Rocket M2/M5
-  - Rocket M2/M5 Ti
-  - Rocket M2/M5 XW
-  - UniFi AC Mesh [#ath10k]_
-  - UniFi AC Mesh Pro [#ath10k]_
-  - UniFi AP
-  - UniFi AP AC Lite [#ath10k]_
-  - UniFi AP AC LR [#ath10k]_
-  - UniFi AP AC Pro [#ath10k]_
-  - UniFi AP LR
-  - UniFi AP Pro
-  - UniFi AP Outdoor
-  - UniFi AP Outdoor+
-
-* Western Digital
-
-  - My Net N600
-  - My Net N750
-
-* ZyXEL
-
-  - NBG6616 [#ath10k]_
-
-ar71xx-nand
-^^^^^^^^^^^
-
-* Netgear
-
-  - WNDR3700 (v4)
-  - WNDR4300 (v1)
-
-* ZyXEL
-
-  - NBG6716 [#ath10k]_
-
-ar71xx-tiny
-^^^^^^^^^^^
-
-* D-Link
-
-  - DIR-615 (C1)
-
-* TP-Link
-
-  - TL-MR13U (v1)
-  - TL-MR3020 (v1)
-  - TL-MR3040 (v1, v2)
-  - TL-MR3220 (v1, v2)
-  - TL-MR3420 (v1, v2)
-  - TL-WA701N/ND (v1, v2)
-  - TL-WA730RE (v1)
-  - TL-WA750RE (v1)
-  - TL-WA801N/ND (v1, v2, v3)
-  - TL-WA830RE (v1, v2)
-  - TL-WA850RE (v1)
-  - TL-WA860RE (v1)
-  - TL-WA901N/ND (v1, v2, v3, v4, v5)
-  - TL-WA7210N (v2)
-  - TL-WA7510N (v1)
-  - TL-WR703N (v1)
-  - TL-WR710N (v2)
-  - TL-WR740N (v1, v3, v4, v5)
-  - TL-WR741N/ND (v1, v2, v4, v5)
-  - TL-WR743N/ND (v1, v2)
-  - TL-WR840N (v2)
-  - TL-WR841N/ND (v3, v5, v7, v8, v9, v10, v11, v12)
-  - TL-WR843N/ND (v1)
-  - TL-WR940N (v1, v2, v3, v4, v5, v6)
-  - TL-WR941ND (v2, v3, v4, v5, v6)
-
-brcm2708-bcm2708
-^^^^^^^^^^^^^^^^
-
-* RaspberryPi 1
-
-brcm2708-bcm2709
-^^^^^^^^^^^^^^^^
-
-* RaspberryPi 2
-
-
-ipq40xx
-^^^^^^^
-
-* AVM
-
-  - FRITZ!Box 4040 [#80211s]_ [#avmflash]_
-
-* GL.iNet
-
-  - GL-B1300 [#80211s]_
-
-* NETGEAR
-
-  - EX6100v2 [#80211s]_
-  - EX6150v2 [#80211s]_
-
-* OpenMesh
-
-  - A42 [#80211s]_
-  - A62 [#80211s]_
-
-* ZyXEL
-
-  - NBG6617 [#80211s]_
-  - WRE6606 [#80211s]_
-
-mpc85xx-generic
-^^^^^^^^^^^^^^^
-
-* TP-Link
-
-  - TL-WDR4900 (v1)
-
-ramips-mt7620
-^^^^^^^^^^^^^
-
-* GL Innovations
-
-  - GL-MT300A [#80211s]_
-  - GL-MT300N [#80211s]_
-  - GL-MT750 [#80211s]_
-
-* Nexx
-
-  - WT3020AD/F/H
-
-ramips-mt7621
-^^^^^^^^^^^^^
-
-* D-Link
-
-  - DIR-860L (B1) [#80211s]_
-
-* Ubiquiti
-
-  - EdgeRouter X
-  - EdgeRouter X-SFP
-
-* ZBT
-
-  - WG3526-16M [#80211s]_
-  - WG3526-32M [#80211s]_
-
-ramips-mt76x8
-^^^^^^^^^^^^^
-
-* GL.iNet
-
-  - GL-MT300N v2 [#80211s]_
-
-* NETGEAR
-
-  - R6120 [#80211s]_
-
-* TP-Link
-
-  - TL-WR841N v13 [#80211s]_
-  - Archer C50 v3 [#80211s]_
-  - Archer C50 v4 [#80211s]_
-
-* VoCore
-
-  - VoCore2 [#80211s]_
-
-ramips-rt305x
-^^^^^^^^^^^^^
-
-* A5-V11 [#80211s]_
-
-* D-Link
-
-  - DIR-615 (D1, D2, D3, D4, H1) [#80211s]_
-
-* VoCore
-
-  - VoCore (8M, 16M) [#80211s]_
-
-sunxi-cortexa7
-^^^^^^^^^^^^^^
-
-* LeMaker
-
-  - Banana Pi M1
-
-x86-generic
-^^^^^^^^^^^
-
-* x86-generic
-* x86-virtualbox
-* x86-vmware
-
-See also: :doc:`user/x86`
-
-x86-geode
-^^^^^^^^^
-
-* x86-geode
-
-See also: :doc:`user/x86`
-
-x86-64
-^^^^^^
-
-* x86-64-generic
-* x86-64-virtualbox
-* x86-64-vmware
-
-See also: :doc:`user/x86`
-
-Footnotes
-^^^^^^^^^
-
-.. [#ath10k]
-  Device uses the ath10k WLAN driver; images are built for 11s by default unless GLUON_WLAN_MESH
-  is set as described in :ref:`getting-started-make-variables`
-
-.. [#80211s]
-  Device does not support IBSS; images are built by default unless GLUON_WLAN_MESH
-  is explicitly set to something other than *11s*
+  :caption: Releases
+  :maxdepth: 1
 
-.. [#avmflash]
-  For instructions on how to flash AVM devices, visit https://fritzfla.sh
+  releases/index
 
 License
 -------

docs/multidomain-site-example/domains/alpha_centauri.conf

@@ -21,26 +21,32 @@
     ip6 = 'fdxx:xxxx:xxxx:xxxx::xxxx',
   },
 
-  wifi24= {
+  wifi24 = {
+    channel = 1,
     ap = {
       ssid = "alpha-centauri.example.org",
-      channel = 1,
     },
     mesh = {
       id = 'ueH3uXjdp', -- usually you don't want users to connect to this mesh-SSID, so use a cryptic id that no one will accidentally mistake for the client WiFi
     },
   },
 
-  wifi5= {
+  wifi5 = {
+    channel = 44,
     ap = {
       ssid = "alpha-centauri.example.org",
-      channel = 44,
     },
     mesh = {
       id = 'ueH3uXjdp',
     },
   },
 
+  mesh = {
+    batman_adv = {
+      routing_algo = 'BATMAN_IV',
+    },
+  },
+
   mesh_vpn = {
     fastd = {
       groups = {

docs/multidomain-site-example/image-customization.lua

+features {
+	'autoupdater',
+	'ebtables-filter-multicast',
+	'ebtables-filter-ra-dhcp',
+	'ebtables-limit-arp',
+	'mesh-batman-adv-15',
+	'mesh-vpn-fastd',
+	'respondd',
+	'status-page',
+	'web-advanced',
+	'web-wizard',
+}
+
+packages {
+	'iwinfo',
+}
+
+if not device_class('tiny') then
+	features {'wireless-encryption-wpa3'}
+end

docs/multidomain-site-example/site.conf

@@ -20,10 +20,10 @@
   },
 
   mesh_vpn = {
-    mtu = 1312,
 
     fastd = {
       methods = {'salsa2012+umac'},
+      mtu = 1312,
     },
 
     bandwidth_limit = {

docs/multidomain-site-example/site.mk

 ##	gluon site.mk makefile example
 
-##	GLUON_FEATURES
-#		Specify Gluon features/packages to enable;
-#		Gluon will automatically enable a set of packages
-#		depending on the combination of features listed
-
-GLUON_FEATURES := \
-	autoupdater \
-	ebtables-filter-multicast \
-	ebtables-filter-ra-dhcp \
-	ebtables-limit-arp \
-	mesh-batman-adv-15 \
-	mesh-vpn-fastd \
-	radvd \
-	respondd \
-	status-page \
-	web-advanced \
-	web-wizard
-
 ##	GLUON_MULTIDOMAIN
 #		Build gluon with multidomain support.
 
 GLUON_MULTIDOMAIN=1
 
-##	GLUON_SITE_PACKAGES
-#		Specify additional Gluon/LEDE packages to include here;
-#		A minus sign may be prepended to remove a packages from the
-#		selection that would be enabled by default or due to the
-#		chosen feature flags
-
-
-GLUON_SITE_PACKAGES := haveged iwinfo
-
 ##	DEFAULT_GLUON_RELEASE
 #		version string to use for images
 #		gluon relies on

docs/package/gluon-ebtables-limit-arp.rst

 gluon-ebtables-limit-arp
 ========================
 
-The *gluon-ebtables-limit-arp* package adds filters to limit the 
-amount of ARP requests client devices are allowed to send into the 
-mesh. 
+The *gluon-ebtables-limit-arp* package adds filters to limit the
+amount of ARP requests client devices are allowed to send into the
+mesh.
 
 The limits per client device, identified by its MAC address, are
-6 packets per minute and 1 per second per node in total. 
+6 packets per minute and 1 per second per node in total.
 A burst of up to 50 ARP requests is allowed until the rate-limiting
 takes effect (see ``--limit-burst`` in ``ebtables(8)``).
 
 Furthermore, ARP requests for a target IP already present in the
-batman-adv DAT cache are excluded from rate-limiting, in regard 
+batman-adv DAT cache are excluded from rate-limiting, in regard
 to both counting and filtering, as batman-adv will be able
 to respond locally without a burden for the mesh. Therefore, this
 limiter should not affect popular target IP addresses, like those
@@ -21,3 +21,10 @@ However it mitigates the impact on the mesh when a larger range of
 its IPv4 subnet is being scanned, which would otherwise result in
 a significant amount of ARP chatter, even for unused IP addresses.
 
+This package is installed by default if the selected routing
+feature is *mesh-batman-adv-15*.
+It can be unselected via::
+
+    packages {
+      '-gluon-ebtables-limit-arp',
+    }

docs/package/gluon-hoodselector-rectangle-example.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="13cm" height="9cm" viewBox="348 138 253 169" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <g>
+    <rect style="fill: #ffffff" x="389" y="164" width="158" height="115"/>
+    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="389" y="164" width="158" height="115"/>
+  </g>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="348" y="150">
+    <tspan x="348" y="150">53.22,</tspan>
+    <tspan x="348" y="166">8.09 #</tspan>
+  </text>
+  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="545" y="288">
+    <tspan x="545" y="288"># 53.36,</tspan>
+    <tspan x="545" y="304">    8.32</tspan>
+  </text>
+</svg>

docs/package/gluon-hoodselector.rst

+gluon-hoodselector
+==================
+
+This package provides an automated way to continuously select the correct
+domain based on the geolocation of a node. The purpose of Hoodselector is to
+automatically detect in which domain the node is located based on its
+geolocation settings. Therefore domains are required to have bounding boxes,
+defined as polygons or rectangles. Based on this information Hoodselector will
+select a domain from the list of known domains and migrate towards it without
+requiring a reboot. This package therefore provides a scalable and
+decentralized approach to automatic domain selection.
+
+Background information
+----------------------
+
+The main problem of the Nordwest Freifunk community was the quickly rising
+number of nodes in the network. This indirectly affected the stability of the
+network, because the noise inside the network, e.g. management traffic from
+the batman-adv protocol, was rising, too. Inside the community there were some
+ideas like building separate firmwares for each region. This solution would
+cause issues with splitting regions again and nodes scattered among regions
+which belong to a different region. Therefore we decided to develop a
+dynamic and decentralized management of regions called domains.
+The Hoodselector's task is to choose the "right" domains in an intelligent way
+and to hold the network together and accessible.
+
+A domain is defined by geostationary fixed shapes by using longitude & latitude
+in combination with the domain configuration system. Below you can see a visual
+example of a regional domain:
+
+.. figure:: ./gluon-hoodselector-domainmap.jpeg
+    :alt: Regional domains visualized as shapes defined by latitude & longitude
+
+    © OpenStreetMap contributors
+
+Behaviour
+------------------
+
+The following is an abstract state diagram which gives an overview
+of the process:
+
+.. image:: ./gluon-hoodselector.svg
+
+The sequence of this diagram reflects the priority of its running modes.
+Each mode will be explained separately below.
+
+geolocation mode
+^^^^^^^^^^^^^^^^
+
+This mode will only be entered when a node has location coordinates set.
+Nodes with a position will set their domain based on it.
+The node will skip to the next mode when the node (a) has no position or
+(b) its position is not within any of the defined bounding boxes.
+
+default domain mode
+^^^^^^^^^^^^^^^^^^^
+
+This mode will be entered if no other mode before fits.
+It provides a fallback to the default domain.
+
+Domain shapes
+-------------
+
+There are two types of domains: the unique default one without a defined shape
+and others which contain shapes.
+
+* **default domain**
+
+The default domain doesn't hold any shapes and represents the inverted area of
+all other shapes held by other domains with geo coordinates. It will only be
+entered if a node could not be matched to a geo domain. A suggested approach is
+to define the "old" network as default domain and gradually migrate nodes from
+there to geo domains.
+
+* **geo domains**
+
+A geo domain contains shapes, which are described by three dimensional arrays
+and represents the geographical size of the domain. There are two possible
+definitions of these shapes. The first one is using rectangles so that only
+two coordinates per box are needed to define it (see below for an
+example). The second one uses polygons which can have multiple edges.
+Each domain can hold multiple shapes.
+
+.. image:: ./gluon-hoodselector-rectangle-example.svg
+
+site.conf
+---------
+
+The designer of the shapes must always ensure that no overlapping polygons
+between domains will be created or else the order in the domain list will
+become relevant. If for example domain A and B overlap, Hoodselector
+would, for that overlapping area, only ever reach domain A, but never domain B.
+Here is an example of a rectangular definition of a shape:
+Example::
+
+  hoodselector = {
+    shapes = {
+      {
+        {
+          lat = 53.128,
+          lon = 8.187
+        },
+        {
+          lat = 53.163,
+          lon = 8.216
+        },
+      },
+    },
+  },
+
+Here is an example of a shape defined by a triangle:
+Example::
+
+  hoodselector = {
+    shapes = {
+      {
+        {
+          lat = 53.128,
+          lon = 8.187
+        },
+        {
+          lat = 53.163,
+          lon = 8.216
+        },
+        {
+          lat = 53.196,
+          lon = 8.194
+        },
+      },
+    },
+  },
+
+This package is incompatible with :doc:`gluon-config-mode-domain-select`.

docs/package/gluon-logging.rst

+gluon-logging
+=============
+
+The *gluon-logging* package allows to configure a remote syslog server that
+will receive the systems log output that is also visible when calling ``logread``
+from a terminal.
+
+It supports both IPv4 and IPv6 endpoints over UDP and TCP.
+
+Note: The syslog mechanism is incapable of providing a complete log as network
+access is required to send out log messages and ``logd`` does not buffer and resend
+older log messages even though they might be available in ``logread``.
+
+This package conflicts with ``gluon-web-logging`` as it will overwrite the
+user-given syslog server on every upgrade.
+
+site.conf
+---------
+
+syslog.ip : required
+    - Destination address of the remote syslog server
+
+syslog.port : optional
+    - Destination port of the remote syslog server
+    - Defaults to 514
+
+syslog.proto : optional
+    - Protocol to transport syslog frames in, can be either ``tcp`` or ``udp``
+    - Defaults to UDP
+
+Example::
+
+  syslog = {
+    ip = "2001:db8::1",
+    port = 514,
+    proto = "udp",
+  },

docs/package/gluon-mesh-batman-adv-logo.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" version="1.1" width="931.48547" height="370.93994" id="svg4059" inkscape:version="0.48.1 r9760" sodipodi:docname="bat_v2_black.svg" inkscape:export-filename="/mnt/pandem0nium/pub/incoming/bat_logo_v2/bat_v2_black.png" inkscape:export-xdpi="90" inkscape:export-ydpi="90" style="display:inline">
+  <sodipodi:namedview pagecolor="#000000" bordercolor="#666666" borderopacity="1" objecttolerance="10" gridtolerance="10" guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" inkscape:window-width="956" inkscape:window-height="1173" id="namedview9" showgrid="false" inkscape:zoom="0.88204281" inkscape:cx="466.24453" inkscape:cy="37.028713" inkscape:window-x="1920" inkscape:window-y="0" inkscape:window-maximized="0" inkscape:current-layer="layer2" fit-margin-top="0" fit-margin-left="0" fit-margin-right="0" fit-margin-bottom="0" inkscape:snap-nodes="true"/>
+  <defs id="defs4061"/>
+  <metadata id="metadata4064">
+    <rdf:RDF>
+      <cc:Work rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/>
+        <dc:title/>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g inkscape:groupmode="layer" id="layer3" inkscape:label="outline" style="display:none" transform="translate(6.26672, 5.9375)">
+    <path style="color:#000000;fill:#ffffff;stroke:none;stroke-width:4.27199984;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" d="m 483.25,-3.21875 c -6.08901,48.631979 -35.33662,91.011416 -69.21578,124.91707 -21.83485,21.38244 -47.03966,39.44335 -75.34672,51.17668 5.57969,-19.28428 1.04687,-40.97874 -11.5,-56.59375 2.45626,-29.914047 0.68927,-59.992978 -2.5,-89.78125 -15.98198,19.265018 -27.7684,41.544355 -37.5,64.5 -12.24825,-3.17862 -25.72651,-2.402049 -37.71875,0.46875 C 239.88593,74.102096 226.47693,59.077996 210.625,47.0625 c -3.34092,23.469062 -2.56561,47.559048 0.25,70.875 -6.69043,8.82966 -11.26059,19.42531 -12.0625,30.53125 -1.92921,1.3424 -3.05608,3.45019 -4.6875,0.40625 -20.84238,-21.1131 -32.59851,-48.84198 -44.9375,-75.34375 -14.85679,72.96988 -54.000466,137.54014 -93.508574,199.57505 -20.539303,31.20908 -42.388201,61.40672 -64.085176,91.86245 8.08014534,2.26279 14.376322,-5.17296 21.382238,-7.84546 48.067949,-26.0431 95.020242,-57.97999 149.805262,-67.65454 7.73822,-1.18656 15.65228,-1.74501 23.53125,-1.625 -0.16141,-13.91977 12.35539,-25.87856 26.40625,-24.625 13.02151,-0.10475 25.24921,5.06339 36.71875,10.84375 3.0761,-8.90096 9.56834,-15.98034 17.8125,-20.25 15.98458,27.53202 46.28592,42.98776 75.65932,52.75163 10.28498,3.53684 21.92146,5.33208 32.02818,7.49837 -0.72852,8.29742 2.55832,18.64745 11.71875,20.5625 7.84288,-6.18411 13.7902,-15.27395 22.59202,-19.68372 10.89918,-0.79379 21.80373,-2.64611 32.18923,-5.97253 8.1863,6.12253 18.23881,13.28825 29.03125,9.78125 0.2397,-7.80979 -2.17974,-15.60208 -1.25,-23.34375 14.60652,-14.33722 28.49903,-29.6116 39.75,-46.65625 -31.89112,0.19103 -65.39001,-1.50716 -93.6875,-17.375 12.63668,-0.24322 25.04624,3.36048 36.09375,9.40625 26.41279,-12.24594 57.54458,-3.79641 80.97725,11.3725 5.86994,3.60205 11.37305,7.64719 16.46025,12.19 36.58823,-16.89113 78.56629,-15.82385 118.11934,-12.20623 88.66214,9.36494 173.26796,44.12384 247.50566,92.70623 3.41963,1.85442 7.16209,2.95892 10.78125,4.40625 -11.75164,-20.6658 -29.05422,-37.32743 -43.5,-56.125 C 818.67884,217.58496 746.42668,149.41496 664.49937,94.602513 607.29452,55.830775 546.38636,22.78003 483.5625,-5.9375 c -0.10417,0.90625 -0.20833,1.8125 -0.3125,2.71875 z" id="path3993-5" inkscape:connector-curvature="0"/>
+  </g>
+  <g inkscape:groupmode="layer" id="layer2" inkscape:label="batman-adv" style="display:inline" transform="translate(6.26672, 5.9375)">
+    <g style="display:inline" transform="translate(-51.5312, -495.768)" id="layer1">
+      <path d="m 538.40625,495.76769 c -8.05674,66.9338 -77.31603,151.94452 -154.9375,179.84375 3.27747,-7.40037 5.09375,-15.49392 5.09375,-24 0,-14.42887 -5.21809,-27.70021 -13.96875,-38.3125 1.97025,-21.96404 1.77421,-48.67721 -1.375,-80.59375 -13.0022,16.9579 -23.30307,37.7663 -32.15625,58.78125 -6.27289,-1.8029 -12.93745,-2.78125 -19.84375,-2.78125 -7.73405,0 -15.17627,1.22854 -22.09375,3.46875 -7.42014,-13.90647 -17.47037,-28.11748 -33.78125,-41.59375 -2.4998,23.48832 -1.59267,44.90394 1.6875,63.65625 -8.2866,10.45096 -13.63544,23.35979 -12.0986,32.68414 -4.42484,0.36051 -5.23536,4.01016 -5.31948,6.88419 -19.28312,-16.49687 -32.60091,-39.15698 -47.58192,-72.16208 -13.26705,58.98947 -53.37139,142.16702 -150.5,273.75 61.55905,-33.2251 123.79671,-75.61843 182.8125,-75.78125 4.05468,-25.33145 30.1327,-32.48291 64.65625,-15.15625 4.05331,-9.20658 11.84907,-15.85762 21.59375,-20.21875 12.89223,29.16757 60.06405,56.23506 110.53125,61.78125 -2.71475,10.31567 2.48339,19.28096 6.03125,19.90625 L 457.25,806.89269 c 12.40469,-0.59384 24.70147,-2.7024 36.40625,-6.5625 8.39362,6.41285 17.71829,12.37841 24.1875,10.96875 l -1.71875,-21.125 c 13.74684,-14.03964 23.51218,-23.14064 36.6879,-41.69749 -37.60849,-0.0334 -70.29254,-4.68998 -97.84415,-24.05251 14.31376,-2.87534 30.90137,-1.2243 48.09375,7.71875 48.64496,-20.64584 97.96875,23.25 97.96875,23.25 59.36547,-28.55091 217.47867,-17.57755 366.6875,81.8125 -81.50891,-100.35408 -186.3503,-229.51108 -429.3125,-341.4375 z" id="path3993" style="color:#000000;fill:#000000;stroke:none;stroke-width:4.27199984;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" inkscape:export-filename="/home/sven/dokumente/bat_logo_v2.png" inkscape:export-xdpi="90" inkscape:export-ydpi="90" inkscape:connector-curvature="0" sodipodi:nodetypes="ccscccscccccccccccccccccccccc"/>
+      <path d="m 287.37698,691.21665 6.32487,6.0769 42.42641,-3.28299 4.04061,-10.85914 -6.08375,5.31015 -38.85662,6.0495 z" id="path4001" style="color:#000000;fill:#ffffff;stroke:none;stroke-width:1.77165353;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" inkscape:connector-curvature="0" sodipodi:nodetypes="ccccccc"/>
+      <path d="m 304.03798,658.90775 c 3.73562,-7.35256 3.37257,-7.75354 27.47128,-14.84657 15.15993,-4.46206 30.11288,-9.25782 32.38025,-2.07348 l 18.53034,-4.86774 0.54842,3.1737 -18.32114,6.49226 c -3.7905,21.99567 -3.66551,19.92566 -20.7106,21.97074 -27.63928,3.31618 -30.32837,6.17704 -39.39348,-6.06083 l -7.32361,1.01015 c -3.77481,8.34177 -0.87651,8.42602 -25.47706,7.6321 -16.18663,-0.52238 -14.20261,-0.23719 -17.22819,-15.14996 -1.35304,-6.66902 -0.33802,-7.91117 21.30347,-5.15085 17.50983,2.23334 17.19396,1.76122 21.20894,8.92319 z" id="path4003" style="color:#000000;fill:#ffffff;stroke:none;stroke-width:1.77165353;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" inkscape:connector-curvature="0" sodipodi:nodetypes="csccccsccssscc"/>
+    </g>
+  </g>
+</svg>
\ No newline at end of file