docs/dev/web/model.rst

+Models
+======
+
+Models are defined in the ``model`` subdirectory of a gluon-web application
+(``/lib/gluon/config-mode/model`` for the config mode; the status
+page does not use any models). Model support is not part of the gluon-web core
+anymore, but is provided by the *gluon-web-model* package.
+
+Each model defines one or more forms to display on a page, and how the submitted
+form data is handled.
+
+Let's start with an example:
+
+.. code-block:: lua
+
+  local f = Form(translate('Hostname'))
+
+  local s = f:section(Section)
+
+  local o = s:option(Value, 'hostname', translate('Hostname'))
+  o.default = uci:get_first('system', 'system', 'hostname')
+  function o:write(data)
+    uci:set('system', uci:get_first('system', 'system'), 'hostname', data)
+    uci:commit('system')
+  end
+
+  return f
+
+The top-level element of a model is always a *Form*, but it is also possible for
+a model to return multiple forms, which are displayed one below the other.
+
+A *Form* has one or more *Sections*, and each *Section* has different types
+of options.
+
+All of these elements have an *id*, which is used to identify them in the HTML
+form and handlers. If no ID is given, numerical IDs will be assigned automatically,
+but using explicitly named elements is often advisable (and it is required if a
+form does not always include the same elements, i.e., some forms, sections or
+options are added conditionally). IDs are hierarchical, so in the above example,
+the *Value* would get the ID ``1.1.hostname`` (value *hostname* in first section
+of first form).
+
+Classes and methods
+-------------------
+
+  - *Form* (*title*, *description*, *id*)
+
+    - *Form:section* (*type*, *title*, *description*, *id*)
+
+      Creates a new section of the given type (usually *Section*).
+
+    - *Form:write* ()
+
+      Is called after the form has been submitted (but only if the data is valid). It
+      is called last (after all options' *write* methods) and is usually used
+      to commit changed UCI packages.
+
+      The default implementation of *write* doesn't do anything, but it can be
+      overridden.
+
+  - *Section* (usually instantiated through *Form:section*)
+
+    - *Section:option* (*type*, *id*, *title*, *description*)
+
+      Creates a new option of the given type. Option types:
+
+        - *Value*: simple text entry
+        - *TextValue*: multiline text field
+        - *ListValue*: radio buttons or dropdown selection
+        - *DynamicList*: variable number of text entry fields
+        - *Flag*: checkbox
+
+Most option types share the same properties and methods:
+
+  - *default*: default value
+  - *optional*: value may be empty
+  - *datatype*: one of the types described in :ref:`web-model-datatypes`
+
+    By default (when *datatype* is *nil*), all values are accepted.
+
+  - *state*: has one of the values *FORM_NODATA*, *FORM_VALID* and *FORM_INVALID*
+    when read in a form handler
+
+    An option that has not been submitted because of its dependencies will have
+    the state *FORM_NODATA*, *FORM_INVALID* if the submitted value is not valid
+    according to the set *datatype*, and *FORM_VALID* otherwise.
+
+  - *data*: can be read in form handlers to get the submitted value
+
+  - *depends* (*self*, *option*, *value*): adds a dependency on another option
+
+    The option will only be shown when the passed option has the given value. This
+    is mainly useful when the other value is a *Flag* or *ListValue*.
+
+  - *depends* (*self*, *deps*): adds a dependency on multiple other options
+
+    *deps* must be a table with options as keys and values as values. The option
+    will only be shown when all passed options have the corresponding values.
+
+    Multiple alternative dependencies can be added by calling *depends* repeatedly.
+
+  - *value* (*self*, *value*, *text*): adds a choice to a *ListValue*
+
+  - *write* (*self*, *data*): is called with the submitted value when all form data is valid.
+
+    Does not do anything by default, but can be overridden.
+
+The *default* value, the *value* argument to *depends* and the output *data* always have
+the same type, which is usually a string (or *nil* for optional values). Exceptions
+are:
+
+  - *Flag* uses boolean values
+  - *DynamicList* uses a table of strings
+
+Despite its name, the *datatype* setting does not affect the returned value type,
+but only defines a validator the check the submitted value with.
+
+For a more complete example that actually makes use of most of these features,
+have a look at the model of the *gluon-web-network* package.
+
+.. _web-model-datatypes:
+
+Data types
+----------
+
+  - *integer*: an integral number
+  - *uinteger*: an integral number greater than or equal to zero
+  - *float*: a number
+  - *ufloat*: a number greater than or equal to zero
+  - *ipaddr*: an IPv4 or IPv6 address
+  - *ip4addr*: an IPv4 address
+  - *ip6addr*: an IPv6 address
+  - *wpakey*: a string usable as a WPA key (either between 8 and 63 characters, or 64 hex digits)
+  - *range* (*min*, *max*): a number in the given range (inclusive)
+  - *min* (*min*): a number greater than or equal to the given minimum
+  - *max* (*max*): a number less than or equal to the given maximum
+  - *irange* (*min*, *max*): an integral number in the given range (inclusive)
+  - *imin* (*min*): an integral number greater than or equal to the given minimum
+  - *imax* (*max*): an integral number less than or equal to the given maximum
+  - *minlength* (*min*): a string with the given minimum length
+  - *maxlength* (*max*): a string with the given maximum length
+
+Differences from LuCI
+---------------------
+
+  - LuCI's *SimpleForm* and *SimpleSection* are called *Form* and *Section*, respectively
+  - Is it not possible to add options to a *Form* directly, a *Section* must always
+    be created explicitly
+  - Many of LuCI's CBI classes have been removed, most importantly the *Map*
+  - The *rmempty* option attribute does not exist, use *optional* instead
+  - Only the described data types are supported
+  - Form handlers work completely differently (in particular, a *Form*'s *handle*
+    method should usually not be overridden in *gluon-web*)

docs/dev/web/view.rst

+Views
+=====
+
+The template parser reads views from the ``view`` subdirectory of a
+gluon-web application (``/lib/gluon/config-mode/view`` for the config mode,
+``lib/gluon/status-page/view`` for the status page).
+Writing own views should usually be avoided in favour of using :doc:`model`
+with their predefined views.
+
+Views are partial HTML pages, with additional template tags that allow
+to embed Lua code and translation strings. The following tags are defined:
+
+  - ``<%`` ... ``%>`` evaluates the enclosed Lua expression.
+  - ``<%|`` ... ``%>`` evaluates the enclosed Lua expression and prints its value.
+  - ``<%=`` ... ``%>`` evaluates the enclosed Lua expression and prints its value
+    *without escaping HTML entities*. This is useful when the value contains HTML code.
+  - ``<%+`` ... ``%>`` includes another template.
+  - ``<%:`` ... ``%>`` translates the enclosed string using the loaded i18n catalog.
+  - ``<%_`` ... ``%>`` translates the enclosed string *without escaping HTML entities*
+    in the translation. This only makes sense when the i18n catalog contains HTML code.
+  - ``<%#`` ... ``%>`` is a comment.
+
+All of these also come in the whitespace-stripping variants ``<%-`` and ``-%>`` that
+remove all whitespace before or after the tag.
+
+Complex combinations of HTML and Lua code are possible, for example:
+
+.. code-block:: text
+
+  <div>
+    <% if foo then %>
+      Content
+    <% end %>
+  </div>
+
+
+Variables and functions
+-----------------------
+
+Many call sites define additional variables (for example, model templates can
+access the model as *self* and a unique element ID as *id*), but the following
+variables and functions should always be available for the embedded Lua code:
+
+  - *renderer*: :ref:`web-controller-template-renderer`
+  - *http*: :ref:`web-controller-http`
+  - *request*: Table containing the path components of the current page
+  - *url* (*path*): returns the URL for the given path, which is passed as a table of path components.
+  - *attr* (*key*, *value*): Returns a string of the form ``key="value"``
+    (with a leading space character before the key).
+
+    *value* is converted to a string (tables are serialized as JSON) and HTML entities
+    are escaped. Returns an empty string when *value* is *nil* or *false*.
+  - *include* (*template*): Includes another template.
+  - *node* (*path*, ...): Returns the controller node for the given page (passed as
+    one argument per path component).
+
+    Use ``node(unpack(request))`` to get the node for the current page.
+  - *pcdata* (*str*): Escapes HTML entities in the passed string.
+  - *urlencode* (*str*): Escapes the passed string for use in an URL.
+  - *translate*, *_translate*, *translatef* and *i18n*: see :doc:`i18n`

docs/features/autoupdater.rst

@@ -7,30 +7,65 @@ Building Images
 ---------------
 
 By default, the autoupdater is disabled (as it is usually not helpful to have unexpected updates
-during development), but it can be enabled by setting the variable GLUON_BRANCH when building
-to override the default branch set in the set in the site configuration.
+during development), but it can be enabled by setting the variable ``GLUON_AUTOUPDATER_ENABLED`` to ``1`` when building.
+It is also possible to override the default branch during build using the variable ``GLUON_AUTOUPDATER_BRANCH``.
+
+If a default branch is set neither in *site.conf* nor via ``GLUON_AUTOUPDATER_BRANCH``, the default branch is
+implementation-defined. Currently, the branch with the first name in alphabetical order is chosen.
 
 A manifest file for the updater can be generated with `make manifest`. A signing script (using
-ecdsautils) can by found in the `contrib` directory. When creating the manifest, ``GLUON_PRIORITY`` can
-be set on the command line, or it can be taken from the ``site.mk``.
+``ecdsautils``) can be found in the `contrib` directory. When creating the manifest, the
+``PRIORITY`` value may be defined by setting ``GLUON_PRIORITY`` on the command line or in ``site.mk``.
+
+``GLUON_PRIORITY`` defines the maximum number of days that may pass between releasing an update and installation
+of the images. The update probability will start at 0 after the release time declared in the manifest file
+by the variable DATE and then slowly rise up to 1 when ``GLUON_PRIORITY`` days have passed. The autoupdater checks
+for updates hourly (at a random minute of the hour), but usually only updates during its run between
+4am and 5am, except when the whole ``GLUON_PRIORITY`` days and another 24 hours have passed.
+
+``GLUON_PRIORITY`` may be an integer or a decimal fraction.
+
+If ``GLUON_RELEASE`` is passed to ``make`` explicitly or it is generated dynamically
+in ``site.mk``, care must be taken to pass the same ``GLUON_RELEASE`` to ``make manifest``,
+as otherwise the generated manifest will be incomplete.
+
+
+Manifest format
+---------------
 
