From 854fef4e12c07751c4da78081ac534e87ade9afd Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Fri, 24 Dec 2021 14:16:04 +0100
Subject: [PATCH] docs: consistently indent .rst files with 2 spaces
2 spaces is the most common indentation width used in the docs; adjust
the rest for consistency.
Also change .editorconfig accordingly.
---
.editorconfig | 2 +-
docs/dev/basics.rst | 6 +-
docs/dev/debugging.rst | 10 +-
docs/dev/packages.rst | 17 +-
docs/features/autoupdater.rst | 14 +-
docs/features/multidomain.rst | 218 ++--
docs/features/vpn.rst | 6 +-
docs/package/gluon-mesh-batman-adv.rst | 4 +-
.../package/gluon-scheduled-domain-switch.rst | 18 +-
docs/releases/v2015.1.rst | 28 +-
docs/releases/v2016.1.5.rst | 18 +-
docs/releases/v2019.1.1.rst | 12 +-
docs/releases/v2019.1.2.rst | 12 +-
docs/releases/v2019.1.3.rst | 12 +-
docs/releases/v2019.1.rst | 38 +-
docs/releases/v2020.1.1.rst | 12 +-
docs/releases/v2020.1.2.rst | 12 +-
docs/releases/v2020.1.3.rst | 12 +-
docs/releases/v2020.1.rst | 92 +-
docs/user/getting_started.rst | 38 +-
docs/user/site.rst | 969 +++++++++---------
21 files changed, 773 insertions(+), 777 deletions(-)
diff --git a/.editorconfig b/.editorconfig
index 5174a187e..9dca9dab9 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -25,7 +25,7 @@ indent_size = 4
[*.rst]
indent_style = space
-indent_size = 3
+indent_size = 2
[*.yml]
indent_style = space
diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst
index 5508897c3..8608567e5 100644
--- a/docs/dev/basics.rst
+++ b/docs/dev/basics.rst
@@ -32,7 +32,7 @@ rerun
::
- make update
+ make update
`make update` also applies the patches that can be found in the directories found in
`patches`; the resulting branch will be called `patched`, while the commit specified in `modules`
@@ -44,7 +44,7 @@ using
::
- make update-patches
+ make update-patches
If applying a patch fails because you have changed the base commit, the repository will be reset to the old `patched` branch
and you can try rebasing it onto the new `base` branch yourself and after that call `make update-patches` to fix the problem.
@@ -54,7 +54,7 @@ commits, making `git reflog` the only way to recover them!
::
- make refresh-patches
+ make refresh-patches
In order to refresh patches when updating feeds or the OpenWrt base, `make refresh-patches` applies and updates all of their patches without installing feed packages to the OpenWrt buildsystem.
diff --git a/docs/dev/debugging.rst b/docs/dev/debugging.rst
index 520734285..ca1cd0416 100644
--- a/docs/dev/debugging.rst
+++ b/docs/dev/debugging.rst
@@ -32,12 +32,12 @@ The tooling is contained in the kernel source tree in the file
`decode_stacktrace.sh <https://github.com/torvalds/linux/blob/master/scripts/decode_stacktrace.sh>`__.
This file and the needed source tree are available in the directory: ::
- openwrt/build_dir/target-<architecture>/linux-<architecture>/linux-<version>/
+ openwrt/build_dir/target-<architecture>/linux-<architecture>/linux-<version>/
.. note::
- Make sure to use a kernel tree that matches the version and patches
- that was used to build the kernel.
- If in doubt just re-build the images for the target.
+ Make sure to use a kernel tree that matches the version and patches
+ that was used to build the kernel.
+ If in doubt just re-build the images for the target.
Some more information on how to use this tool can be found at
`LWN <https://lwn.net/Articles/592724/>`__.
@@ -48,4 +48,4 @@ Obtaining Stacktraces
On many targets stacktraces can be read from the following
location after reboot: ::
- /sys/kernel/debug/crashlog
+ /sys/kernel/debug/crashlog
diff --git a/docs/dev/packages.rst b/docs/dev/packages.rst
index 098b0276c..7c239675b 100644
--- a/docs/dev/packages.rst
+++ b/docs/dev/packages.rst
@@ -9,13 +9,16 @@ Development workflow
When you are developing packages, it often happens that you iteratively want to deploy
and verify the state your development. There are two ways to verify your changes:
-1) One way is to rebuild the complete firmware, flash it, configure it and verify your
- development then. This usually takes at least a few minutes to get your changes
- working so you can test them. Especially if you iterate a lot, this becomes tedious.
-2) Another way is to rebuild only the package you are currently working on and
- to deploy this package to your test system. Here not even a reboot is required.
- This makes iterating relatively fast. Your test system could be real hardware or
- even a qemu in most cases.
+1)
+ One way is to rebuild the complete firmware, flash it, configure it and verify your
+ development then. This usually takes at least a few minutes to get your changes
+ working so you can test them. Especially if you iterate a lot, this becomes tedious.
+
+2)
+ Another way is to rebuild only the package you are currently working on and
+ to deploy this package to your test system. Here not even a reboot is required.
+ This makes iterating relatively fast. Your test system could be real hardware or
+ even a qemu in most cases.
Gluon provides scripts to enhance workflow 2). Here is an example illustrating
the workflow using these scripts:
diff --git a/docs/features/autoupdater.rst b/docs/features/autoupdater.rst
index 6e011245f..545b8237d 100644
--- a/docs/features/autoupdater.rst
+++ b/docs/features/autoupdater.rst
@@ -99,16 +99,16 @@ These commands can be used on a node:
::
- # Update with some probability
- autoupdater
+ # Update with some probability
+ autoupdater
::
- # Force update check, even when the updater is disabled
- autoupdater -f
+ # Force update check, even when the updater is disabled
+ autoupdater -f
::
- # If fallback is true the updater will perform an update only if the timespan
- # PRIORITY days (as defined in the manifest) and another 24h have passed
- autoupdater --fallback
+ # If fallback is true the updater will perform an update only if the timespan
+ # PRIORITY days (as defined in the manifest) and another 24h have passed
+ autoupdater --fallback
diff --git a/docs/features/multidomain.rst b/docs/features/multidomain.rst
index 7abd59a80..91dd7bcff 100644
--- a/docs/features/multidomain.rst
+++ b/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
@@ -93,12 +93,12 @@ Via commandline
::
- gluon-switch-domain 'newdomaincode'
+ gluon-switch-domain 'newdomaincode'
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``::
- gluon-switch-domain --no-reboot 'newdomaincode'
+ gluon-switch-domain --no-reboot 'newdomaincode'
Switching the domain without reboot is currently **experimental**.
@@ -123,115 +123,115 @@ 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
- - 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
+ - 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
+ - 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 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
+ - 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*.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
--------------
diff --git a/docs/features/vpn.rst b/docs/features/vpn.rst
index 8697baad8..c1ed93366 100644
--- a/docs/features/vpn.rst
+++ b/docs/features/vpn.rst
@@ -52,6 +52,6 @@ socket can be interrogated, after installing for example `socat`.
::
- opkg update
- opkg install socat
- socat - UNIX-CONNECT:/var/run/fastd.mesh_vpn.socket
+ opkg update
+ opkg install socat
+ socat - UNIX-CONNECT:/var/run/fastd.mesh_vpn.socket
diff --git a/docs/package/gluon-mesh-batman-adv.rst b/docs/package/gluon-mesh-batman-adv.rst
index 291353242..cd362ede9 100644
--- a/docs/package/gluon-mesh-batman-adv.rst
+++ b/docs/package/gluon-mesh-batman-adv.rst
@@ -2,7 +2,7 @@ gluon-mesh-batman-adv
=====================
.. image:: gluon-mesh-batman-adv-logo.svg
- :width: 300 px
+ :width: 300 px
B.A.T.M.A.N. Advanced (often referenced as batman-adv) is an implementation of
the B.A.T.M.A.N. routing protocol in form of a linux kernel module operating on layer 2.
@@ -47,7 +47,7 @@ Multicast Architecture
----------------------
.. image:: gluon-mesh-batman-adv-multicast.svg
- :width: 300 px
+ :width: 300 px
While generally broadcast capability is a nice feature of a layer 2
mesh protocol, it quickly reaches its limit.
diff --git a/docs/package/gluon-scheduled-domain-switch.rst b/docs/package/gluon-scheduled-domain-switch.rst
index ee1fe146d..f67c500d7 100644
--- a/docs/package/gluon-scheduled-domain-switch.rst
+++ b/docs/package/gluon-scheduled-domain-switch.rst
@@ -15,15 +15,15 @@ site.conf
All those settings have to be defined exclusively in the domain, not the site.
domain_switch : optional (needed for domains to switch)
- target_domain :
- - target domain to switch to
- switch_after_offline_mins :
- - amount of time without reachable gateway to switch unconditionally
- switch_time :
- - UNIX epoch after which domain will be switched
- connection_check_targets :
- - array of IPv6 addresses which are probed to determine if the node is
- connected to the mesh
+ target_domain :
+ - target domain to switch to
+ switch_after_offline_mins :
+ - amount of time without reachable gateway to switch unconditionally
+ switch_time :
+ - UNIX epoch after which domain will be switched
+ connection_check_targets :
+ - array of IPv6 addresses which are probed to determine if the node is
+ connected to the mesh
Example::
diff --git a/docs/releases/v2015.1.rst b/docs/releases/v2015.1.rst
index 2fd694c12..785c2b28a 100644
--- a/docs/releases/v2015.1.rst
+++ b/docs/releases/v2015.1.rst
@@ -170,16 +170,16 @@ Site changes
for example::
fastd_mesh_vpn = {
- methods = {'salsa2012+umac'},
- mtu = 1426,
- groups = {
- backbone = {
- limit = 2,
- peers = {
- -- ...
- }
- }
+ methods = {'salsa2012+umac'},
+ mtu = 1426,
+ groups = {
+ backbone = {
+ limit = 2,
+ peers = {
+ -- ...
+ }
}
+ }
}
- ``config_mode``: The config mode messages aren't configured in ``site.conf`` anymore. Instead, they are
@@ -190,11 +190,11 @@ Site changes
in the site i18n files. The ``site.conf`` section becomes::
roles = {
- default = 'foo',
- list = {
- 'foo',
- 'bar',
- }
+ default = 'foo',
+ list = {
+ 'foo',
+ 'bar',
+ }
}
The display string use i18n message IDs like ``gluon-luci-node-role:role:foo`` and ``gluon-luci-node-role:role:bar``.
diff --git a/docs/releases/v2016.1.5.rst b/docs/releases/v2016.1.5.rst
index 142be29eb..8752a9173 100644
--- a/docs/releases/v2016.1.5.rst
+++ b/docs/releases/v2016.1.5.rst
@@ -9,21 +9,21 @@ ar71xx-generic
* OpenMesh
- - MR600 (v1, v2)
- - MR900 (v1, v2)
- - OM2P (v1, v2)
- - OM2P-HS (v1, v2)
- - OM2P-LC
- - OM5P
- - OM5P-AN
+ - MR600 (v1, v2)
+ - MR900 (v1, v2)
+ - OM2P (v1, v2)
+ - OM2P-HS (v1, v2)
+ - OM2P-LC
+ - OM5P
+ - OM5P-AN
* Ubiquiti
- - Rocket M XW
+ - Rocket M XW
* TP-LINK
- - TL-WR841N/ND v11
+ - TL-WR841N/ND v11
Bugfixes
~~~~~~~~
diff --git a/docs/releases/v2019.1.1.rst b/docs/releases/v2019.1.1.rst
index 0385e8bf3..2e173d7a1 100644
--- a/docs/releases/v2019.1.1.rst
+++ b/docs/releases/v2019.1.1.rst
@@ -30,13 +30,13 @@ Known issues
* The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
* Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/releases/v2019.1.2.rst b/docs/releases/v2019.1.2.rst
index 7d44fd499..7231b4ef3 100644
--- a/docs/releases/v2019.1.2.rst
+++ b/docs/releases/v2019.1.2.rst
@@ -26,13 +26,13 @@ Known issues
* The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
* Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/releases/v2019.1.3.rst b/docs/releases/v2019.1.3.rst
index 11dd09599..aab216931 100644
--- a/docs/releases/v2019.1.3.rst
+++ b/docs/releases/v2019.1.3.rst
@@ -36,13 +36,13 @@ Known issues
* The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
* Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/releases/v2019.1.rst b/docs/releases/v2019.1.rst
index a9e0a829e..6632b1190 100644
--- a/docs/releases/v2019.1.rst
+++ b/docs/releases/v2019.1.rst
@@ -73,8 +73,8 @@ ramips-mt7621
.. note::
- The ``ipq806x`` target has been flagged as broken, as none of its devices are fully supported in this OpenWrt
- release yet. You might have to update your build scripts accordingly.
+ The ``ipq806x`` target has been flagged as broken, as none of its devices are fully supported in this OpenWrt
+ release yet. You might have to update your build scripts accordingly.
@@ -109,20 +109,20 @@ have outdoor mode automatically enabled during their initial setup, specifically
* Ubiquiti
- - Bullet M
- - Litebeam M5
- - Nanostation M5
- - Nanostation M5 Loco
- - Rocket M5
- - Rocket M5 TI
- - Unifi AC Mesh
- - Unifi AC Mesh Pro
- - Unifi Outdoor
+ - Bullet M
+ - Litebeam M5
+ - Nanostation M5
+ - Nanostation M5 Loco
+ - Rocket M5
+ - Rocket M5 TI
+ - Unifi AC Mesh
+ - Unifi AC Mesh Pro
+ - Unifi Outdoor
* TP-Link
- - CPE510
- - WBS510
+ - CPE510
+ - WBS510
See the :ref:`wifi5 <user-site-wifi5>` section for the *site.conf* configuration of this feature.
@@ -253,13 +253,13 @@ Known issues
* The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
* Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/releases/v2020.1.1.rst b/docs/releases/v2020.1.1.rst
index f18d1133a..c78415315 100644
--- a/docs/releases/v2020.1.1.rst
+++ b/docs/releases/v2020.1.1.rst
@@ -25,13 +25,13 @@ Known issues
- The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
- Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/releases/v2020.1.2.rst b/docs/releases/v2020.1.2.rst
index 37adb6a16..4bc7c800c 100644
--- a/docs/releases/v2020.1.2.rst
+++ b/docs/releases/v2020.1.2.rst
@@ -50,13 +50,13 @@ Known issues
- The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
- Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/releases/v2020.1.3.rst b/docs/releases/v2020.1.3.rst
index 429d4c78c..7b82b433e 100644
--- a/docs/releases/v2020.1.3.rst
+++ b/docs/releases/v2020.1.3.rst
@@ -30,13 +30,13 @@ Known issues
- The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
- Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/releases/v2020.1.rst b/docs/releases/v2020.1.rst
index d3bea233b..8dd23630a 100644
--- a/docs/releases/v2020.1.rst
+++ b/docs/releases/v2020.1.rst
@@ -11,80 +11,80 @@ Added hardware support
ath79-generic
~~~~~~~~~~~~~
-- devolo WiFi pro 1200e
-- devolo WiFi pro 1200i
-- devolo WiFi pro 1750c
-- devolo WiFi pro 1750e
-- devolo WiFi pro 1750i
-- devolo WiFi pro 1750x
-- GL.iNet GL-AR300M-Lite
-- OCEDO Raccoon
-- TP-Link Archer C6 v2
+- devolo WiFi pro 1200e
+- devolo WiFi pro 1200i
+- devolo WiFi pro 1750c
+- devolo WiFi pro 1750e
+- devolo WiFi pro 1750i
+- devolo WiFi pro 1750x
+- GL.iNet GL-AR300M-Lite
+- OCEDO Raccoon
+- TP-Link Archer C6 v2
ipq40xx-generic
~~~~~~~~~~~~~~~
-- Aruba AP-303
-- Aruba Instant On AP11
-- AVM FRITZ!Repeater 1200
+- Aruba AP-303
+- Aruba Instant On AP11
+- AVM FRITZ!Repeater 1200
ipq806x-generic
~~~~~~~~~~~~~~~
-- Netgear R7800
+- Netgear R7800
lantiq-xway
~~~~~~~~~~~
-- AVM FRITZ!Box 7312
-- AVM FRITZ!Box 7320
-- AVM FRITZ!Box 7330
-- AVM FRITZ!Box 7330 SL
+- AVM FRITZ!Box 7312
+- AVM FRITZ!Box 7320
+- AVM FRITZ!Box 7330
+- AVM FRITZ!Box 7330 SL
lantiq-xrx200
~~~~~~~~~~~~~
-- AVM FRITZ!Box 7360 (v1, v2)
-- AVM FRITZ!Box 7360 SL
-- AVM FRITZ!Box 7362 SL
-- AVM FRITZ!Box 7412
+- AVM FRITZ!Box 7360 (v1, v2)
+- AVM FRITZ!Box 7360 SL
+- AVM FRITZ!Box 7362 SL
+- AVM FRITZ!Box 7412
mpc85xx-p1020
~~~~~~~~~~~~~
-- Enterasys WS-AP3710i
-- OCEDO Panda
+- Enterasys WS-AP3710i
+- OCEDO Panda
ramips-mt7620
~~~~~~~~~~~~~
-- TP-Link Archer C2 (v1)
-- TP-Link Archer C20 (v1)
-- TP-Link Archer C20i
-- TP-Link Archer C50 (v1)
-- Xiaomi MiWifi Mini
+- TP-Link Archer C2 (v1)
+- TP-Link Archer C20 (v1)
+- TP-Link Archer C20i
+- TP-Link Archer C50 (v1)
+- Xiaomi MiWifi Mini
ramips-mt7621
~~~~~~~~~~~~~
-- Netgear EX6150 (v1)
-- Netgear R6220
+- Netgear EX6150 (v1)
+- Netgear R6220
ramips-mt76x8
~~~~~~~~~~~~~
-- GL.iNet VIXMINI
-- TP-Link TL-MR3020 (v3)
-- TP-Link TL-WA801ND (v5)
-- TP-Link TL-WR902AC (v3)
+- GL.iNet VIXMINI
+- TP-Link TL-MR3020 (v3)
+- TP-Link TL-WA801ND (v5)
+- TP-Link TL-WR902AC (v3)
Removed hardware support
------------------------
-- ALFA Network Hornet-UB [#kernelpartition_too_small]_
-- ALFA Network Tube2H [#kernelpartition_too_small]_
-- ALFA Network N2 [#kernelpartition_too_small]_
-- ALFA Network N5 [#kernelpartition_too_small]_
+- ALFA Network Hornet-UB [#kernelpartition_too_small]_
+- ALFA Network Tube2H [#kernelpartition_too_small]_
+- ALFA Network N2 [#kernelpartition_too_small]_
+- ALFA Network N5 [#kernelpartition_too_small]_
.. [#kernelpartition_too_small]
The kernel partition on this device is too small to build a working image.
@@ -162,8 +162,8 @@ Site changes
site.mk
~~~~~~~
-- The ``GLUON_WLAN_MESH`` variable can be dropped, as 802.11s is
- the only supported wireless transport from now on.
+- The ``GLUON_WLAN_MESH`` variable can be dropped, as 802.11s is
+ the only supported wireless transport from now on.
Internals
---------
@@ -206,13 +206,13 @@ Known issues
* The integration of the BATMAN_V routing algorithm is incomplete.
- - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
- | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
- | metric.
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
- - | Throughput values are not correctly acquired for different interface types.
- | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
- | This affects virtual interface types like bridges and VXLAN.
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
* Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
(`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
diff --git a/docs/user/getting_started.rst b/docs/user/getting_started.rst
index 5d8d6aa2c..a7b9d0cbb 100644
--- a/docs/user/getting_started.rst
+++ b/docs/user/getting_started.rst
@@ -44,7 +44,7 @@ We also provide a container environment that already tracks all these dependenci
::
- ./scripts/container.sh
+ ./scripts/container.sh
Building the images
-------------------
@@ -54,31 +54,31 @@ version you'd like to checkout, e.g. *v2021.1*.
::
- git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE
+ git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE
This command will create a directory named *gluon/*.
It might also tell a scary message about being in a *detached state*.
**Don't panic!** Everything's fine.
Now, enter the freshly created directory::
- cd gluon
+ cd gluon
It's time to add (or create) your site configuration. If you already
have a site repository, just clone it::
- git clone https://github.com/freifunk-alpha-centauri/site-ffac.git site
+ git clone https://github.com/freifunk-alpha-centauri/site-ffac.git site
If you want to build a new site, create a new git repository *site/*::
- mkdir site
- cd site
- git init
+ mkdir site
+ cd site
+ git init
Copy *site.conf*, *site.mk* and *i18n* from *docs/site-example*::
- cp ../docs/site-example/site.conf .
- cp ../docs/site-example/site.mk .
- cp -r ../docs/site-example/i18n .
+ cp ../docs/site-example/site.conf .
+ cp ../docs/site-example/site.mk .
+ cp -r ../docs/site-example/i18n .
Edit these files as you see fit and commit them into the site repository.
Extensive documentation about the site configuration can be found at:
@@ -88,9 +88,9 @@ to the Gluon main repository should be avoided, as it will make updates more com
Next go back to the top-level Gluon directory and build Gluon::
- cd ..
- make update # Get other repositories used by Gluon
- make GLUON_TARGET=ath79-generic # Build Gluon
+ cd ..
+ make update # Get other repositories used by Gluon
+ make GLUON_TARGET=ath79-generic # Build Gluon
In case of errors read the messages carefully and try to fix the stated issues
(e.g. install missing tools not available or look for Troubleshooting_ in the wiki.
@@ -102,9 +102,9 @@ To see a complete list of supported targets, call ``make`` without setting ``GLU
To build all targets use a loop like this::
- for TARGET in $(make list-targets); do
- make GLUON_TARGET=$TARGET
- done
+ for TARGET in $(make list-targets); do
+ make GLUON_TARGET=$TARGET
+ done
You should generally reserve 5GB of disk space and additionally about 10GB for each `GLUON_TARGET`.
@@ -117,7 +117,7 @@ system.
of multiple copies of the same image. If your webserver's configuration prohibits following
symlinks, you can use the following command to resolve these links while copying the images::
- cp -rL output/images /var/www
+ cp -rL output/images /var/www
The directory `output/debug` contains a compressed kernel image for each
architecture.
@@ -130,14 +130,14 @@ Cleaning the build tree
There are two levels of `make clean`::
- make clean GLUON_TARGET=ath79-generic
+ make clean GLUON_TARGET=ath79-generic
will ensure all packages are rebuilt for a single target. This is usually not
necessary, but may fix certain kinds of build failures.
::
- make dirclean
+ make dirclean
will clean the entire tree, so the toolchain will be rebuilt as well, which will take a while.
diff --git a/docs/user/site.rst b/docs/user/site.rst
index a3d221c49..e018bf16e 100644
--- a/docs/user/site.rst
+++ b/docs/user/site.rst
@@ -12,543 +12,536 @@ Configuration
The ``site.conf`` is a lua dictionary with the following defined keys.
hostname_prefix
- A string which shall prefix the default hostname of a device.
+ A string which shall prefix the default hostname of a device.
site_name
- The name of your community.
+ The name of your community.
site_code
- The code of your community. It is good practice to use the TLD of
- your community here.
+ The code of your community. It is good practice to use the TLD of
+ your community here.
domain_seed
- 32 bytes of random data, encoded in hexadecimal, used to seed other random
- values specific to the mesh domain. It must be the same for all nodes of one
- mesh, but should be different for firmware that is not supposed to mesh with
- each other.
+ 32 bytes of random data, encoded in hexadecimal, used to seed other random
+ values specific to the mesh domain. It must be the same for all nodes of one
+ mesh, but should be different for firmware that is not supposed to mesh with
+ each other.
- The recommended way to generate a value for a new site is:
- ::
+ The recommended way to generate a value for a new site is::
- echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
+ echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
prefix4 \: optional
- The IPv4 Subnet of your community mesh network in CIDR notation, e.g.
- ::
+ The IPv4 Subnet of your community mesh network in CIDR notation, e.g. ::
- prefix4 = '10.111.111.0/18'
+ prefix4 = '10.111.111.0/18'
- Required if ``next_node.ip4`` is set.
+ Required if ``next_node.ip4`` is set.
prefix6
- The IPv6 subnet of your community mesh network, e.g.
- ::
+ The IPv6 subnet of your community mesh network, e.g. ::
- prefix6 = 'fdca::ffee:babe:1::/64'
+ prefix6 = 'fdca::ffee:babe:1::/64'
node_prefix6
- The ipv6 prefix from which the unique IP-addresses for nodes are selected
- in babel-based networks. This may overlap with prefix6. e.g.
- ::
+ The ipv6 prefix from which the unique IP-addresses for nodes are selected
+ in babel-based networks. This may overlap with prefix6. e.g. ::
- node_prefix6 = 'fdca::ffee:babe:2::/64'
+ node_prefix6 = 'fdca::ffee:babe:2::/64'
node_client_prefix6
- The ipv6 prefix from which the client-specific IP-address is calculated that
- is assigned to each node by l3roamd to allow efficient communication when
- roaming. This is exclusively useful when running a routing mesh protocol
- like babel. e.g.
- ::
+ The ipv6 prefix from which the client-specific IP-address is calculated that
+ is assigned to each node by l3roamd to allow efficient communication when
+ roaming. This is exclusively useful when running a routing mesh protocol
+ like babel. e.g. ::
- node_client_prefix6 = 'fdca::ffee:babe:3::/64'
+ node_client_prefix6 = 'fdca::ffee:babe:3::/64'
timezone
- The timezone of your community live in, e.g.
- ::
+ The timezone of your community live in, e.g. ::
- -- Europe/Berlin
- timezone = 'CET-1CEST,M3.5.0,M10.5.0/3'
+ -- Europe/Berlin
+ timezone = 'CET-1CEST,M3.5.0,M10.5.0/3'
ntp_servers
- List of NTP servers available in your community or used by your community, e.g.:
- ::
+ List of NTP servers available in your community or used by your community, e.g.::
- ntp_servers = {'1.ntp.services.ffac','2.ntp.services.ffac'}
+ ntp_servers = {'1.ntp.services.ffac','2.ntp.services.ffac'}
- This NTP servers must be reachable via IPv6 from the nodes. If you don't want to set an IPv6 address
- explicitly, but use a hostname (which is recommended), see also the :ref:`FAQ <faq-dns>`.
+ This NTP servers must be reachable via IPv6 from the nodes. If you don't want to set an IPv6 address
+ explicitly, but use a hostname (which is recommended), see also the :ref:`FAQ <faq-dns>`.
opkg \: optional
- ``opkg`` package manager configuration.
+ ``opkg`` package manager configuration.
- There are two optional fields in the ``opkg`` section:
+ There are two optional fields in the ``opkg`` section:
- - ``openwrt`` overrides the default OpenWrt repository URL. The default URL would
- correspond to ``http://downloads.openwrt.org/snapshots/packages/%A``
- and usually doesn't need to be changed when nodes are expected to have IPv6
- internet connectivity.
- - ``extra`` specifies a table of additional repositories (with arbitrary keys)
+ - ``openwrt`` overrides the default OpenWrt repository URL. The default URL would
+ correspond to ``http://downloads.openwrt.org/snapshots/packages/%A``
+ and usually doesn't need to be changed when nodes are expected to have IPv6
+ internet connectivity.
+ - ``extra`` specifies a table of additional repositories (with arbitrary keys)
- ::
+ ::
- opkg = {
- openwrt = 'http://opkg.services.ffac/openwrt/snapshots/packages/%A',
- extra = {
- gluon = 'http://opkg.services.ffac/modules/gluon-%GS-%GR/%S',
- },
- }
+ opkg = {
+ openwrt = 'http://opkg.services.ffac/openwrt/snapshots/packages/%A',
+ extra = {
+ gluon = 'http://opkg.services.ffac/modules/gluon-%GS-%GR/%S',
+ },
+ }
- There are various patterns which can be used in the URLs:
+ There are various patterns which can be used in the URLs:
- - ``%d`` is replaced by the OpenWrt distribution name ("openwrt")
- - ``%v`` is replaced by the OpenWrt version number (e.g. "17.01")
- - ``%S`` is replaced by the target board (e.g. "ath79/generic")
- - ``%A`` is replaced by the target architecture (e.g. "mips_24kc")
- - ``%GS`` is replaced by the Gluon site code (as specified in ``site.conf``)
- - ``%GV`` is replaced by the Gluon version
- - ``%GR`` is replaced by the Gluon release (as specified in ``site.mk``)
+ - ``%d`` is replaced by the OpenWrt distribution name ("openwrt")
+ - ``%v`` is replaced by the OpenWrt version number (e.g. "17.01")
+ - ``%S`` is replaced by the target board (e.g. "ath79/generic")
+ - ``%A`` is replaced by the target architecture (e.g. "mips_24kc")
+ - ``%GS`` is replaced by the Gluon site code (as specified in ``site.conf``)
+ - ``%GV`` is replaced by the Gluon version
+ - ``%GR`` is replaced by the Gluon release (as specified in ``site.mk``)
regdom \: optional
- The wireless regulatory domain responsible for your area, e.g.:
- ::
+ The wireless regulatory domain responsible for your area, e.g. ::
- regdom = 'DE'
+ regdom = 'DE'
- Setting ``regdom`` is mandatory if ``wifi24`` or ``wifi5`` is defined.
+ Setting ``regdom`` is mandatory if ``wifi24`` or ``wifi5`` is defined.
wifi24 \: optional
- WLAN configuration for 2.4 GHz devices.
- ``channel`` must be set to a valid wireless channel for your radio.
- ``beacon_interval`` can be specified to set a custom beacon interval in
- time units (TU). A time unit is equivalent to 1024 µs.
- If not set, the default value of 100 TU (=102.4 ms) is used.
-
-
- There are currently two interface types available. You may choose to
- configure any subset of them:
-
- - ``ap`` creates a master interface where clients may connect
- - ``mesh`` creates an 802.11s mesh interface with forwarding disabled
-
- Each interface may be disabled by setting ``disabled`` to ``true``.
- This will only affect new installations.
- Upgrades will not change the disabled state.
-
- ``ap`` holds the client network configuration.
- To create an unencrypted client network, a string named ``ssid`` which sets the
- interface's ESSID is required. This is the wireless network clients connect to.
- For an OWE secured network, the ``owe_ssid`` string has to be set. It sets the
- SSID for the opportunistically encrypted wireless network, to which compatible
- clients can connect to.
- For OWE to work, the ``wireless-encryption-wpa3`` has to be enabled (usually by
- adding it to ``GLUON_FEATURES_standard``) in your ``site.mk``.
- To utilize the OWE transition mode, ``owe_transition_mode`` has to be set to true.
- When ``owe_transition_mode`` is enabled, the OWE secured SSID will be hidden.
- Compatible devices will automatically connect to the OWE secured SSID when selecting
- the open SSID.
- Note that for the transition mode to work, both ``ssid`` as well as ``owe_ssid``
- have to be enabled. Also, some devices with a broken implementation might not be able
- to connect with a transition-mode enabled network.
-
- ``mesh`` requires a single parameter, a string, named ``id`` which sets the
- mesh id, also visible as an open WiFi in some network managers. 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.
-
- ``mesh`` also accepts an optional ``mcast_rate`` (kbit/s) parameter for
- setting the multicast bitrate. Increasing the default value of 1000 to something
- like 12000 is recommended.
- ::
-
- wifi24 = {
- channel = 11,
- ap = {
- ssid = 'alpha-centauri.freifunk.net',
- owe_ssid = 'owe.alpha-centauri.freifunk.net',
- owe_transition_mode = true,
- },
- mesh = {
- id = 'ueH3uXjdp',
- mcast_rate = 12000,
- },
- },
+ WLAN configuration for 2.4 GHz devices.
+ ``channel`` must be set to a valid wireless channel for your radio.
+ ``beacon_interval`` can be specified to set a custom beacon interval in
+ time units (TU). A time unit is equivalent to 1024 µs.
+ If not set, the default value of 100 TU (=102.4 ms) is used.
+
+ There are currently two interface types available. You may choose to
+ configure any subset of them:
+
+ - ``ap`` creates a master interface where clients may connect
+ - ``mesh`` creates an 802.11s mesh interface with forwarding disabled
+
+ Each interface may be disabled by setting ``disabled`` to ``true``.
+ This will only affect new installations.
+ Upgrades will not change the disabled state.
+
+ ``ap`` holds the client network configuration.
+ To create an unencrypted client network, a string named ``ssid`` which sets the
+ interface's ESSID is required. This is the wireless network clients connect to.
+ For an OWE secured network, the ``owe_ssid`` string has to be set. It sets the
+ SSID for the opportunistically encrypted wireless network, to which compatible
+ clients can connect to.
+ For OWE to work, the ``wireless-encryption-wpa3`` has to be enabled (usually by
+ adding it to ``GLUON_FEATURES_standard``) in your ``site.mk``.
+ To utilize the OWE transition mode, ``owe_transition_mode`` has to be set to true.
+ When ``owe_transition_mode`` is enabled, the OWE secured SSID will be hidden.
+ Compatible devices will automatically connect to the OWE secured SSID when selecting
+ the open SSID.
+ Note that for the transition mode to work, both ``ssid`` as well as ``owe_ssid``
+ have to be enabled. Also, some devices with a broken implementation might not be able
+ to connect with a transition-mode enabled network.
+
+ ``mesh`` requires a single parameter, a string, named ``id`` which sets the
+ mesh id, also visible as an open WiFi in some network managers. 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.
+
+ ``mesh`` also accepts an optional ``mcast_rate`` (kbit/s) parameter for
+ setting the multicast bitrate. Increasing the default value of 1000 to something
+ like 12000 is recommended.
+
+ ::
+
+ wifi24 = {
+ channel = 11,
+ ap = {
+ ssid = 'alpha-centauri.freifunk.net',
+ owe_ssid = 'owe.alpha-centauri.freifunk.net',
+ owe_transition_mode = true,
+ },
+ mesh = {
+ id = 'ueH3uXjdp',
+ mcast_rate = 12000,
+ },
+ },
.. _user-site-wifi5:
wifi5 \: optional
- Same as `wifi24` but for the 5 GHz radio.
+ Same as `wifi24` but for the 5 GHz radio.
- Additionally a range of channels that are safe to use outsides on the 5 GHz band can
- be set up through ``outdoor_chanlist``, which allows for a space-separated list of
- channels and channel ranges, separated by a hyphen.
- When set this offers the outdoor mode flag for 5 GHz radios in the config mode which
- reconfigures the AP to select its channel from outdoor chanlist, while respecting
- regulatory specifications, and disables mesh on that radio.
- The ``outdoors`` option in turn allows to configure when outdoor mode will be enabled.
- When set to ``true`` all 5 GHz radios will use outdoor channels, while on ``false``
- the outdoor mode will be completely disabled. The default setting is ``'preset'``,
- which will enable outdoor mode automatically on outdoor-capable devices.
+ Additionally a range of channels that are safe to use outsides on the 5 GHz band can
+ be set up through ``outdoor_chanlist``, which allows for a space-separated list of
+ channels and channel ranges, separated by a hyphen.
+ When set this offers the outdoor mode flag for 5 GHz radios in the config mode which
+ reconfigures the AP to select its channel from outdoor chanlist, while respecting
+ regulatory specifications, and disables mesh on that radio.
+ The ``outdoors`` option in turn allows to configure when outdoor mode will be enabled.
+ When set to ``true`` all 5 GHz radios will use outdoor channels, while on ``false``
+ the outdoor mode will be completely disabled. The default setting is ``'preset'``,
+ which will enable outdoor mode automatically on outdoor-capable devices.
- It can be beneficial to look up the WLAN channels that are used by `weather radars`_
- when constructing ``outdoor_chanlist`` to try and minimize the impact of DFS events.
+ It can be beneficial to look up the WLAN channels that are used by `weather radars`_
+ when constructing ``outdoor_chanlist`` to try and minimize the impact of DFS events.
- .. _weather radars: https://homepage.univie.ac.at/albert.rafetseder/RADARs/help.html
+ .. _weather radars: https://homepage.univie.ac.at/albert.rafetseder/RADARs/help.html
- ::
+ ::
- wifi5 = {
- channel = 44,
- outdoor_chanlist = "100-140",
+ wifi5 = {
+ channel = 44,
+ outdoor_chanlist = "100-140",
- [...]
- },
+ [...]
+ },
next_node \: package
- Configuration of the local node feature of Gluon
- ::
-
- next_node = {
- name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
- ip4 = '10.23.42.1',
- ip6 = 'fdca:ffee:babe:1::1',
- mac = '16:41:95:40:f7:dc'
- }
-
- All values of this section are optional. If the IPv4 or IPv6 address is
- omitted, there will be no IPv4 or IPv6 anycast address. The MAC address
- defaults to ``16:41:95:40:f7:dc``; this value usually doesn't need to be
- changed, but it can be adjusted to match existing deployments that use a
- different value.
-
- When the nodes' next-node address is used as a DNS resolver by clients
- (by passing it via DHCP or router advertisements), it may be useful to
- allow resolving a next-node hostname without referring to an upstream DNS
- server (e.g. to allow reaching the node using such a hostname via HTTP or SSH
- in isolated mesh segments). This is possible by providing one or more names
- in the ``name`` field.
+ Configuration of the local node feature of Gluon
+
+ ::
+
+ next_node = {
+ name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
+ ip4 = '10.23.42.1',
+ ip6 = 'fdca:ffee:babe:1::1',
+ mac = '16:41:95:40:f7:dc'
+ }
+
+ All values of this section are optional. If the IPv4 or IPv6 address is
+ omitted, there will be no IPv4 or IPv6 anycast address. The MAC address
+ defaults to ``16:41:95:40:f7:dc``; this value usually doesn't need to be
+ changed, but it can be adjusted to match existing deployments that use a
+ different value.
+
+ When the nodes' next-node address is used as a DNS resolver by clients
+ (by passing it via DHCP or router advertisements), it may be useful to
+ allow resolving a next-node hostname without referring to an upstream DNS
+ server (e.g. to allow reaching the node using such a hostname via HTTP or SSH
+ in isolated mesh segments). This is possible by providing one or more names
+ in the ``name`` field.
.. _user-site-mesh:
mesh
- Configuration of general mesh functionality.
-
- To avoid inter-mesh links, Gluon can encapsulate the mesh protocol in VXLAN
- for Mesh-on-LAN/WAN. It is recommended to set *mesh.vxlan* to ``true`` to
- enable VXLAN in new setups. Setting it to ``false`` disables this
- encapsulation to allow meshing with other nodes that don't support VXLAN
- (Gluon 2017.1.x and older). In multi-domain setups, *mesh.vxlan* is optional
- and defaults to ``true``.
-
- Gluon generally segments layer-2 meshes so that each node becomes IGMP/MLD
- querier for its own local clients. This is necessary for reliable multicast
- snooping. The segmentation is realized by preventing IGMP/MLD queries from
- passing through the mesh. See also
- :ref:`gluon-mesh-batman-adv <igmp-mld-domain-segmentation>` for details.
-
- By default, not only queries are filtered, but also membership report and
- leave packets, as they add to the background noise of the mesh. As a
- consequence, snooping switches outside the mesh that are connected to a
- Gluon node need to be configured to forward all multicast traffic towards
- the mesh; this is usually not a problem, as such setups are unusual. If
- you run a special-purpose mesh that requires membership reports to be
- working, this filtering can be disabled by setting the
- optional *filter_membership_reports* value to ``false``.
-
- In addition, options specific to the batman-adv routing protocol can be set
- in the *batman_adv* section:
-
- The mandatory value *routing_algo* selects the batman-adv protocol variant.
- The following values are supported:
-
- - ``BATMAN_IV``
- - ``BATMAN_V``
-
- The optional value *gw_sel_class* sets the gateway selection class, the
- default is ``20`` for B.A.T.M.A.N. IV and ``5000`` kbit/s for B.A.T.M.A.N. V.
-
- - **B.A.T.M.A.N. IV:** with the value ``20`` the gateway is selected based
- on the link quality (TQ) only; with class ``1`` it is calculated from
- both, the TQ and the announced bandwidth.
- - **B.A.T.M.A.N. V:** with the value ``1500`` the gateway is selected if the
- throughput is at least 1500 kbit/s faster than the throughput of the
- currently selected gateway.
-
- For details on determining the threshold, when to switch to a new gateway,
- see `batctl manpage`_, section "gw_mode".
-
- .. _batctl manpage: https://www.open-mesh.org/projects/batman-adv/wiki/Gateways
-
- ::
-
- mesh = {
- vxlan = true,
- filter_membership_reports = false,
- batman_adv = {
- routing_algo = 'BATMAN_IV',
- gw_sel_class = 1,
- },
- }
+ Configuration of general mesh functionality.
+
+ To avoid inter-mesh links, Gluon can encapsulate the mesh protocol in VXLAN
+ for Mesh-on-LAN/WAN. It is recommended to set *mesh.vxlan* to ``true`` to
+ enable VXLAN in new setups. Setting it to ``false`` disables this
+ encapsulation to allow meshing with other nodes that don't support VXLAN
+ (Gluon 2017.1.x and older). In multi-domain setups, *mesh.vxlan* is optional
+ and defaults to ``true``.
+
+ Gluon generally segments layer-2 meshes so that each node becomes IGMP/MLD
+ querier for its own local clients. This is necessary for reliable multicast
+ snooping. The segmentation is realized by preventing IGMP/MLD queries from
+ passing through the mesh. See also
+ :ref:`gluon-mesh-batman-adv <igmp-mld-domain-segmentation>` for details.
+
+ By default, not only queries are filtered, but also membership report and
+ leave packets, as they add to the background noise of the mesh. As a
+ consequence, snooping switches outside the mesh that are connected to a
+ Gluon node need to be configured to forward all multicast traffic towards
+ the mesh; this is usually not a problem, as such setups are unusual. If
+ you run a special-purpose mesh that requires membership reports to be
+ working, this filtering can be disabled by setting the
+ optional *filter_membership_reports* value to ``false``.
+
+ In addition, options specific to the batman-adv routing protocol can be set
+ in the *batman_adv* section:
+
+ The mandatory value *routing_algo* selects the batman-adv protocol variant.
+ The following values are supported:
+
+ - ``BATMAN_IV``
+ - ``BATMAN_V``
+
+ The optional value *gw_sel_class* sets the gateway selection class, the
+ default is ``20`` for B.A.T.M.A.N. IV and ``5000`` kbit/s for B.A.T.M.A.N. V.
+
+ - **B.A.T.M.A.N. IV:** with the value ``20`` the gateway is selected based
+ on the link quality (TQ) only; with class ``1`` it is calculated from
+ both, the TQ and the announced bandwidth.
+ - **B.A.T.M.A.N. V:** with the value ``1500`` the gateway is selected if the
+ throughput is at least 1500 kbit/s faster than the throughput of the
+ currently selected gateway.
+
+ For details on determining the threshold, when to switch to a new gateway,
+ see `batctl manpage`_, section "gw_mode".
+
+ .. _batctl manpage: https://www.open-mesh.org/projects/batman-adv/wiki/Gateways
+
+ ::
+
+ mesh = {
+ vxlan = true,
+ filter_membership_reports = false,
+ batman_adv = {
+ routing_algo = 'BATMAN_IV',
+ gw_sel_class = 1,
+ },
+ }
mesh_vpn
- Remote server setup for the mesh VPN.
-
- The `enabled` option can be set to true to enable the VPN by default. `mtu`
- defines the MTU of the VPN interface, determining a proper MTU value is described
- in the :ref:`FAQ <faq-mtu>`.
-
- By default the public key of a node's VPN daemon is not added to announced respondd
- data; this prevents malicious ISPs from correlating VPN sessions with specific mesh
- nodes via public respondd data. If this is of no concern in your threat model,
- this behaviour can be disabled (and thus announcing the public key be enabled) by
- setting `pubkey_privacy` to `false`. At the moment, this option only affects fastd.
-
- The `fastd` section configures settings specific to the *fastd* VPN
- implementation.
-
- If `configurable` is set to `false` or unset, the method list will be replaced on updates
- with the list from the site configuration. Setting `configurable` to `true` will allow the user to
- add the method ``null`` to the beginning of the method list or remove ``null`` from it,
- and make this change survive updates. Setting `configurable` is necessary for the
- package `gluon-web-mesh-vpn-fastd`, which adds a UI for this configuration.
-
- In any case, the ``null`` method should always be the first method in the list
- if it is supported at all. You should only set `configurable` to `true` if the
- configured peers support both the ``null`` method and methods with encryption.
-
- You can set syslog_level from verbose (default) to warn to reduce syslog output.
-
- fastd allows to configure a tree of peer groups and peers. By default, the
- list of groups and peers configured in the *fastd* UCI config is completely
- replaced by the list from site.conf on upgrades. To allow custom modifications
- to the peer list, removal and modification of peers can be prevented by
- setting the *preserve* option of a peer to ``1`` in UCI.
-
- The `tunneldigger` section is used to define the *tunneldigger* broker list.
-
- **Note:** It doesn't make sense to include both `fastd` and `tunneldigger`
- sections in the same configuration file, as only one of the packages *gluon-mesh-vpn-fastd*
- and *gluon-mesh-vpn-tunneldigger* should be installed with the current
- implementation.
-
- **Note:** It may be interesting to include the package *gluon-iptables-clamp-mss-to-pmtu*
- in the build when using *gluon-mesh-babel* to work around ICMP blackholes on the internet.
-
- ::
-
- mesh_vpn = {
- -- enabled = true,
- mtu = 1312,
- -- pubkey_privacy = true,
-
- fastd = {
- methods = {'salsa2012+umac'},
- -- configurable = true,
- -- syslog_level = 'warn',
- groups = {
- backbone = {
- -- Limit number of connected peers from this group
- limit = 1,
- peers = {
- peer1 = {
- key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
- -- Having multiple domains prevents SPOF in freifunk.net
- remotes = {
- 'ipv4 "vpn1.alpha-centauri.freifunk.net" port 10000',
- 'ipv4 "vpn1.alpha-centauri-freifunk.de" port 10000',
- },
+ Remote server setup for the mesh VPN.
+
+ The `enabled` option can be set to true to enable the VPN by default. `mtu`
+ defines the MTU of the VPN interface, determining a proper MTU value is described
+ in the :ref:`FAQ <faq-mtu>`.
+
+ By default the public key of a node's VPN daemon is not added to announced respondd
+ data; this prevents malicious ISPs from correlating VPN sessions with specific mesh
+ nodes via public respondd data. If this is of no concern in your threat model,
+ this behaviour can be disabled (and thus announcing the public key be enabled) by
+ setting `pubkey_privacy` to `false`. At the moment, this option only affects fastd.
+
+ The `fastd` section configures settings specific to the *fastd* VPN
+ implementation.
+
+ If `configurable` is set to `false` or unset, the method list will be replaced on updates
+ with the list from the site configuration. Setting `configurable` to `true` will allow the user to
+ add the method ``null`` to the beginning of the method list or remove ``null`` from it,
+ and make this change survive updates. Setting `configurable` is necessary for the
+ package `gluon-web-mesh-vpn-fastd`, which adds a UI for this configuration.
+
+ In any case, the ``null`` method should always be the first method in the list
+ if it is supported at all. You should only set `configurable` to `true` if the
+ configured peers support both the ``null`` method and methods with encryption.
+
+ You can set syslog_level from verbose (default) to warn to reduce syslog output.
+
+ fastd allows to configure a tree of peer groups and peers. By default, the
+ list of groups and peers configured in the *fastd* UCI config is completely
+ replaced by the list from site.conf on upgrades. To allow custom modifications
+ to the peer list, removal and modification of peers can be prevented by
+ setting the *preserve* option of a peer to ``1`` in UCI.
+
+ The `tunneldigger` section is used to define the *tunneldigger* broker list.
+
+ **Note:** It doesn't make sense to include both `fastd` and `tunneldigger`
+ sections in the same configuration file, as only one of the packages *gluon-mesh-vpn-fastd*
+ and *gluon-mesh-vpn-tunneldigger* should be installed with the current
+ implementation.
+
+ **Note:** It may be interesting to include the package *gluon-iptables-clamp-mss-to-pmtu*
+ in the build when using *gluon-mesh-babel* to work around ICMP blackholes on the internet.
+
+ ::
+
+ mesh_vpn = {
+ -- enabled = true,
+ mtu = 1312,
+ -- pubkey_privacy = true,
+
+ fastd = {
+ methods = {'salsa2012+umac'},
+ -- configurable = true,
+ -- syslog_level = 'warn',
+ groups = {
+ backbone = {
+ -- Limit number of connected peers from this group
+ limit = 1,
+ peers = {
+ peer1 = {
+ key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+ -- Having multiple domains prevents SPOF in freifunk.net
+ remotes = {
+ 'ipv4 "vpn1.alpha-centauri.freifunk.net" port 10000',
+ 'ipv4 "vpn1.alpha-centauri-freifunk.de" port 10000',
},
- peer2 = {
- key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
- -- You can also omit the ipv4 to allow both connection via ipv4 and ipv6
- remotes = {'"vpn2.alpha-centauri.freifunk.net" port 10000'},
- },
- peer3 = {
- key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
- -- In addition to domains you can also add ip addresses, which provides
- -- resilience in case of dns outages
- remotes = {
- '"vpn3.alpha-centauri.freifunk.net" port 10000',
- '[2001:db8::3:1]:10000',
- '192.0.2.3:10000',
- },
+ },
+ peer2 = {
+ key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+ -- You can also omit the ipv4 to allow both connection via ipv4 and ipv6
+ remotes = {'"vpn2.alpha-centauri.freifunk.net" port 10000'},
+ },
+ peer3 = {
+ key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
+ -- In addition to domains you can also add ip addresses, which provides
+ -- resilience in case of dns outages
+ remotes = {
+ '"vpn3.alpha-centauri.freifunk.net" port 10000',
+ '[2001:db8::3:1]:10000',
+ '192.0.2.3:10000',
},
},
- -- Optional: nested peer groups
- -- groups = {
- -- lowend_backbone = {
- -- limit = 1,
- -- peers = ...
- -- },
- -- },
},
- -- Optional: additional peer groups, possibly with other limits
- -- peertopeer = {
- -- limit = 10,
- -- peers = { ... },
+ -- Optional: nested peer groups
+ -- groups = {
+ -- lowend_backbone = {
+ -- limit = 1,
+ -- peers = ...
+ -- },
-- },
},
+ -- Optional: additional peer groups, possibly with other limits
+ -- peertopeer = {
+ -- limit = 10,
+ -- peers = { ... },
+ -- },
},
+ },
- tunneldigger = {
- brokers = {'vpn1.alpha-centauri.freifunk.net'}
- },
+ tunneldigger = {
+ brokers = {'vpn1.alpha-centauri.freifunk.net'}
+ },
- bandwidth_limit = {
- -- The bandwidth limit can be enabled by default here.
- enabled = false,
+ bandwidth_limit = {
+ -- The bandwidth limit can be enabled by default here.
+ enabled = false,
- -- Default upload limit (kbit/s).
- egress = 200,
+ -- Default upload limit (kbit/s).
+ egress = 200,
- -- Default download limit (kbit/s).
- ingress = 3000,
- },
- }
+ -- Default download limit (kbit/s).
+ ingress = 3000,
+ },
+ }
mesh_on_wan \: optional
- Enables the mesh on the WAN port (``true`` or ``false``).
- ::
+ Enables the mesh on the WAN port (``true`` or ``false``).
+ ::
- mesh_on_wan = true,
+ mesh_on_wan = true,
mesh_on_lan \: optional
- Enables the mesh on the LAN port (``true`` or ``false``).
- ::
+ Enables the mesh on the LAN port (``true`` or ``false``).
+ ::
- mesh_on_lan = true,
+ mesh_on_lan = true,
poe_passthrough \: optional
- Enable PoE passthrough by default on hardware with such a feature.
+ Enable PoE passthrough by default on hardware with such a feature.
autoupdater \: package
- Configuration for the autoupdater feature of Gluon.
-
- Specifying a default branch in *site.conf* is optional. See
- :doc:`../features/autoupdater` for information how to change the behaviour
- of the autoupdater during image build.
-
- The mirrors are checked in random order until the manifest could be downloaded
- successfully or all mirrors have been tried.
- ::
-
- autoupdater = {
- branch = 'stable', -- optional
- branches = {
- stable = {
- name = 'stable',
- mirrors = {
- 'http://[fdca:ffee:babe:1::fec1]/firmware/stable/sysupgrade/',
- 'http://autoupdate.alpha-centauri.freifunk.net/firmware/stable/sysupgrade/',
- },
- -- Number of good signatures required
- good_signatures = 2,
- pubkeys = {
- 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someguy
- 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someother
- }
+ Configuration for the autoupdater feature of Gluon.
+
+ Specifying a default branch in *site.conf* is optional. See
+ :doc:`../features/autoupdater` for information how to change the behaviour
+ of the autoupdater during image build.
+
+ The mirrors are checked in random order until the manifest could be downloaded
+ successfully or all mirrors have been tried.
+ ::
+
+ autoupdater = {
+ branch = 'stable', -- optional
+ branches = {
+ stable = {
+ name = 'stable',
+ mirrors = {
+ 'http://[fdca:ffee:babe:1::fec1]/firmware/stable/sysupgrade/',
+ 'http://autoupdate.alpha-centauri.freifunk.net/firmware/stable/sysupgrade/',
+ },
+ -- Number of good signatures required
+ good_signatures = 2,
+ pubkeys = {
+ 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someguy
+ 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someother
}
}
}
+ }
- All configured mirrors must be reachable from the nodes via IPv6. If you don't want to set an IPv6 address
- explicitly, but use a hostname (which is recommended), see also the :ref:`FAQ <faq-dns>`.
+ All configured mirrors must be reachable from the nodes via IPv6. If you don't want to set an IPv6 address
+ explicitly, but use a hostname (which is recommended), see also the :ref:`FAQ <faq-dns>`.
.. _user-site-config_mode:
config_mode \: optional
- Additional configuration for the configuration web interface. All values are
- optional.
-
- When no hostname is specified, a default hostname based on the *hostname_prefix*
- and the node's primary MAC address is assigned. Manually setting a hostname
- can be enforced by setting *hostname.optional* to *false*.
-
- To not prefill the hostname-field in config-mode with the default hostname,
- set *hostname.prefill* to *false*.
-
- By default, no altitude field is shown by the *gluon-config-mode-geo-location*
- package. Set *geo_location.show_altitude* to *true* if you want the altitude
- field to be visible.
-
- The *geo_location.osm* section is only relevant when the *gluon-config-mode-geo-location-osm*
- package is used. The *center.lon* and *center.lat* values are mandatory in this case and
- define the default center of the map when no position has been picked yet. The *zoom* level
- defaults to 12 in this case.
-
- *openlayers_url* allows to override the base URL of the
- *build/ol.js* and *css/ol.css* files (the default is
- ``https://cdn.rawgit.com/openlayers/openlayers.github.io/master/en/v5.2.0``).
- It is also possible to replace the default tile layer (which is OpenStreetMap)
- with a custom one using the *tile_layer* section. Only XYZ layers are supported
- at this point.
-
- The remote login page only shows SSH key configuration by default. A
- password form can be displayed by setting *remote_login.show_password_form*
- to true; in this case, *remote_login.min_password_length* defines the
- minimum password length.
- ::
-
- config_mode = {
- hostname = {
- optional = false,
- prefill = true,
- },
- geo_location = {
- show_altitude = true,
- osm = {
- center = {
- lat = 52.951947558,
- lon = 8.744238281,
- },
- zoom = 13,
- -- openlayers_url = 'http://ffac.example.org/openlayer',
- -- tile_layer = {
- -- type = 'XYZ',
- -- url = 'https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png',
- -- attributions = '© <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors.',
- -- },
- },
- },
- remote_login = {
- show_password_form = true,
- min_password_length = 10,
+ Additional configuration for the configuration web interface. All values are
+ optional.
+
+ When no hostname is specified, a default hostname based on the *hostname_prefix*
+ and the node's primary MAC address is assigned. Manually setting a hostname
+ can be enforced by setting *hostname.optional* to *false*.
+
+ To not prefill the hostname-field in config-mode with the default hostname,
+ set *hostname.prefill* to *false*.
+
+ By default, no altitude field is shown by the *gluon-config-mode-geo-location*
+ package. Set *geo_location.show_altitude* to *true* if you want the altitude
+ field to be visible.
+
+ The *geo_location.osm* section is only relevant when the *gluon-config-mode-geo-location-osm*
+ package is used. The *center.lon* and *center.lat* values are mandatory in this case and
+ define the default center of the map when no position has been picked yet. The *zoom* level
+ defaults to 12 in this case.
+
+ *openlayers_url* allows to override the base URL of the
+ *build/ol.js* and *css/ol.css* files (the default is
+ ``https://cdn.rawgit.com/openlayers/openlayers.github.io/master/en/v5.2.0``).
+ It is also possible to replace the default tile layer (which is OpenStreetMap)
+ with a custom one using the *tile_layer* section. Only XYZ layers are supported
+ at this point.
+
+ The remote login page only shows SSH key configuration by default. A
+ password form can be displayed by setting *remote_login.show_password_form*
+ to true; in this case, *remote_login.min_password_length* defines the
+ minimum password length.
+ ::
+
+ config_mode = {
+ hostname = {
+ optional = false,
+ prefill = true,
+ },
+ geo_location = {
+ show_altitude = true,
+ osm = {
+ center = {
+ lat = 52.951947558,
+ lon = 8.744238281,
},
+ zoom = 13,
+ -- openlayers_url = 'http://ffac.example.org/openlayer',
+ -- tile_layer = {
+ -- type = 'XYZ',
+ -- url = 'https://{a-c}.tile.openstreetmap.org/{z}/{x}/{y}.png',
+ -- attributions = '© <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors.',
+ -- },
},
+ },
+ remote_login = {
+ show_password_form = true,
+ min_password_length = 10,
+ },
+ },
roles \: optional
- Optional role definitions. Nodes will announce their role inside the mesh.
- This will allow in the backend to distinguish between normal, backbone and
- service nodes or even gateways (if they advertise that role). It is up to
- the community which roles to define. See the section below as an example.
- ``default`` takes the default role which is set initially. This value should be
- part of ``list``. If you want node owners to change the role via config mode add
- the package ``gluon-web-node-role`` to ``site.mk``.
-
- The strings to display in the web interface are configured per language in the
- ``i18n/en.po``, ``i18n/de.po``, etc. files of the site repository using message IDs like
- ``gluon-web-node-role:role:node`` and ``gluon-web-node-role:role:backbone``.
- ::
-
- roles = {
- default = 'node',
- list = {
- 'node',
- 'test',
- 'backbone',
- 'service',
- },
+ Optional role definitions. Nodes will announce their role inside the mesh.
+ This will allow in the backend to distinguish between normal, backbone and
+ service nodes or even gateways (if they advertise that role). It is up to
+ the community which roles to define. See the section below as an example.
+ ``default`` takes the default role which is set initially. This value should be
+ part of ``list``. If you want node owners to change the role via config mode add
+ the package ``gluon-web-node-role`` to ``site.mk``.
+
+ The strings to display in the web interface are configured per language in the
+ ``i18n/en.po``, ``i18n/de.po``, etc. files of the site repository using message IDs like
+ ``gluon-web-node-role:role:node`` and ``gluon-web-node-role:role:backbone``.
+ ::
+
+ roles = {
+ default = 'node',
+ list = {
+ 'node',
+ 'test',
+ 'backbone',
+ 'service',
},
+ },
setup_mode \: package
- Allows skipping setup mode (config mode) at first boot when attribute
- ``skip`` is set to ``true``. This is optional and may be left out.
- ::
+ Allows skipping setup mode (config mode) at first boot when attribute
+ ``skip`` is set to ``true``. This is optional and may be left out.
+ ::
- setup_mode = {
- skip = true,
- },
+ setup_mode = {
+ skip = true,
+ },
.. _user-site-build-configuration:
@@ -559,59 +552,59 @@ The ``site.mk`` is a Makefile which defines various values
involved in the build process of Gluon.
GLUON_DEPRECATED
- Controls whether images for deprecated devices should be built. The following
- values are supported:
+ Controls whether images for deprecated devices should be built. The following
+ values are supported:
- - ``0``: Do not build any images for deprecated devices.
- - ``upgrade``: Only build sysupgrade images for deprecated devices.
- - ``full``: Build both sysupgrade and factory images for deprecated devices.
+ - ``0``: Do not build any images for deprecated devices.
+ - ``upgrade``: Only build sysupgrade images for deprecated devices.
+ - ``full``: Build both sysupgrade and factory images for deprecated devices.
- Usually, devices are deprecated because their flash size is insufficient to
- support future Gluon versions. The recommended setting is ``0`` for new sites,
- and ``upgrade`` for existing configurations (where upgrades for existing
- deployments of low-flash devices are required).
+ Usually, devices are deprecated because their flash size is insufficient to
+ support future Gluon versions. The recommended setting is ``0`` for new sites,
+ and ``upgrade`` for existing configurations (where upgrades for existing
+ deployments of low-flash devices are required).
GLUON_FEATURES
- Defines a list of features to include. Depending on the device, the feature list
- defined from this value is combined with the feature list for either the standard
- or the tiny device-class. The resulting feature list is used to generate the default
- package set.
+ Defines a list of features to include. Depending on the device, the feature list
+ defined from this value is combined with the feature list for either the standard
+ or the tiny device-class. The resulting feature list is used to generate the default
+ package set.
GLUON_FEATURES_standard
- Defines a list of additional features to include or exclude for devices of
- the standard device-class.
+ Defines a list of additional features to include or exclude for devices of
+ the standard device-class.
GLUON_FEATURES_tiny
- Defines a list of additional features to include or exclude for devices of
- the tiny device-class.
+ Defines a list of additional features to include or exclude for devices of
+ the tiny device-class.
GLUON_SITE_PACKAGES
- Defines a list of packages which should be installed in addition to the
- default package set. It is also possible to remove packages from the
- default set by prepending a minus sign to the package name.
+ Defines a list of packages which should be installed in addition to the
+ default package set. It is also possible to remove packages from the
+ default set by prepending a minus sign to the package name.
GLUON_SITE_PACKAGES_standard
- Defines a list of additional packages to include or exclude for devices of
- the standard device-class.
+ Defines a list of additional packages to include or exclude for devices of
+ the standard device-class.
GLUON_SITE_PACKAGES_tiny
- Defines a list of additional packages to include or exclude for devices of
- the tiny device-class.
+ Defines a list of additional packages to include or exclude for devices of
+ the tiny device-class.
GLUON_RELEASE
- The current release version Gluon should use.
+ The current release version Gluon should use.
GLUON_PRIORITY
- The default priority for the generated manifests (see the autoupdater documentation
- for more information).
+ The default priority for the generated manifests (see the autoupdater documentation
+ for more information).
GLUON_REGION
- Region code to build into images where necessary. Valid values are the empty string,
- ``us`` and ``eu``.
+ Region code to build into images where necessary. Valid values are the empty string,
+ ``us`` and ``eu``.
GLUON_LANGS
- List of languages (as two-letter-codes) to be included in the web interface. Should always contain
- ``en``.
+ List of languages (as two-letter-codes) to be included in the web interface. Should always contain
+ ``en``.
.. _user-site-feature-flags:
@@ -689,31 +682,31 @@ The community-defined texts in the config mode are configured in PO files in the
of the site configuration. The message IDs currently defined are:
gluon-config-mode:welcome
- Welcome text on the top of the config wizard page.
+ Welcome text on the top of the config wizard page.
gluon-config-mode:pubkey
- Information about the public VPN key on the reboot page.
+ Information about the public VPN key on the reboot page.
gluon-config-mode:novpn
- Information shown on the reboot page, if the mesh VPN was not selected.
+ Information shown on the reboot page, if the mesh VPN was not selected.
gluon-config-mode:contact-help
- Description for the usage of the ``contact`` field
+ Description for the usage of the ``contact`` field
gluon-config-mode:contact-note
- Note shown (in small font) below the ``contact`` field
+ Note shown (in small font) below the ``contact`` field
gluon-config-mode:hostname-help
- Description for the usage of the ``hostname`` field
+ Description for the usage of the ``hostname`` field
gluon-config-mode:geo-location-help
- Description for the usage of the longitude/latitude fields (and altitude, if shown)
+ Description for the usage of the longitude/latitude fields (and altitude, if shown)
gluon-config-mode:altitude-label
- Label for the ``altitude`` field
+ Label for the ``altitude`` field
gluon-config-mode:reboot
- General information shown on the reboot page.
+ General information shown on the reboot page.
There is a POT file in the site example directory which can be used to create templates
for the language files. The command ``msginit -l en -i ../../docs/site-example/i18n/gluon-site.pot``
@@ -722,12 +715,12 @@ utilities are installed.
.. note::
- An empty ``msgstr``, as is the default after running ``msginit``, leads to
- the ``msgid`` being printed as-is. It does *not* hide the whole text, as
- might be expected.
+ An empty ``msgstr``, as is the default after running ``msginit``, leads to
+ the ``msgid`` being printed as-is. It does *not* hide the whole text, as
+ might be expected.
- Depending on the context, you might be able to use comments like
- ``<!-- empty -->`` as translations to effectively hide the text.
+ Depending on the context, you might be able to use comments like
+ ``<!-- empty -->`` as translations to effectively hide the text.
Site modules
------------
@@ -742,21 +735,21 @@ tree, with the important different that the list of feeds must be assigned to
the variable ``GLUON_SITE_FEEDS``. Multiple feed names must be separated by spaces,
for example::
- GLUON_SITE_FEEDS='foo bar'
+ GLUON_SITE_FEEDS='foo bar'
The feed names may only contain alphanumerical characters, underscores and slashes.
For each of the feeds, the following variables are used to specify how to update
the feed:
PACKAGES_${feed}_REPO
- The URL of the git repository to clone (usually ``git://`` or ``http(s)://``)
+ The URL of the git repository to clone (usually ``git://`` or ``http(s)://``)
PACKAGES_${feed}_COMMIT
- The commit ID of the repository to use
+ The commit ID of the repository to use
PACKAGES_${feed}_BRANCH
- Optional: The branch of the repository the given commit ID can be found in.
- Defaults to the default branch of the repository (usually ``master``)
+ Optional: The branch of the repository the given commit ID can be found in.
+ Defaults to the default branch of the repository (usually ``master``)
These variables are always all uppercase, so for an entry ``foo`` in GLUON_SITE_FEEDS,
the corresponding configuration variables would be ``PACKAGES_FOO_REPO``,
--
GitLab