From 74a6556f9c6b4d61015b2e08fa3b245bcbcf74d9 Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Wed, 28 Oct 2015 00:03:07 +0100
Subject: [PATCH] docs: releases/v2015.2: update site migration guide

---
 docs/releases/v2015.2.rst | 110 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 109 insertions(+), 1 deletion(-)

diff --git a/docs/releases/v2015.2.rst b/docs/releases/v2015.2.rst
index eda71390..13af5b28 100644
--- a/docs/releases/v2015.2.rst
+++ b/docs/releases/v2015.2.rst
@@ -15,10 +15,118 @@ Bugfixes
 
 Site changes
 ~~~~~~~~~~~~
+* ``site.conf``
+
+  - New WLAN configuration
+
+    ``wifi24`` and ``wifi5`` need to be updated to a new more flexible format.
+    A configuration using the old format
+
+    ::
+
+      {
+        channel = 1,
+        htmode = 'HT20'
+        ssid = 'entenhausen.freifunk.net',
+        mesh_ssid = 'xe:xx:xx:xx:xx:xx',
+        mesh_bssid = 'xe:xx:xx:xx:xx:xx',
+        mesh_mcast_rate = 12000,
+      }
+
+    would look like this in the new format::
+
+      {
+        channel = 1,
+        ap = {
+          ssid = 'entenhausen.freifunk.net',
+        },
+        ibss = {
+          ssid = 'xe:xx:xx:xx:xx:xx',
+          bssid = 'xe:xx:xx:xx:xx:xx',
+          mcast_rate = 12000,
+        },
+      }
+
+    The ``htmode`` option has been dropped, the channel width is now always set to 20MHz
+    (see https://github.com/freifunk-gluon/gluon/issues/487 for a discussion of this change).
+
+    In addition to the old IBSS (Adhoc) based meshing, 802.11s-based meshing can be configured
+    using the ``mesh`` section. Example::
+
+      {
+        channel = 1,
+        ap = {
+          ssid = 'entenhausen.freifunk.net',
+        },
+        mesh = {
+          id = 'mesh.entenhausen.freifunk.net', -- can by any string, human-readable or random
+          mcast_rate = 12000,
+        },
+      }
+
+    While using ``ibss`` and ``mesh`` at the same time is possible, is causes high load in
+    very active meshes, so it is advisable to avoid such configurations.
+
+  - Bandwidth limitation defaults
+
+    The old section ``simple_tc.mesh_vpn`` has been moved to ``fastd_mesh_vpn.bandwidth_limit`` and the ``ifname``
+    field isn't used anymore. What looked like this
+    before
+
+    ::
+
+      simple_tc = {
+        mesh_vpn = {
+          ifname = 'mesh-vpn',
+          enabled = false,
+          limit_ingress = 3000,
+          limit_egress = 200,
+        }
+      }
+
+    needs to be changed to
+
+    ::
+
+      fastd_mesh_vpn = {
+        -- ...
+
+        bandwidth_limit = {
+          enabled = false,
+          ingress = 3000,
+          egress = 200,
+        },
+      }
+
+  - opkg repository configuration
+
+    The opkg configuration has been changed to be more flexible and allow specifying custom repositories.
+    Example::
+
+      opkg = {
+        openwrt = 'http://opkg.services.ffeh/openwrt/%n/%v/%S/packages',
+        extra = {
+          modules = 'http://opkg.services.ffeh/modules/gluon-%GS-%GR/%S',
+        },
+      }
+
+    The keys of the ``extra`` table (like ``modules`` in this example) can be chosen arbitrarily.
+
+    Instead of explicitly specifying the whole URL, using patterns is recommended. The following
+    patterns are understood:
+
+    - ``%n`` is replaced by the OpenWrt version codename (e.g. "chaos_calmer")
+    - ``%v`` is replaced by the OpenWrt version number (e.g. "15.05")
+    - ``%S`` is replaced by the target architecture (e.g. "ar71xx/generic")
+    - ``%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``)
+
+
 * ``i18n/``
 
   - The translations of ``gluon-config-mode:pubkey`` now have to show the fastd
-    public key itself if desired, making its format and whether it is shown at
+    public key itself if desired, making the formatting of the key and whether it is shown at
     all configurable. To retain the old format, add ``<p>`` to the beginning of
     your translations and append::