-The priority defines the maximum number of days that may pass between releasing an update and installation
-of the images. The update probability will start at 0 after the release time mentioned in the manifest
-and then slowly rise to 1 up to the point when the number of days given by the priority has passed.
+The manifest starts with a short header, followed by the list of firmwares and signatures.
+The header contains the following information:
 
-The priority may be an integer or a decimal fraction.
+.. code-block:: sh
+
+    BRANCH=stable
+    DATE=2020-10-07 00:00:00+02:00
+    PRIORITY=7
+
+- ``BRANCH`` is the autoupdater branch name that needs to match the nodes configuration.
+- ``DATE`` specifies when the time period for the update begins. Nodes will do their regular update during a random minute
+  between 4:00 and 4:59 am. Nodes might not always have a reliable NTP synchronization, which is why a fallback mechanism
+  exists, that checks for an update, and will execute if ``DATE`` is at least 24h in the past.
+- ``PRIORITY`` can be configured as ``GLUON_PRIORITY`` when generating the manifest or in ``site.mk``, and defines
+  the number of days over which the update should be stretched out after ``DATE``. Nodes will calculate a probability
+  based on the time left to determine when to update.
+
+
+Automated nightly builds
+------------------------
 
 A fully automated nightly build could use the following commands:
 
-::
+.. code-block:: sh
 
     git pull
