docs/package/gluon-config-mode-domain-select.rst

@@ -5,7 +5,7 @@ the node will be placed in. If the selection has changed the upgrade scripts in
 ``/lib/gluon/upgrade/`` are triggered to update the nodes configuration.
 
 Hiding domains could be useful for default or testing domains, which should not
-be accidentally selected by a node operater.
+be accidentally selected by a node operator.
 
 domains/\*.conf
 ---------------

docs/package/gluon-config-mode-geo-location-osm.rst

+.. _package-gluon-config-mode-geo-location-osm:
+
+gluon-config-mode-geo-location-osm
+==================================
+
+When package *gluon-config-mode-geo-location-osm* is enabled, the configuration wizard will
+try to load an OSM-based map to allow the user to specify the node location.
+Loading the map requires a working internet connection, for example via WLAN
+(while connected to the Gluon node via Ethernet).
+
+.. image:: gluon-config-mode-geo-location-osm.png

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

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