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/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/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