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/authorized-keys.rst

+Adding SSH public keys
+======================
+
+By using the package ``gluon-authorized-keys`` it is possible to add
+SSH public keys to an image to permit root login.
+
+If you select this package, add a list of authorized keys to ``site.conf`` like this:::
+
+  {
+    authorized_keys = { 'ssh-rsa AAA.... user1@host',
+                        'ssh-rsa AAA.... user2@host' },
+    hostname_prefix = ...
+    ...
+
+Existing keys in ``/etc/dropbear/authorized_keys`` will be preserved.

docs/features/autoupdater.rst

+Autoupdater
+===========
+
+Gluon contains an automatic update system which can be configured in the site configuration.
+
+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_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 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 manifest starts with a short header, followed by the list of firmwares and signatures.
+The header contains the following information:
+
+.. 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
+    # git -C site pull
+    make update
+    make clean GLUON_TARGET=ath79-generic
+    NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
+    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
+    cp -r output/images /where/to/put/this/experimental
+
+
+Infrastructure
+--------------
+
+We suggest to have following directory tree accessible via http:
+
+::
+
+    firmware/
+            stable/
+                    sysupgrade/
+                    factory/
+            snapshot/
+                    sysupgrade/
+                    factory/
+            experimental/
+                    sysupgrade/
+                    factory/
+
+The server must be available via IPv6.
+
+Command Line
+------------
+
+These commands can be used on a node:
+
+::
+
+  # Update with some probability
+  autoupdater
+
+::
+
+  # Force update check, even when the updater is disabled
+  autoupdater -f
+
+::
+
+  # 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

+Config Mode
+===========
+
+When in Config Mode a node will neither participate in the mesh nor connect
+to the VPN using the WAN port. Instead, it'll offer a web interface on the
+LAN port to aid configuration of the node.
+
+Whether a node is in Config Mode can be determined by a characteristic
+blinking sequence of the SYS LED:
+
+.. image:: node_configmode.gif
+
+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/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
+------------------
+
+In general, Config Mode will be offered on the LAN ports. However, there
+are two practical exceptions:
+
+* Devices with just one network port will run Config Mode on that port.
+* Devices with PoE on the WAN port will run Config Mode on the WAN port instead.
+
+
+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.

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

+Node monitoring
+===============
+
+Gluon is capable of announcing information about each node to the mesh
+and to neighbouring nodes. This allows nodes to learn each others hostname,
+IP addresses, location, software versions and various other information.
+
+Format of collected data
+------------------------
+
+Information to be announced is currently split into three categories:
+
+  nodeinfo
+    In this category (mostly) static information is collected. If
+    something is unlikely to change without human intervention it should be
+    put here.
+
+  statistics
+    This category holds fast changing data, like traffic counters, uptime,
+    system load or the selected gateway.
+
+  neighbours
+    `neighbours` contains information about all neighbouring nodes of all
+    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 categories.
+
+Accessing Node Information
+--------------------------
+
+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: https://www.open-mesh.org/projects/alfred
+
+alfred (mesh bound)
+~~~~~~~~~~~~~~~~~~~
+
+The package ``gluon-alfred`` is required for this to work.
+
+Using alfred both categories are distributed within the mesh. In order to
+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/ffnord/alfred-json
+
+The following data types are used:
+
+* `nodeinfo`: 158
+* `statistics`: 159
+* `neighbours`: 160
+
+All data is compressed using GZip (alfred-json can handle the decompression).
+
+In order to retrieve statistics data you could run:
+
+::
+
+  # alfred-json -z -r 159
+  {
+    "f8:d1:11:7e:97:dc": {
+      "processes": {
+        "total": 55,
+        "running": 2
+      },
+      "idletime": 30632.290000000001,
+      "uptime": 33200.07,
+      "memory": {
+        "free": 1660,
+        "cached": 8268,
+        "total": 29212,
+        "buffers": 2236
+      },
+      "node_id": "f8d1117e97dc",
+      "loadavg": 0.01
+    },
+    "90:f6:52:3e:b9:50": {
+      "processes": {
+        "total": 58,
+        "running": 2
+      },
+      "idletime": 28047.470000000001,
+      "uptime": 33307.849999999999,
+      "memory": {
+        "free": 2364,
+        "cached": 7168,
+        "total": 29212,
+        "buffers": 1952
+      },
+      "node_id": "90f6523eb950",
+      "loadavg": 0.34000000000000002
+    }
+  }
+
+You can find more information about alfred in its 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 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:
+
+* ``nodeinfo``, ``statistics``, ``neighbours``: Returns the data of single category uncompressed.
+* ``GET nodeinfo``, ...: Returns the data of one or multiple categories (separated by spaces)
+  compressed using the `deflate` algorithm (without a gzip header). The data may
+  be decompressed using zlib and many zlib bindings using -15 as the window size parameter.
+
+gluon-neighbour-info
+~~~~~~~~~~~~~~~~~~~~
+
+The program `gluon-neighbour-info` can be used to retrieve
+information from other nodes.
+
+::
+
+  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
+the usage information printed by ``gluon-neighbour-info -h`` for more information
+about the supported arguments.
+
+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>`_
+and have a look the existing providers.

docs/features/multidomain.rst

+Multidomain Support
+===================
+
+Preamble
+--------
+
+There comes a time when a mesh network grows past sensible boundaries.
+As broadcast traffic grows, mesh networks experience scaling issues and
+using them becomes very unpleasant. An approach to solve this follows
+the well-known “divide and conquer” paradigm and splits a large network
+into multiple smaller networks. These smaller networks start with a
+dedicated layer 2 network each, which are interconnected via their
+gateways by layer 3 routing. Gluon is already field-tested handling a
+single domain and the multidomain feature allows for the reconfiguration
+of key parameters that decide which domain a node participates in,
+without the need of a distinct set of firmware images for each mesh domain.
+
+Overview
+--------
+
+Multidomain support allows to build a single firmware with multiple,
+switchable domain configurations. The nomenclature is as follows:
+
+- ``site``: an aggregate over multiple domains
+- ``domain``: mesh network with connectivity parameters that prevent
+  accidental bridging with other domains
+- ``domain code``: unique domain identifier
+- ``domain name``: pretty name for a domain code
+
+By default Gluon builds firmware with a single domain embedded into
+``site.conf``. To use multiple domains, enable it in ``site.mk``:
+
+::
+
+  GLUON_MULTIDOMAIN=1
+
+In the site repository, create the ``domains/`` directory, which will
+hold your domain configurations. Each domain configuration file is named
+after its primary ``domain_code``, additional domain codes and names are
+supported.
+
+::
+
+  site/
+  |-- site.conf
+  |-- site.mk
+  |-- i18n/
+  |-- domains/
+    |-- alpha_centauri.conf
+    |-- beta_centauri.conf
+    |-- gamma_centauri.conf
+
+The domain configuration ``alpha_centauri.conf`` could look like this.
+
+::
+
+  {
+    domain_names = {
+      alpha_centauri = 'Alpha Centauri'
+    },
+
+    -- more domain specific config follows below
+  }
+
+In this example “Alpha Centauri” is the user-visible ``domain_name`` for the
+domain_code ``alpha_centauri``. Also note that the domain code
+``alpha_centauri`` matches the filename ``alpha_centauri.conf``.
+
+Additional domain codes/names can be added to ``domain_names``, which
+are treated as aliases for the their domain configuration. Aliases can
+be used to offer more fine-grained and well-recognizable domain choices
+to users. Having multiple aliases on a single domain is a helpful
+precursor to splitting the domain into even smaller blocks.
+
+Furthermore you have to specify the ``default_domain`` in the ``site.conf``.
+This domain is applied in following cases:
+
+- When the config mode is skipped.
+- When a domain is removed in a new firmware release, the default_domain
+  will be chosen then.
+- When a user selects a wrong domain code via uci.
+
+Please note, that this value is saved to uci, so changing the `default_domain`
+value in the `site.conf` in a new firmware release only affects the actual
+domain of a router, if and only if one of the above conditions matches.
+
+
+Switching the domain
+--------------------
+
+Via commandline
+^^^^^^^^^^^^^^^
+
+::
+
+  gluon-switch-domain 'newdomaincode'
+
+When the node is not in config mode, ``gluon-switch-domain`` will automatically
+reboot the node by default. This can be suppressed by passing ``--no-reboot``::
+
+  gluon-switch-domain --no-reboot 'newdomaincode'
+
+Switching the domain without reboot is currently **experimental**.
+
+Via config mode
+^^^^^^^^^^^^^^^
+
+To allow switching the domain via config mode, add ``config-mode-domain-select``
+to the enabled features in the image-customization.lua file.
+
+|image0|
+
+Allowed site variables
+----------------------
+
+Internally the site variables are merged from the ``site.conf`` and the
+selected ``domain.conf``, so the most variables are also allowed in
+``site.conf`` and in ``domain.conf``. But there are some exceptions,
+which do not make sense in a domain or site specific way. The following
+sections give an overview over variables that are only usable in either
+site or domain context.
+
+site.conf only variables
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Used in as initial default values, when the firmware was just flashed
+  and/or the config mode is skipped, so they do not make sense in a
+  domain specific way:
+
+  - authorized_keys
+  - default_domain
+  - poe_passthrough
+  - interfaces.*.default_roles
+  - setup_mode.skip
+  - autoupdater.branch
+  - mesh_vpn.enabled
+  - mesh_vpn.pubkey_privacy
+  - mesh_vpn.bandwidth_limit
+  - mesh_vpn.bandwidth_limit.enabled
+  - mesh_vpn.bandwidth_limit.ingress
+  - mesh_vpn.bandwidth_limit.egress
+
+- Variables that influence the appearance of the config mode,
+  domain-independent because they are relevant before a domain was selected.
+
+  - config_mode.geo_location.show_altitude
+  - config_mode.hostname.optional
+  - config_mode.remote_login
+  - config_mode.remote_login.show_password_form
+  - config_mode.remote_login.min_password_length
+  - hostname_prefix
+  - mesh_vpn.fastd.configurable
+  - roles.default
+  - roles.list
+
+- Specific to a firmware build itself:
+
+  - site_code
+  - site_name
+  - autoupdater.branches.*.name
+  - autoupdater.branches.*.good_signatures
+  - autoupdater.branches.*.pubkeys
+
+- We simply do not see any reason, why these variables could be helpful
+  in a domain specific way:
+
+  - mesh_vpn.fastd.syslog_level
+  - timezone
+  - regdom
+
+domain.conf only variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Obviously:
+
+  - domain_names
+
+    - a table of domain codes to domain names
+      ``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
+
+  - hide_domain
+
+    - prevents a domain name(s) from appearing in config mode, either
+      boolean or array of domain codes
+
+      - ``true``, ``false``
+      - ``{ 'foo', 'bar' }``
+
+- Because each domain is considered a separate layer 2 network, these
+  values should be different in each domain:
+
+  - next_node.ip4
+  - next_node.ip6
+  - next_node.name
+  - prefix6
+  - prefix4
+  - extra_prefixes6
+
+- To prevent accidental bridging of different domains, all meshing
+  technologies should be separated:
+
+  - domain_seed (wired mesh)
+
+    - must be a random value used to derive the vxlan id for wired meshing
+
+  - wifi*.mesh.id
+  - mesh_vpn.fastd.groups.*.peers.remotes
+  - mesh_vpn.fastd.groups.*.peers.key
+  - mesh_vpn.tunneldigger.brokers
+
+- Clients consider WiFi networks sharing the same ESSID as if they were
+  the same L2 network and try to reconfirm and reuse previous
+  addressing. If multiple neighbouring domains shared the same ESSID,
+  the roaming experience of clients would degrade.
+
+  - wifi*.ap.ssid
+
+- Some values should be only set in legacy domains and not in new domains.
+
+  - mesh.vxlan
+
+    - By default, this value is `true`. It should be only set to `false`
+      for one legacy domain, since vxlan prevents accidental wired
+      merges of domains. For old domains this value is still available
+      to keep compatibility between all nodes in one domain.
+
+  - next_node.mac
+
+    - For new domains, the default value should be used, since there is
+      no need for a special mac (or domain specific mac). For old domains
+      this value is still available to keep compatibility between all
+      nodes in one domain.
+
+Example config
+--------------
+
+site.mk
+^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/site.mk
+  :language: makefile
+
+site.conf
+^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/site.conf
+  :language: lua
+
+domains/alpha_centauri.conf
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/domains/alpha_centauri.conf
+  :language: lua
+
+i18n/en.po
+^^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/i18n/en.po
+  :language: po
+
+i18n/de.po
+^^^^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/i18n/de.po
+  :language: po
+
+modules
+^^^^^^^
+
+.. literalinclude:: ../multidomain-site-example/modules
+  :language: makefile
+
+
+.. |image0| image:: multidomain_configmode.gif

docs/features/private-wlan.rst

+Private WLAN
+============
+
+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 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::
+
+  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
+
+Please replace ``$SSID`` by the name of the WLAN and ``$KEY`` by your passphrase (8-63 characters).
+If you have two radios (e.g. 2.4 and 5 GHz) you need to do this for radio0 and radio1.
+
+It may also be disabled by running::
+
+  uci set wireless.wan_radio0.disabled=1
+  uci commit
+  wifi

docs/features/roles.rst

+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 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::
+
+  roles = {
+    default = 'node',
+    list = {
+      'node',
+      'test',
+      'backbone',
+      'service',
+    },
+  },
+
+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-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-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[0].role="$ROLE"
+  uci commit
+
+Please replace ``$ROLE`` by the role you want the node to own.

docs/features/vpn.rst

+Mesh VPN
+========
+
+Gluon integrates several layer 2 tunneling protocols to
+allow connections between local meshes through the internet.
+
+Protocol handlers
+^^^^^^^^^^^^^^^^^
+
+There are currently three protocol handlers which can be selected
+as a feature:
+
+mesh-vpn-fastd
+""""""""""""""
+
+fastd is a lightweight userspace tunneling daemon that
+implements cipher suites that are specifically designed
+to work well on embedded devices. It offers encryption
+and authentication.
+The primary drawback of fastd's encrypted connection modes
+is the necessary context switches when forwarding packets.
+A kernel-supported L2TPv3 offloading option is available to
+work around the context-switching bottleneck, but it comes
+at the cost of losing the ability to protect tunnel connections
+against eavesdropping or manipulation.
+
+mesh-vpn-tunneldigger
+"""""""""""""""""""""
+
+Tunneldigger always uses L2TPv3, generally achieving the same
+performance as fastd with the ``null@l2tp`` method, but offering
+no security.
+Tunneldigger's primary drawback is the lack of IPv6 support.
+It also provides less configurability than fastd.
+
+mesh-vpn-wireguard
+""""""""""""""""""
+
+WireGuard is an encrypted in-kernel tunneling protocol that
+provides encrypted transmission and at the same time offers
+high throughput.
+
+fastd
+^^^^^
+
+.. _VPN fastd methods:
+
+Methods
+"""""""
+
+fastd offers various different connection "methods" with different
+security properties that can be configured in the site configuration.
+
+The following methods are currently recommended:
+
+- ``salsa2012+umac``: Encrypted + authenticated
+- ``null+salsa2012+umac``: Unencrypted, authenticated
+- ``null@l2tp``: Unencrypted, unauthenticated
+
+Multiple methods can be listed in ``site.conf``. The first listed method
+supported by both the node and its peer will be used.
+
+The use of the ``null@l2tp`` method with offloading enabled can provide a
+considerable performance gain, especially on weaker embedded hardware.
+For L2TP offloading, the ``mesh-vpn-fastd-l2tp`` feature needs to be enabled in
+``site.mk``.
+
+
+.. _vpn-gateway-configuration:
+
+Gateway / Supernode Configuration
+"""""""""""""""""""""""""""""""""
+
+When only using the ``null`` or ``null@l2tp`` methods without offloading,
+simply add these methods to the front of the method list. ``null@l2tp``
+should always appear before ``null`` in the configuration when both are enabled.
+fastd v22 or newer is needed for the ``null@l2tp`` method.
+
+It is often not necessary to enable L2TP offloading on supernodes for
+performance reasons. Nodes using offloading can communicate with supernodes that
+don't use offloading as long as both use the ``null@l2tp`` method.
+
+
+.. _vpn-gateway-configuration-offloading:
+
+Offloading on Gateways / Supernodes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable L2TP offloading on the supernodes, it is recommended to study the
+fastd documentation section pertaining to the `offload configuration option
+<https://fastd.readthedocs.io/en/stable/manual/config.html#option-offload>`_.
+
+However, the important changes to the fastd config on your Supernode are:
+
+    - | Set ``mode multitap;``
+      | Every peer gets their own interface.
+
+    - | Replace ``interface "foo":`` with ``interface "peer-%k";``
+      | ``%k`` is substituted for a portion of the peers public key.
+
+    - | Set ``offload l2tp yes;``
+      | This tells fastd to use the l2tp kernel module.
+
+    - | Set ``persist interface no;``
+      | This tells fastd to only keep interfaces around while the connection is active.
+
+Note that in ``multitap`` mode, which is required when using L2TP offloading,
+fastd will create one interface per peer on the supernode's. This allows
+offloading the L2TP forwarding into the kernel space. But this also means added
+complexity with regards to handling those interfaces.
+
+There are two main options on how you can handle this:
+
+    -  create ``on up`` and ``on down`` hooks
+
+        - to handle interface setup and destruction
+        - preferably using the async keyword, so hooks are not blocking fastd
+
+    - use a daemon like systemd-networkd
+
+Examples for both options can be found in the
+`Wiki <https://github.com/freifunk-gluon/gluon/wiki/fastd-l2tp-offloading-on-supernodes>`_.
+
+Configurable Method
+"""""""""""""""""""
+
+From the site configuration, fastd can be allowed to offer
+toggleable encryption in the config mode with the intent to
+increase throughput.
+
+There is also an older unprotected method ``null``. Use of the newer
+``null@l2tp`` method is generally recommended over ``null``, as the
+performance gains provided by the latter (compared to the encrypted
+and authenticated methods) are very small.
+
+Site configuration
+~~~~~~~~~~~~~~~~~~
+
+1)
+  Add the feature ``web-mesh-vpn-fastd`` in ``site.mk``
+2)
+  Set ``mesh_vpn.fastd.configurable = true`` in ``site.conf``
+3)
+  Optionally, add ``null@l2tp`` to the ``mesh_vpn.fastd.methods`` table if you want
+  "Performance mode" as default (not recommended)
+
+Config Mode
+~~~~~~~~~~~
+
+The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport.
+
+.. image:: fastd_mode.gif
+
+To confirm whether the correct cipher is being used, the log output
+of fastd can be checked using ``logread``.
+
+WireGuard
+^^^^^^^^^
+
+In order to support WireGuard in Gluon, a few technologies are glued together.
+
+**VXLAN:** As Gluon typically relies on batman-adv, the Mesh VPN has to provide
+OSI Layer 2 transport. But WireGuard is an OSI Layer 3 tunneling protocol, so
+additional technology is necessary here. For this, we use VXLAN. In short, VXLAN
+is a well-known technology to encapsulate ethernet packages into IP packages.
+You can think of it as kind of similar to VLAN, but on a different layer. Here,
+we use VXLAN to transport batman-adv traffic over WireGuard.
+
+**wgpeerselector**: To connect all gluon nodes to each other, it is common to
+create a topology where each gluon node is connected to one of the available
+gateways via Mesh VPN respectively. To achieve this, the gluon node should be
+able to select a random gateway to connect to. But such "random selection of a
+peer" is not implemented in WireGuard by default. WireGuard only knows static
+peers. Therefore the *wgpeerselector* has been developed. It randomly selects a
+gateway, tries to establish a connection, and if it fails, tries to connect
+to the next gateway. This approach has several advantages, such as load
+balancing VPN connection attempts and avoiding problems with offline gateways.
+More information about the wgpeerselector and its algorithm can be found
+`here <https://github.com/freifunk-gluon/packages/blob/master/net/wgpeerselector/README.md>`__.
+
+On the gluon node both VXLAN and the wgpeerselector are well integrated and no
+explicit configuration of those tools is necessary, once the general WireGuard
+support has been configured.
+
+Attention must by paid to time synchronization. As WireGuard
+performs checks on timestamps in order to avoid replay attacks, time must
+be synchronized before the Mesh VPN connection is established. This means that
+the NTP servers specified in your site.conf must be publicly available (and not
+only through the mesh). Be aware that if you fail this, you may not directly see
+negative effects. Only when a previously connected node reboots the effect
+comes into play, as the gateway still knows about the old timestamp of the gluon
+node.
+
+.. _gluon-mesh-vpn-key-translate:
+
+gluon-mesh-vpn-key-translate
+""""""""""""""""""""""""""""
+
+Many communities already possess a collection of active fastd-keys when they
+plan migrating their community to WireGuard.
+These public keys known on the server-side can be derived into their WireGuard
+equivalent using `gluon-mesh-vpn-key-translate <https://github.com/AiyionPrime/gluon-mesh-vpn-key-translate>`__.
+The routers do the necessary reencoding of the private key seamlessly
+when updating firmware from fastd to the WireGuard variant.
+
+Gateway / Supernode Configuration
+"""""""""""""""""""""""""""""""""
+
+On the gateway side, a software called *wireguard-vxlan-glue* is necessary. It
+is a small daemon that dynamically adds and removes forwarding rules for VXLAN
+interfaces, so traffic is sent correctly into the WireGuard interface. Thereby
+the forwarding rules are only installed if a client is connected, so
+unnecessary traffic in the kernel is avoided. The source can be found
+`here <https://github.com/freifunkh/wireguard-vxlan-glue/>`__.