-    (cd site && git pull)
+    # git -C site pull
     make update
-    make clean
+    make clean GLUON_TARGET=ath79-generic
     NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
-    make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ar71xx-generic GLUON_BRANCH=experimental
-    make manifest GLUON_BRANCH=experimental
+    make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ath79-generic GLUON_RELEASE=$GLUON_RELEASE \
+        GLUON_AUTOUPDATER_BRANCH=experimental GLUON_AUTOUPDATER_ENABLED=1
+    make manifest GLUON_RELEASE=$GLUON_RELEASE GLUON_AUTOUPDATER_BRANCH=experimental
     contrib/sign.sh $SECRETKEY output/images/sysupgrade/experimental.manifest
 
     rm -rf /where/to/put/this/experimental
@@ -74,8 +109,6 @@ These commands can be used on a node:
 
 ::
 
-   # If fallback is true the updater will perform an update only if 
-   # the timespan given by the priority and another 24h have passed
+  # 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
-
-

docs/features/configmode.rst

@@ -14,10 +14,13 @@ Activating Config Mode
 ----------------------
 
 Config Mode is automatically entered at the first boot. You can re-enter
-Config Mode by pressing and holding the RESET/WPS button for about three
-seconds. The device should reboot (all LEDs will turn of briefly) and 
+Config Mode by pressing and holding the RESET/WPS/DECT button for about three
+seconds. The device should reboot (all LEDs will turn off briefly) and
 Config Mode will be available.
 
