docs: add documentation about multidomain support (#1365)
This commit is contained in:
lemoer
Andreas Ziegler
parent
046103e5a2
commit
c0e7b96d1d
|
|
@ -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
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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'},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
|
@ -0,0 +1 @@
|
|||
../site-example/i18n/
|
||||
|
|
@ -0,0 +1 @@
|
|||
../site-example/modules
|
||||
|
|
@ -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
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue