From 473818e90565bb4340101da5ae377d936c54c7eb Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Sat, 7 Jul 2018 11:44:01 +0200
Subject: [PATCH] docs: add v2018.1 release notes
---
docs/index.rst | 1 +
docs/releases/v2018.1.rst | 376 ++++++++++++++++++++++++++++++++++++++
docs/user/site.rst | 2 +
3 files changed, 379 insertions(+)
create mode 100644 docs/releases/v2018.1.rst
diff --git a/docs/index.rst b/docs/index.rst
index 880790d4d..b4e977934 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -70,6 +70,7 @@ Several Freifunk communities in Germany use Gluon as the foundation of their Fre
:caption: Releases
:maxdepth: 1
+ releases/v2018.1
releases/v2017.1.8
releases/v2017.1.7
releases/v2017.1.6
diff --git a/docs/releases/v2018.1.rst b/docs/releases/v2018.1.rst
new file mode 100644
index 000000000..20e5729e1
--- /dev/null
+++ b/docs/releases/v2018.1.rst
@@ -0,0 +1,376 @@
+Gluon 2018.1 (in development)
+#############################
+
+Important notes
+***************
+
+This version changes the flash partition layout on some devices (TP-Link CPE/WBS 210/510). 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.
+
+Some of the following paragraphs describe so-called "feature flags". This new concept is
+explained in :ref:`user-site-feature-flags`.
+
+Added hardware support
+**********************
+
+ar71xx-generic
+==============
+
+* ALFA NETWORK
+
+ - AP121F
+
+* AVM
+
+ - FRITZ!Box 4020
+
+* OpenMesh
+
+ - A40
+ - A60
+ - OM2P v4
+ - OM2P-HS v4
+
+* TP-Link
+
+ - Archer C59 v1 [#noibss]_
+ - CPE210 v2
+
+ar71xx-nand
+===========
+
+* ZyXEL
+
+ - NBG6716
+
+ar71xx-tiny
+===========
+
+* TP-Link
+
+ - TL-WA901ND v5
+
+ipq806x [#newtarget]_ [#noibss]_
+================================
+
+* TP-Link
+
+ - Archer C2600
+
+ramips-mt7620 [#newtarget]_ [#noibss]_
+======================================
+
+* GL Innovations
+
+ - GL-MT300A
+ - GL-MT300N
+ - GL-MT750
+
+ramips-mt7628 [#newtarget]_ [#noibss]_
+======================================
+
+* VoCore
+
+ - VoCore 2
+
+ramips-rt305x [#newtarget]_ [#noibss]_
+======================================
+
+* A5
+
+ - V11
+
+* D-Link
+
+ - DIR615 (D1, D2, D3, D4, H1)
+
+* VoCore
+
+ - VoCore (8MB, 16MB)
+
+sunxi [#newtarget]_
+===================
+
+* LeMaker
+
+ - Lamobo r1
+
+
+.. [#newtarget]
+ 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``.
+
+New features
+************
+
+Multidomain support
+===================
+
+When mesh networks grow too large, it becomes necessary to split them into
+multiple independent mesh domains to allow the meshes to work with reasonable
+performance. Formerly, the only way to achieve this with Gluon was to build
+a separate set of firmware images for each domain.
+
+With Gluon 2018.1, multidomain firmwares can be used to achieve the same,
+using only a single site configuration that is basis for several different
+domain-specific configurations. The feature is explained in detail in
+:doc:`../features/multidomain`.
+
+Wired mesh encapsulation
+========================
+
+Gluon now supports encapsulating wired mesh traffic (Mesh on LAN/WAN) in
+`VXLAN <https://en.wikipedia.org/wiki/Virtual_Extensible_LAN>`_.
+See :doc:`../features/wired-mesh` for details on this feature.
+
+Router advertisement filtering
+==============================
+
+Similar to the builtin batman-adv gateway feature for IPv4, the *gluon-radv-filterd* package
+(*radv-filterd* feature flag) allows to filter IPv6 router advertisements received from the mesh
+so that only the RAs with the best routing metric (TQ) reach the clients, ensuring that
+the "best" (topologically closest) gateway is chosen as the IPv6 default route, thereby
+reducing gateway crosstalk.
+
+At the moment, this feature only filters RAs forwarded to clients; the RAs handled on
+the nodes themselves will be unfiltered, so the nodes will still use arbitrary default
+gateways.
+
+IGMP/MLD segmentation
+=====================
+
+The IGMP/MLD segmentation feature previously provided by the *gluon-ebtables-segment-mld*
+package has been extended and moved into the Gluon core; it does not exist as a separate package
+anymore.
+
+Filtering IGMP/MLD queries directed towards the mesh ensures that each node becomes the multicast querier
+for its own clients (unless there are other multicast-aware switches connected to the node), rather
+than electing a single, basically arbitrary node in the mesh to become the querier. Overall,
+this should significantly improve the reliablity of multicast in the mesh. This is especially
+important for IPv6, as the IPv6 Neighbour Discovery Protocol (NDP) is based on local multicast.
+
+See also the documentation of the :ref:`site.conf mesh section <user-site-mesh>`.
+
+gluon-ebtables-limit-arp
+========================
+
+The *gluon-ebtables-limit-arp* (*ebtables-limit-arp* feature flag) package adds filters to limit the
+rate of ARP requests client devices are allowed to send into the mesh.
+
+Certain client applications are known to generate a significant amount of such ARP requests and
+are reportedly becoming more and more common. Without this package, such clients are one
+known cause for mesh wide load and congestion problems (see also the :ref:`releases-v2018.1-known-issues`
+section below).
+
+Because of this package's implementation, which relies on frequent dynamic updates
+- something ebtables does not perform well at - it is not included by default, as it can
+cause unnecessary load. Feedback, especially with a close look on load and congestion on
+nodes with a large number of changing client devices, is very much welcome. Depending on the
+feedback, we might enable this feature by default in a future release.
+
+Public key in respondd data (optional)
+======================================
+
+If desired, the fastd public key of a node can be included in the respondd nodeinfo data,
+faciliating the correlations of VPN peers and nodes. As the VPN key is transmitted unencrypted
+in the fastd handshake, this would theoretically allow an ISP to determine which nodes
+are operated behind which internet line. Therefore, this feature must be enabled explicitly
+by setting *mesh_vpn.pubkey_privacy* to ``false`` in *site.conf*.
+
+B.A.T.M.A.N. V (experimental)
+=============================
+
+When using batman-adv compat 15, it is now possible to switch to the new routing
+algorithm B.A.T.M.A.N. V (while the old algorithm is called B.A.T.M.A.N. IV) by
+setting *mesh.batman_adv.routing_algo* to ``"BATMAN_V"``. Note that the new routing
+algorithm is not backwards-compatible, so nodes using different algorithms can
+not interoperate.
+
+.. _releases-v2018.1-site-changes:
+
+Site changes
+************
+
+site.mk
+=======
+
+* Due to improved package dependency handling, the packages
+ *gluon-config-mode-core* and *gluon-setup-mode* do not need
+ to be listed explicitly in *site.mk* anymore; they will be
+ pulled in implicitly.
+* Including the *ebtables-limit-arp* feature flag is recommended. Please note
+ the abovementioned caveats on this feature.
+* We recommend to use *GLUON_FEATURES* for all Gluon packages, and rely on
+ *GLUON_SITE_PACKAGES* for non-Gluon (OpenWrt) packages only, as explained
+ in :ref:`user-site-feature-flags`.
+
+site.conf
+=========
+
+When updating a site configuration from Gluon 2017.1.x, the following changes
+must be made:
+
+* .. code-block:: lua
+
+ domain_seed = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+
+ These 32 bytes of random data (encoded in hexadecimal) are used to seed a number
+ of site/domain specific random values that must be the same on all nodes of the
+ same mesh, but different for different meshes. The following command
+ can be used to generate such a random value:
+
+ .. code-block:: shell
+
+ echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
+
+ In multidomain setups, repeat this command for each domain.
+
+ At this time, only the VXLAN ID for wired meshing is derived from the domain seed.
+
+* .. code-block:: lua
+
+ mesh = {
+ vxlan = true, -- or false
+ -- ...
+ },
+
+ In single domain setups, the new *mesh.vxlan* option is mandatory. It should be set to *true* in new
+ meshes; existing setups should set it to *false* to retain compatibility with older versions of Gluon.
+
+ In multidomain setups, *mesh.vxlan* defaults to *true* and does not need to be set explicitly.
+ It can still be set to *false* for individual domains that should allow wired meshing with existing
+ setups, which is also useful for migrating an existing mesh to a multidomain-capable firmware.
+
+* Password change form
+
+ The password change form in the "Advanced settings" is not shown by default anymore, as SSH keys are
+ the recommended means of authentication. It is still possible to set a password via SSH while in
+ config mode.
+
+ Set
+
+ .. code-block:: lua
+
+ config_mode = {
+ remote_login = {
+ show_password_form = true,
+ -- ...
+ },
+ -- ...
+ },
+
+ to restore the old behaviour.
+
+ When shown, the password form requires a minimum password length of 12 characters now. This requirement
+ can be modified using the *config_mode.remote_login.min_password_length* setting.
+
+i18n
+====
+
+It is now possible to override a few labels and descriptions in the configuration
+wizard. The available message IDs are listed in :ref:`site-config-mode-texts`.
+
+These new i18n strings are optional; leaving them empty or unset will retain the
+default texts.
+
+Internals
+*********
+
+Status page rewrite
+===================
+
+The status page has been rewritten to simplify the code and reduce its size. Rather than
+having a static frontend and retrieving all information via JavaScript, all static information
+in the status page is now generated on the node, and JavaScript is only used for dynamic data.
+
+To achieve this, the status page was ported to the gluon-web framework. The new status page
+also makes use of Gluon's usual i18n facilities now. In addition, the gluon-web-model
+package was split out of the gluon-web core package, as model support is only required
+for config mode packages, but not for the new status page.
+
+i18n namespaces
+===============
+
+In earlier version of Gluon, all gluon-web (formerly LuCI) packages shared the same i18n namespace,
+so independent packages could override each others translations (with an arbitrary translation of
+the same string "winning"). This issue has been solved by giving each package its own translation
+namespace, which is defined by the *package* directive in a package's controller. It is still
+possible to access a different i18n namespace (e.g. gluon-web base or site translations), which is
+described in :doc:`../dev/web/i18n`.
+
+Package Makefile cleanup
+========================
+
+The Makefiles of the individual Gluon packages have been cleaned up significantly by moving a
+lot of boilerplate code to *package/gluon.mk*. The new features of *package/gluon.mk* are
+explained in detail in :doc:`../dev/packages`.
+
+Site checker
+============
+
+* New JSON/Lua path specification
+
+ The old string-based path specifications in site check scripts (e.g. ``'autoupdater.branch'``)
+ have been replaced with arrays (``{'autoupdater', 'branch'}``). This will implicitly ensure that
+ *autoupdater* is a table when it exists (simplifying checks for deep structures), and it makes it easier
+ to specify paths with variable components (by referencing a variable as an array element).
+
+* Alternatives
+
+ The site check library has gained support for *alternatives*. It is now possible to check
+ if a configuration satisfies one of multiple checks:
+
+ .. code-block:: lua
+
+ -- foo can be a boolean or a string!
+ alternatives(function()
+ need_boolean({'foo'})
+ end, function()
+ need_string({'foo'})
+ end)
+
+ As many branches (functions) as necessary can be passed to a single *alternatives* call, which will succeed when
+ at least one of the branches succeeds.
+
+batman-adv multicast optimizations
+==================================
+
+After various extra rounds of testing and fixes, the batman-adv (compat 15) multicast optimizations were
+reenabled: knowledge about potential multicast listeners is gathered and distributed through the mesh again.
+
+This is the next step towards the addition of the actual multicast distribution optimizations, which are
+being prepared in `#1357 <https://github.com/freifunk-gluon/gluon/pull/1357>`_. When finished, the optimizations
+will help reduce the remaining Layer-2-specific network overhead, e.g. multicasted ICMPv6 messages.
+
+No behaviour changes are expected yet, as the multicast sender side is still disabled.
+Once the majority of the mesh network has been updated to Gluon 2018.1, it can be activated on
+dedicated nodes by including `#1357 <https://github.com/freifunk-gluon/gluon/pull/1357>`_ in the firmware
+build. Test feedback is very welcome.
+
+.. _releases-v2018.1-known-issues:
+
+Known issues
+************
+
+* 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 promicious 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 specially 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/user/site.rst b/docs/user/site.rst
index 142ec919b..94d6d181a 100644
--- a/docs/user/site.rst
+++ b/docs/user/site.rst
@@ -182,6 +182,8 @@ next_node \: package
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.
--
GitLab