From bf5b026a872e244d90a88d22b2f2871478ad7b90 Mon Sep 17 00:00:00 2001 From: Martin Weinelt Date: Sat, 14 Sep 2019 13:56:55 +0200 Subject: [PATCH] docs: Add v2019.1 release notes --- README.md | 2 +- docs/index.rst | 1 + docs/releases/v2019.1.rst | 284 ++++++++++++++++++++++++++++++++++ docs/site-example/site.conf | 2 +- docs/user/getting_started.rst | 4 +- docs/user/site.rst | 4 + 6 files changed, 293 insertions(+), 4 deletions(-) create mode 100644 docs/releases/v2019.1.rst diff --git a/README.md b/README.md index b7a399c5..4917e82d 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ the future development of Gluon. Please refrain from using the `master` branch for anything else but development purposes! Use the most recent release instead. You can list all releases by running `git tag` -and switch to one by running `git checkout v2018.2.3 && make update`. +and switch to one by running `git checkout v2019.1 && make update`. If you're using the autoupdater, do not autoupdate nodes with anything but releases. If you upgrade using random master commits the nodes *will break* eventually. diff --git a/docs/index.rst b/docs/index.rst index 73ad21ca..ae4a4df0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -74,6 +74,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre :caption: Releases :maxdepth: 1 + releases/v2019.1 releases/v2018.2.3 releases/v2018.2.2 releases/v2018.2.1 diff --git a/docs/releases/v2019.1.rst b/docs/releases/v2019.1.rst new file mode 100644 index 00000000..1cd4f65c --- /dev/null +++ b/docs/releases/v2019.1.rst @@ -0,0 +1,284 @@ +Gluon 2019.1 +############ + +Important notes +*************** + +Gluon v2019.1.x will be the last series of releases to support batman-adv-legacy (v14 compat) and IBSS +(Ad-hoc) mesh links. Migration features have been developed and should be used during this release cycle +to migrate to batman-adv v15 compat and/or 802.11s mesh links. These migration features are the +:doc:`scheduled domain switching <../package/gluon-scheduled-domain-switch>` (since v2018.2.1) and +:ref:`batman-adv module coexistence ` (since v2019.1, see below). +The migration must be completed before an upgrade to future Gluon releases (v2019.2 or later) becomes +possible. + +With Gluon v2019.1, nodes will not answer respondd queries on ``[ff02::2:1001]:1001`` anymore. Respondd +querier setups still using this address must be updated to the new address ``[ff05::2:1001]:1001`` +(supported since Gluon v2017.1). This change was required due to cross-domain leakage of respondd data. + +If you are upgrading from a version prior to v2018.1, please note that the flash layout on some +devices (TP-Link CPE/WBS 210/510) was changed. To avoid upgrade failures, make sure to upgrade +to Gluon 2017.1.8 or the latest Gluon 2016.2.x (unreleased) before installing Gluon 2018.1, 2018.2 or 2019.1. + +Added hardware support +********************** + +ar71xx-generic +============== + +* D-Link + + - DAP-1330 A1 + +ar71xx-tiny [#deprecated]_ +========================== + +* TP-Link + + - TL-WR840N v2 + +ipq40xx +======= + +* 8devices + + - Jalapeno + +mpc85xx-p1020 [#newtarget]_ +=========================== + +* Aerohive + + - HiveAP 330 + +ramips-mt7621 +============= + +* ASUS + + - RT-AC57U [#noibss]_ + +.. [#deprecated] + This target will be reaching its end of life soon. This means that support + in the next major release of Gluon is doubtful. + +.. [#newtarget] + This is a new target. + +.. [#noibss] + Device or target does not support AP+IBSS mode: This device or target will not be built + when *GLUON_WLAN_MESH* is set to ``ibss``. + + +.. 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. + + + +New features +************ + +.. _release-v2019.1-batman-adv-coexistence: + +batman-adv coexistence +====================== + +To allow a migration from B.A.T.M.A.N. Adv. compat 14 this Gluon release offers the ability to ship both +B.A.T.M.A.N. Adv. compat versions 14 and 15 in the same image. The ``mesh.batman_adv.routing_algo`` option is used +to decide which module gets loaded and the scheduled domain switching functionality can be used to migrate between +the two versions. + +Note that if you were using ``gluon-mesh-batman-adv-14`` ("batman-adv-legacy") before you will need to update the +``mesh.batman_adv.routing_algo`` setting from from ``BATMAN_IV`` to ``BATMAN_IV_LEGACY`` if you want to +stay on v14 compat. + +See the :ref:`mesh ` section for the *site.conf* configuration of this feature. + +Outdoor Mode +============ + +Radio devices hosted outdoors are often affected by different regulation than if they were installed indoors. The +outdoor mode allows for the reconfiguration of 5 GHz radios onto different channels and channel ranges. +Regulatory policies like DFS currently make it difficult to use the 5 GHz band for mesh networking because it's +never certain that nodes will stay on the same channel. +If enabled, by setting ``wifi5.outdoor_chanlist``, a number of devices that are commonly installed outdoors will +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 + +* TP-Link + + - CPE510 + - WBS510 + +See the :ref:`wifi5 ` section for the *site.conf* configuration of this feature. + +Device Deprecation +================== + +The ar71xx-tiny and several devices in the ramips-rt305x target have been marked as deprecated. The `GLUON_DEPRECATED` +flag was introduced to offer communities the choice on how to deal with the ending support for those devices. Devices +or targets marked as deprecated will very likely not be included in following Gluon releases anymore, usually due to +their insufficient flash size. + +See the :ref:`Build configuration ` section for details. + +Hoodselector: Geolocation Mode +============================== + +The new hoodselector package allows a node to automatically reevaluate its selected mesh domain at runtime. In this +release we support its geolocation feature. + +See the :doc:`../package/gluon-hoodselector` documentation for details. + + +x86 images support firstboot +============================ + +x86 images are now using squashfs instead of ext4 and can now have their configuration reset by using ``firstboot``. + + +Bugfixes +******** + +* Fixes passwordless SSH access when gluon-authorized-keys was used without gluon-setup-mode. + (`#1777 `_) + +* Fixes cross-domain leakage of respondd data by not joining the link-local multicast group on br-client. Nodes will + not be answering respondd queries on ``[ff02::2:1001]:1001`` anymore. Respondd queries using that adresss must be + updated to the new address ``[ff05::2:1001]:1001``. (`#1701 `_) + + +Site changes +************ + +When updating a site configuration from Gluon 2018.2.x, the following changes must be made: + +site.mk +======= + +* We now require the ``GLUON_DEPRECATED`` variable to be set to decide how to handle the image generation for + deprecated devices. (`#1745 `_) + +* The variable ``DEVICES`` that controls which devices to build images for has been renamed to ``GLUON_DEVICES``. + (`#1686 `_) + +* The ``gluon-radvd`` package is now included by default and can be dropped from *FEATURES* and *GLUON_SITE_PACKGES*. + +site.conf +========= + +* The ``mesh.batman_adv.routing_algo`` option is now required when the batman-adv routing protocol is used. + (`#1622 `_) + + To continue using batman-adv v14 compat you need to set this option from ``BATMAN_IV`` to ``BATMAN_IV_LEGACY``. + +* The options ``wifi*.basic_rates`` and ``wifi*.supported_rates`` have been removed, as the legacy 802.11b rates are + now disabled by default. (`#1716 `_) + + +Gateway recommendations +*********************** + +These are recommendations for running non-Gluon nodes, like for example gateways, in your mesh network: + +* Since Gluon v2018.1 the IGMP/MLD segmentation feature was enabled by default. When ``bat0`` is run with a bridge on + top the ``bat0`` bridge port should be set to receive all multicast traffic unconditionally: + + :: + + # echo 2 > /sys/class/net/bat0/brport/multicast_router + + See the chapter on :ref:`IGMP/MLD Domain Segmentation ` for more details. + + +Internals +********* + +Debug Build Flag +================ + +Setting ``GLUON_DEBUG=1`` will provide firmware images including debugging symbols usable with GDB or similar tools. +Requires a device or target with at least 16 MB of flash space, e.g. `x86-64`. Unset by default. + +Lua target files +================ + +Target definitions were rewritten in Lua; this was necessary to implement the device deprecation feature. It also +offers the option for more flexible tagging of devices in the future. +(`#1745 `_) + +luacheck +======== + +Lua scripts can now be properly linted and analyzed using luacheck. Run ``luacheck package scripts target`` in the +Gluon project root. (`#1741 `_) + + +Docker build environment +======================== + +A minimal docker-based build environment is now available in ``contrib/Dockerfile``. +(`#1738 `_) + + +Reload of domain-related services +================================= + +A mechanism to reload domain related services is now available. +(`#1710 `_) + + +.. _releases-v2019.1-known-issues: + + +Known issues +************ + +* Out of memory situations with high client count on ath9k. + (`#1768 `_) + +* 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. + + - | 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 `_) + + Reducing the TX power in the Advanced Settings is recommended. + +* The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled + (`#496 `_) + + This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is + disallowed). + +* Inconsistent respondd API (`#522 `_) + + The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while. + +* Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware especially in larger + meshes (`#1243 `_) + + Optimizations in Gluon 2018.1 have significantly improved memory usage. + There are still known bugs leading to unreasonably high load that we hope to + solve in future releases. + diff --git a/docs/site-example/site.conf b/docs/site-example/site.conf index b30ac040..2b9c9584 100644 --- a/docs/site-example/site.conf +++ b/docs/site-example/site.conf @@ -1,4 +1,4 @@ --- This is an example site configuration for Gluon v2018.2+ +-- This is an example site configuration for Gluon v2019.1 -- -- Take a look at the documentation located at -- https://gluon.readthedocs.io/ for details. diff --git a/docs/user/getting_started.rst b/docs/user/getting_started.rst index 48f16027..95c4407a 100644 --- a/docs/user/getting_started.rst +++ b/docs/user/getting_started.rst @@ -8,7 +8,7 @@ Gluon's releases are managed using `Git tags`_. If you are just getting started with Gluon we recommend to use the latest stable release of Gluon. Take a look at the `list of gluon releases`_ and notice the latest release, -e.g. *v2018.2.3*. Always get Gluon using git and don't try to download it +e.g. *v2019.1*. Always get Gluon using git and don't try to download it as a Zip archive as the archive will be missing version information. Please keep in mind that there is no "default Gluon" build; a site configuration @@ -44,7 +44,7 @@ Building the images ------------------- To build Gluon, first check out the repository. Replace *RELEASE* with the -version you'd like to checkout, e.g. *v2018.2.3*. +version you'd like to checkout, e.g. *v2019.1*. :: diff --git a/docs/user/site.rst b/docs/user/site.rst index 49007b65..4d09ccec 100644 --- a/docs/user/site.rst +++ b/docs/user/site.rst @@ -163,6 +163,8 @@ wifi24 \: optional }, }, +.. _user-site-wifi5: + wifi5 \: optional Same as `wifi24` but for the 5Ghz radio. @@ -516,6 +518,8 @@ setup_mode \: package skip = true, }, +.. _user-site-build-configuration: + Build configuration -------------------