+If you have access to the console of the node, there is the
+``gluon-enter-setup-mode`` command, which reboots a node into Config Mode.
+
 
 Port Configuration
 ------------------
@@ -35,3 +38,17 @@ Accessing Config Mode
 Config Mode can be accessed at http://192.168.1.1. The node will offer DHCP
 to clients. Should this fail, you may assign an IP from 192.168.1.0/24 to
 your computer manually.
+
+.. image:: configmode.png
+
+Advanced Config Options
+-----------------------
+
+Depending on the installed packages, the advanced config mode allows to configure packages further.
+
+* :doc:`gluon-web-wifi-config enable <wlan-configuration>` radios used for wifi and mesh as well as outdoor mode
+* :doc:`../package/gluon-web-network` allows to configure the used roles (uplink, mesh, client) on each interface
+* :doc:`../package/gluon-web-admin` allows to enter SSH keys or set a password in the `Remote access` section
+* :doc:`../package/gluon-web-cellular` allows to configure SIM card / WWAN settings on supported cellular devices
+
+The advanced config does also allow to upload a sysupgrade file to update the firmware to a different version.

docs/features/dns-cache.rst

+.. _dns-caching:
+
+DNS caching
+===========
+
+User experience may be greatly improved when dns is accelerated. Also, it
+seems like a good idea to keep the number of packages being exchanged
+between node and gateway as small as possible. In order to do this, a
+DNS cache may be used on a node. The dnsmasq instance listening on port
+53 on the node will be reconfigured to answer requests, use a list of
+upstream servers and a specific cache size if the options listed below are
+added to site.conf. Upstream servers are the DNS servers which are normally
+used by the nodes to resolve hostnames (e.g. gateways/supernodes).
+
+There are the following settings:
+    servers
+    cacheentries
+
+To use the node's DNS server, both options should be set. The node will cache at
+most 'cacheentries' many DNS records in RAM. The 'servers' list will be used to
+resolve the received DNS queries if the request cannot be answered from
+cache. Gateways should announce the "next node" address via DHCP and RDNSS (if
+any). Note that not setting 'servers' here will lead to DNS not working: Once
+the gateways all announce the "next node" address for DNS, there is no way for
+nodes to automatically determine DNS servers. They have to be baked into the
+firmware.
+
+If these settings do not exist, the cache is not initialized and RAM usage will
+not increase.
+
+When next_node.name is set, an A record and an AAAA record for the
+next-node IP address are placed in the dnsmasq configuration. This means that
+the content of next_node.name may be resolved even without upstream connectivity.
+It is suggested to use the same name as the DNS server provides:
+e.g. nextnode.location.community.example.org (This way the name also works if a
+client uses static DNS Servers). Hint: If next_node.name does not contain a dot
+some browsers would open the searchpage instead.
+
+::
+
+  dns = {
+    cacheentries = 5000,
+    servers = { '2001:4860:4860::8888', '2001:4860:4860::8844' },
+  },
+
+  next_node = {
+    name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
+    ip6 = '2001:db8:8::1',
+    ip4 = '198.51.100.1',
+  }
+
+
+Each cache entry will occupy about 90 bytes of RAM.

