docs: add documentation about multidomain support (#1365)

docs/features/multidomain.rst

@@ -0,0 +1,272 @@
+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**:
+
+::
+
+    uci set gluon.core.domain="newdomaincode"
+    gluon-reconfigure
+    reboot
+
+**via config mode:**
+
+To allow switching the domain via config mode, ``config-mode-domain-select``
+has to be added to GLUON_FEATURES in the site.mk.
+
+|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
+   -  mesh_on_wan
+   -  mesh_on_lan
+   -  single_as_lan
+   -  setup_mode.skip
+   -  autoupdater.branch
+   -  mesh_vpn.enabled
+   -  mesh_vpn.pubkey_privacy
+   -  mesh_vpn.bandwidth_limit
+   -  mesh_vpn.bandwidth_limit.enabled
+   -  mesh_vpn.bandwidth_limit.ingress
+   -  mesh_vpn.bandwidth_limit.egress
+
+-  Variables that influence the appearance of the config mode,
+   domain-independent because they are relevant before a domain was selected.
+
+   -  config_mode.geo_location.show_altitude
+   -  config_mode.hostname.optional
+   -  config_mode.remote_login
+   -  config_mode.remote_login.show_password_form
+   -  config_mode.remote_login.min_password_length
+   -  hostname_prefix
+   -  mesh_vpn.fastd.configurable
+   -  roles.default
+   -  roles.list
+
+-  Specific to a firmware build itself:
+
+   -  site_code
+   -  site_name
+   -  autoupdater.branches.*.name
+   -  autoupdater.branches.*.good_signatures
+   -  autoupdater.branches.*.pubkeys
+
+-  We simply do not see any reason, why these variables could be helpful
+   in a domain specific way:
+
+   -  mesh_vpn.fastd.syslog_level
+   -  wifi*.ibss.supported_basic_rates
+   -  wifi*.mesh.supported_basic_rates
+   -  timezone
+   -  regdom
+
+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 as an own 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 accidential bridging of different domains, all meshing
+   technologies should be seperated:
+
+   -  domain_seed (wired mesh)
+
+      -  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
+
+-  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/index.rst

@@ -25,6 +25,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
    features/wired-mesh
    features/dns-forwarder
    features/monitoring
+   features/multidomain
    features/authorized-keys
    features/roles
    features/vpn

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

@@ -0,0 +1,61 @@
+{
+  -- multiple codes/names can be defined, the first one is the primary name
+  -- additional aliases can be defined
+  domain_names = {
+    alpha_centauri = 'Alpha Centauri',
+    rigil_kentaurus = 'Rigil Kentaurus',
+    proxima_centauri = 'Proxima Centauri',
+  },
+
+  -- 32 byte random data in hexadecimal encoding
+  -- Can be generated using: echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
+  domain_seed = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+
+  -- unique network prefixes per domain
+  prefix4 = '10.xxx.0.0/20',
+  prefix6 = 'fdxx:xxxx:xxxx:xxxx::/64',
+
+  next_node = {
+    ip4 = '10.xxx.yyy.zzz',
+    ip6 = 'fdxx:xxxx:xxxx:xxxx::xxxx',
+  },
+
+  wifi24= {
+    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= {
+    ap = {
+      ssid = "alpha-centauri.example.org",
+      channel = 44,
+    },
+    mesh = {
+      id = 'ueH3uXjdp',
+    },
+  },
+
+  mesh_vpn = {
+    fastd = {
+      groups = {
+        backbone = {
+          peers = {
+            peer1 = {
+              key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+              remotes = {'"peer1.example.org" port xxxxx'},
+            },
+            peer2 = {
+              key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+              remotes = {'"peer2.example.org" port xxxxx'},
+            },
+          },
+        },
+      },
+    },
+  },
+}

docs/multidomain-site-example/i18n

@@ -0,0 +1 @@
+../site-example/i18n/

docs/multidomain-site-example/modules

@@ -0,0 +1 @@
+../site-example/modules

docs/multidomain-site-example/site.conf

@@ -0,0 +1,52 @@
+{
+  site_name = 'Centauri Mesh',
+  site_code = 'centauri',
+  default_domain = 'alpha_centauri',
+
+  timezone = 'CET-1CEST,M3.5.0,M10.5.0/3',
+  ntp_server = {'ntp1.example.org', 'ntp2.example.org'},
+  regdom = 'DE',
+
+  wifi24 = {
+    mesh = {
+      mcast_rate = 12000,
+    },
+  },
+
+  wifi5 = {
+    mesh = {
+      mcast_rate = 12000,
+    },
+  },
+
+  mesh_vpn = {
+    mtu = 1312,
+
+    fastd = {
+      methods = {'salsa2012+umac'},
+    },
+
+    bandwidth_limit = {
+      enabled = false,
+      egress = 200, -- kbit/s
+      ingress = 3000, -- kbit/s
+    },
+  },
+
+  autoupdater = {
+    branch = 'stable',
+
+    branches = {
+      stable = {
+        name = 'stable',
+        mirrors = {'http://update.example.org/stable/sysupgrade'},
+        good_signatures = 2,
+        pubkeys = {
+          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
+          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Bob
+          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Mary
+        },
+      },
+    },
+  },
+}

docs/multidomain-site-example/site.mk

@@ -0,0 +1,60 @@
+##	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 \
+	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
+#			opkg compare-versions "$1" '>>' "$2"
+#		to decide if a version is newer or not.
+
+DEFAULT_GLUON_RELEASE := 0.6+exp$(shell date '+%Y%m%d')
+
+# Variables set with ?= can be overwritten from the command line
+
+##	GLUON_RELEASE
+#		call make with custom GLUON_RELEASE flag, to use your own release version scheme.
+#		e.g.:
+#			$ make images GLUON_RELEASE=23.42+5
+#		would generate images named like this:
+#			gluon-ff%site_code%-23.42+5-%router_model%.bin
+
+GLUON_RELEASE ?= $(DEFAULT_GLUON_RELEASE)
+
+# Default priority for updates.
+GLUON_PRIORITY ?= 0
+
+# Region code required for some images; supported values: us eu
+GLUON_REGION ?= eu
+
+# Languages to include
+GLUON_LANGS ?= en de