From 854fef4e12c07751c4da78081ac534e87ade9afd Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Fri, 24 Dec 2021 14:16:04 +0100 Subject: [PATCH 1/3] 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 | 204 ++-- 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 | 875 +++++++++--------- 21 files changed, 719 insertions(+), 723 deletions(-) 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``, From ac3ac29158864b46430354eb1be550f0b59e63c4 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Fri, 24 Dec 2021 14:18:16 +0100 Subject: [PATCH 2/3] docs: minor grammer/wording fixes --- docs/features/multidomain.rst | 2 +- docs/user/site.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/multidomain.rst b/docs/features/multidomain.rst index 91dd7bcf..80cae0de 100644 --- a/docs/features/multidomain.rst +++ b/docs/features/multidomain.rst @@ -188,7 +188,7 @@ domain.conf only variables - ``true``, ``false`` - ``{ 'foo', 'bar' }`` -- Because each domain is considered as an own layer 2 network, these +- Because each domain is considered a separate layer 2 network, these values should be different in each domain: - next_node.ip4 diff --git a/docs/user/site.rst b/docs/user/site.rst index e018bf16..bd2f9c3c 100644 --- a/docs/user/site.rst +++ b/docs/user/site.rst @@ -68,7 +68,7 @@ ntp_servers 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 + These 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 From 543039d190bfd74515b94187bdca5bbe52891488 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Fri, 24 Dec 2021 14:22:20 +0100 Subject: [PATCH 3/3] docs: remove obsolete workaround for paragraphs in nested lists With older versions of the RTD theme, paragraphs in nested lists would lead to inconsistent spacing. This has been fixed, so we can remove our workaround to use line blocks instead of paragraphs. --- docs/releases/v2019.1.1.rst | 14 ++++++++------ docs/releases/v2019.1.2.rst | 14 ++++++++------ docs/releases/v2019.1.3.rst | 14 ++++++++------ docs/releases/v2019.1.rst | 14 ++++++++------ docs/releases/v2020.1.1.rst | 14 ++++++++------ docs/releases/v2020.1.2.rst | 14 ++++++++------ docs/releases/v2020.1.3.rst | 14 ++++++++------ docs/releases/v2020.1.rst | 14 ++++++++------ 8 files changed, 64 insertions(+), 48 deletions(-) diff --git a/docs/releases/v2019.1.1.rst b/docs/releases/v2019.1.1.rst index 2e173d7a..024d5ad6 100644 --- a/docs/releases/v2019.1.1.rst +++ b/docs/releases/v2019.1.1.rst @@ -30,13 +30,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. * 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 7231b4ef..7ee0de32 100644 --- a/docs/releases/v2019.1.2.rst +++ b/docs/releases/v2019.1.2.rst @@ -26,13 +26,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. * 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 aab21693..7a78dfb2 100644 --- a/docs/releases/v2019.1.3.rst +++ b/docs/releases/v2019.1.3.rst @@ -36,13 +36,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. * 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 6632b119..43f5c3e7 100644 --- a/docs/releases/v2019.1.rst +++ b/docs/releases/v2019.1.rst @@ -253,13 +253,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. * 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 c7841531..e165863f 100644 --- a/docs/releases/v2020.1.1.rst +++ b/docs/releases/v2020.1.1.rst @@ -25,13 +25,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. - 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 4bc7c800..378917ea 100644 --- a/docs/releases/v2020.1.2.rst +++ b/docs/releases/v2020.1.2.rst @@ -50,13 +50,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. - 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 7b82b433..7a9f5d8e 100644 --- a/docs/releases/v2020.1.3.rst +++ b/docs/releases/v2020.1.3.rst @@ -30,13 +30,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. - 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 8dd23630..bebd07c4 100644 --- a/docs/releases/v2020.1.rst +++ b/docs/releases/v2020.1.rst @@ -206,13 +206,15 @@ 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 `_) - - | Throughput values are not correctly acquired for different interface types. - | (`#1728 `_) - | This affects virtual interface types like bridges and VXLAN. + 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. * Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (`#94 `_)