docs/features/monitoring.rst

@@ -24,7 +24,7 @@ Information to be announced is currently split into three categories:
     interfaces. This data can be used to determine the network topology.
 
 All categories will have a ``node_id`` key. It should be used to
-relate data of different catagories.
+relate data of different categories.
 
 Accessing Node Information
 --------------------------
@@ -33,7 +33,7 @@ There are two packages responsible for distribution of the information. For
 one, information is distributed across the mesh using alfred_. Information
 between neighbouring nodes is exchanged using `gluon-respondd`.
 
-.. _alfred: http://www.open-mesh.org/projects/alfred
+.. _alfred: https://www.open-mesh.org/projects/alfred
 
 alfred (mesh bound)
 ~~~~~~~~~~~~~~~~~~~
@@ -45,7 +45,7 @@ retrieve the data you'll need both a local alfred daemon and alfred-json_
 installed. Please note that at least one alfred daemon is required to run as
 `master`.
 
-.. _alfred-json: https://github.com/tcatm/alfred-json
+.. _alfred-json: https://github.com/ffnord/alfred-json
 
 The following data types are used:
 
@@ -97,14 +97,15 @@ In order to retrieve statistics data you could run:
 
 You can find more information about alfred in its README_.
 
-.. _README: http://www.open-mesh.org/projects/alfred/repository/revisions/master/entry/README
+.. _README: https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README.rst
 
 gluon-respondd
 ~~~~~~~~~~~~~~
 
 `gluon-respondd` allows querying neighbouring nodes for their information.
 It is a daemon listening on the multicast address ``ff02::2:1001`` on
-UDP port 1001 on both the bare mesh interfaces and `br-client`. Unicast
+UDP port 1001 on the mesh interface and on the multicast address
+``ff05::2:1001`` on the `br-client` interface. Unicast
 requests are supported as well.
 
 The supported requests are:
@@ -117,13 +118,13 @@ The supported requests are:
 gluon-neighbour-info
 ~~~~~~~~~~~~~~~~~~~~
 
-The programm `gluon-neighbour-info` can be used to retrieve
+The program `gluon-neighbour-info` can be used to retrieve
 information from other nodes.
 
 ::
 
-  gluon-neighbour-info -i wlan0 \
-  -p 1001 -d ff02:0:0:0:0:0:2:1001 \
+  gluon-neighbour-info -i bat0 \
+  -p 1001 -d ff05:0:0:0:0:0:2:1001 \
   -r nodeinfo
 
 An optional timeout may be specified, e.g. `-t 5` (default: 3 seconds). See
@@ -134,5 +135,5 @@ Adding a data provider
 ----------------------
 
 To add a provider, you need to install a shared object into ``/lib/gluon/respondd``.
-For more information, refer to the `respondd README <https://github.com/freifunk-gluon/packages/blob/master/net/respondd/README.md>`_
+For more information, refer to the `respondd README <https://github.com/freifunk-gluon/packages/blob/main/net/respondd/README.md>`_
 and have a look the existing providers.

docs/features/private-wlan.rst

 Private WLAN
 ============
 
-It is possible to set up a private WLAN that bridges the WAN port and is seperated from the mesh network.
-Please note that you should not enable ``mesh_on_wan`` simultaneously.
+It is possible to set up a private WLAN that bridges the uplink port and is separated from the mesh network.
+Please note that you should not enable Wired Mesh on the uplink port at the same time.
 