docs/features/wlan-configuration.rst

+WLAN configuration
+==================
+
+Gluon allows to configure 2.4GHz and 5GHz radios independently. The configuration
+may include one or both of the two networks "client" (AP mode) and "mesh" (802.11s
+mode), which can be used simultaneously. See :doc:`../user/site` for details on the
+configuration.
+
+Upgrade behaviour
+-----------------
+
+For each of these networks, the site configuration may define a `disabled` flag (by
+default, all configured networks are enabled). This flag is merely a default setting,
+on upgrades the existing setting is always retained (as this setting may have been changed
+by the user). This means that it is not possible to enable or disable an existing network
+configurations during upgrades.
+
+During upgrades the wifi channel of the 2.4GHz and 5GHz radio will be restored to the channel
+configured in the site.conf. The channel width will be reset to Gluon's default. If you need to preserve
+these settings during upgrades you can configure this via the uci section ``gluon-core.wireless``::
+
+  uci set gluon.wireless.preserve_channels='1'
+
+When channels should be preserved, toggling the outdoor mode will have no effect on the channel settings.
+Therefore, the Outdoor mode settings won't be displayed in config mode.
+Keep in mind that nodes running wifi interfaces on custom channels can't mesh with default nodes anymore!

docs/multidomain-site-example/i18n

+../site-example/i18n/
\ No newline at end of file

docs/multidomain-site-example/image-customization.lua

+features {
+	'autoupdater',
+	'ebtables-filter-multicast',
+	'ebtables-filter-ra-dhcp',
+	'ebtables-limit-arp',
+	'mesh-batman-adv-15',
+	'mesh-vpn-fastd',
+	'respondd',
+	'status-page',
+	'web-advanced',
+	'web-wizard',
+}
+
+packages {
+	'iwinfo',
+}
+
+if not device_class('tiny') then
+	features {'wireless-encryption-wpa3'}
+end

docs/multidomain-site-example/modules

+../site-example/modules
\ No newline at end of file