diff --git a/docs/features/multidomain.rst b/docs/features/multidomain.rst new file mode 100644 index 00000000..7fa55a3f --- /dev/null +++ b/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 diff --git a/docs/features/multidomain_configmode.gif b/docs/features/multidomain_configmode.gif new file mode 100644 index 00000000..494840f5 Binary files /dev/null and b/docs/features/multidomain_configmode.gif differ diff --git a/docs/index.rst b/docs/index.rst index 03839d3d..7c6d06eb 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/multidomain-site-example/domains/alpha_centauri.conf b/docs/multidomain-site-example/domains/alpha_centauri.conf new file mode 100644 index 00000000..27558253 --- /dev/null +++ b/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"' >' "$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