-The private WLAN can be enabled through the config mode if the package ``gluon-luci-private-wifi`` is installed.
+The private WLAN is encrypted using WPA2 by default. On devices with enough flash and a supported radio,
+WPA3 or WPA2/WPA3 mixed-mode can be used instead of WPA2. For this to work, the ``wireless-encryption-wpa3``
+feature has to be enabled as a feature.
+
+It is recommended to enable IEEE 802.11w management frame protection for WPA2/WPA3 networks, however this
+can lead to connectivity problems for older clients. In this case, management frame protection can be
+made optional or completely disabled in the advanced settings tab.
+
+The private WLAN can be enabled through the config mode if the package ``gluon-web-private-wifi`` is installed.
 You may also enable a private WLAN using the command line::
 
-  uci set wireless.wan_radio0=wifi-iface
-  uci set wireless.wan_radio0.device=radio0
-  uci set wireless.wan_radio0.network=wan
-  uci set wireless.wan_radio0.mode=ap
-  uci set wireless.wan_radio0.encryption=psk2
-  uci set wireless.wan_radio0.ssid="$SSID"
-  uci set wireless.wan_radio0.key="$KEY"
-  uci set wireless.wan_radio0.disabled=0
+  RID=0
+  SSID="privateWLANname"
+  KEY="yoursecret1337password"
+
+  uci set wireless.wan_radio$RID=wifi-iface
+  uci set wireless.wan_radio$RID.device=radio$RID
+  uci set wireless.wan_radio$RID.network=wan
+  uci set wireless.wan_radio$RID.mode=ap
+  uci set wireless.wan_radio$RID.encryption=psk2
+  uci set wireless.wan_radio$RID.ssid="$SSID"
+  uci set wireless.wan_radio$RID.key="$KEY"
+  uci set wireless.wan_radio$RID.disabled=0
+  uci set wireless.wan_radio$RID.macaddr=$(lua -e "print(require('gluon.util').generate_mac(3+4*$RID))")
   uci commit
   wifi
 

docs/features/roles.rst

@@ -2,8 +2,8 @@ Roles
 =====
 
 It is possible to define a set of roles you want to distinguish at backend side. One node can own one
-role which it will announce via alfred inside the mesh. This will make it easier to differentiate
-nodes when parsing alfred data. E.g to count only **normal** nodes and not the gateways
+role which it will announce via respondd/announced inside the mesh. This will make it easier to differentiate
+nodes when parsing respondd data. E.g to count only **normal** nodes and not the gateways
 or servers (nodemap). A lot of things are possible.
 
 For this the section ``roles`` in ``site.conf`` is needed::
@@ -18,17 +18,17 @@ For this the section ``roles`` in ``site.conf`` is needed::
     },
   },
 
-The strings to display in the LuCI interface are configured per language in the
+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-luci-node-role:role:node`` and ``gluon-luci-node-role:role:backbone``.
+``gluon-web-node-role:role:node`` and ``gluon-web-node-role:role:backbone``.
 
 The value of ``default`` is the role every node will initially own. This value should be part of ``list`` as well.
 If you want node owners to change the defined roles via config-mode you can add the package
-``gluon-luci-node-role`` to your ``site.mk``.
+``gluon-web-node-role`` to your ``site.mk``.
 
 The role is saved in ``gluon-node-info.system.role``. To change the role using command line do::
 
-  uci set gluon-node-info.system.role="$ROLE"
+  uci set gluon-node-info.@system[0].role="$ROLE"
   uci commit
 
 Please replace ``$ROLE`` by the role you want the node to own.

docs/features/tls.rst

+TLS support
+===========
+
+The generic TLS implementation which is currently used by OpenWRT can be installed or added as dependency through the package ``gluon-tls``.
+This removes the need for community packages to depend on a specific TLS implementation (like mbedtls, OpenSSL or WolfSSL).
+
+This package is an alias for the current TLS implementation used.
+To allow for easy usage of communicating through HTTPS from the node, typical Certificate Authorities (CAs) are included through the package ``ca-bundle`` .
+
+* Starting with OpenWRT 23.05, mbedtls is the default TLS layer - this is reflected in Gluon :ref:`v2023.2 <releases-v2023.2-minor-changes>`. HTTPS is used by default to communicate with OpenWRT opkg servers.