diff --git a/.editorconfig b/.editorconfig index 5174a187..9dca9dab 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 5508897c..8608567e 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 52073428..ca1cd041 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 `__. This file and the needed source tree are available in the directory: :: - openwrt/build_dir/target-/linux-/linux-/ + openwrt/build_dir/target-/linux-/linux-/ .. 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 `__. @@ -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 098b0276..7c239675 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 6e011245..545b8237 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 7abd59a8..91dd7bcf 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: +- 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 + - 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. +- 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 + - 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: +- Specific to a firmware build itself: - - site_code - - site_name - - autoupdater.branches.*.name - - autoupdater.branches.*.good_signatures - - autoupdater.branches.*.pubkeys + - 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: +- 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 + - 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 8697baad..c1ed9336 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 29135324..cd362ede 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 ee1fe146..f67c500d 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 2fd694c1..785c2b28 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 142be29e..8752a917 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 0385e8bf..2e173d7a 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/releases/v2019.1.2.rst b/docs/releases/v2019.1.2.rst index 7d44fd49..7231b4ef 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/releases/v2019.1.3.rst b/docs/releases/v2019.1.3.rst index 11dd0959..aab21693 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/releases/v2019.1.rst b/docs/releases/v2019.1.rst index a9e0a829..6632b119 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 ` 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/releases/v2020.1.1.rst b/docs/releases/v2020.1.1.rst index f18d1133..c7841531 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/releases/v2020.1.2.rst b/docs/releases/v2020.1.2.rst index 37adb6a1..4bc7c800 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/releases/v2020.1.3.rst b/docs/releases/v2020.1.3.rst index 429d4c78..7b82b433 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/releases/v2020.1.rst b/docs/releases/v2020.1.rst index d3bea233..8dd23630 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 `_) - | 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 `_) + | 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 `_) - | This affects virtual interface types like bridges and VXLAN. + - | Throughput values are not correctly acquired for different interface types. + | (`#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 `_) diff --git a/docs/user/getting_started.rst b/docs/user/getting_started.rst index 5d8d6aa2..a7b9d0cb 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 a3d221c4..e018bf16 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"' `. + 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 `. 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. + 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: - 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 - - ``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. - 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. - ``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`` 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. - ``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, - }, - }, + 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 - :: + 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. + 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' + } - 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. + 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. + 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``. + 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 ` for details. + 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 ` 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``. + 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: + 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: + The mandatory value *routing_algo* selects the batman-adv protocol variant. + The following values are supported: - - ``BATMAN_IV`` - - ``BATMAN_V`` + - ``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. + 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. + - **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". + 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 + .. _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 = { + 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. + 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 `. + 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 `. - 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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 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. + **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, + 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', - }, + 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', }, }, - -- 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. + 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. + 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. - :: + 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 - } + 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 `. + 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 `. .. _user-site-config_mode: config_mode \: optional - Additional configuration for the configuration web interface. All values are - 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*. + 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*. + 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. + 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. + 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. + *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. - :: + 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 = '© OpenStreetMap contributors.', - -- }, - }, - }, - remote_login = { - show_password_form = true, - min_password_length = 10, + 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 = '© OpenStreetMap 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``. + 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``. - :: + 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', - }, + 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 - ```` as translations to effectively hide the text. + Depending on the context, you might be able to use comments like + ```` 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``,