From bf5b026a872e244d90a88d22b2f2871478ad7b90 Mon Sep 17 00:00:00 2001
From: Martin Weinelt <martin@darmstadt.freifunk.net>
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 b7a399c56..4917e82d1 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 73ad21cad..ae4a4df00 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 000000000..1cd4f65c5
--- /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 <release-v2019.1-batman-adv-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 <user-site-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 <user-site-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 <user-site-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 <https://github.com/freifunk-gluon/gluon/issues/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 <https://github.com/freifunk-gluon/gluon/issues/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 <https://github.com/freifunk-gluon/gluon/pull/1745>`_)
+
+* The variable ``DEVICES`` that controls which devices to build images for has been renamed to ``GLUON_DEVICES``.
+ (`#1686 <https://github.com/freifunk-gluon/gluon/pull/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 <https://github.com/freifunk-gluon/gluon/pull/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 <https://github.com/freifunk-gluon/gluon/pull/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 <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 <https://github.com/freifunk-gluon/gluon/pull/1745>`_)
+
+luacheck
+========
+
+Lua scripts can now be properly linted and analyzed using luacheck. Run ``luacheck package scripts target`` in the
+Gluon project root. (`#1741 <https://github.com/freifunk-gluon/gluon/pull/1741>`_)
+
+
+Docker build environment
+========================
+
+A minimal docker-based build environment is now available in ``contrib/Dockerfile``.
+(`#1738 <https://github.com/freifunk-gluon/gluon/pull/1738>`_)
+
+
+Reload of domain-related services
+=================================
+
+A mechanism to reload domain related services is now available.
+(`#1710 <https://github.com/freifunk-gluon/gluon/pull/1710>`_)
+
+
+.. _releases-v2019.1-known-issues:
+
+
+Known issues
+************
+
+* Out of memory situations with high client count on ath9k.
+ (`#1768 <https://github.com/freifunk-gluon/gluon/issues/1768>`_)
+
+* The integration of the BATMAN_V routing algorithm is incomplete.
+
+ - | Mesh neighbors don't appear on the status page. (`#1726 <https://github.com/freifunk-gluon/gluon/issues/1726>`_)
+ | Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput
+ | metric.
+
+ - | Throughput values are not correctly acquired for different interface types.
+ | (`#1728 <https://github.com/freifunk-gluon/gluon/issues/1728>`_)
+ | This affects virtual interface types like bridges and VXLAN.
+
+* Default TX power on many Ubiquiti devices is too high, correct offsets are unknown
+ (`#94 <https://github.com/freifunk-gluon/gluon/issues/94>`_)
+
+ 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 <https://github.com/freifunk-gluon/gluon/issues/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 <https://github.com/freifunk-gluon/gluon/issues/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 <https://github.com/freifunk-gluon/gluon/issues/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 b30ac0403..2b9c9584c 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 48f16027a..95c4407ac 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 49007b65d..4d09ccec1 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
-------------------
--
GitLab