Welcome to Gluon

Gluon is a modular framework for creating OpenWrt-based firmware images for wireless mesh nodes. Several Freifunk communities in Germany use Gluon as the foundation of their Freifunk firmware.

Getting Started

Selecting the right version

Gluon’s releases are managed using Git tags. If you are just getting started with Gluon we recommend to use the latest stable release of Gluon.

Take a look at the list of gluon releases and notice the latest release, e.g. v2020.1. Always get Gluon using git and don’t try to download it as a Zip archive as the archive will be missing version information.

Please keep in mind that there is no “default Gluon” build; a site configuration is required to adjust Gluon to your needs. Due to new features being added (or sometimes being removed) the format of the site configuration changes slightly between releases. Please refer to our release notes for instructions to update an old site configuration to a newer release of Gluon.

An example configuration can be found in the Gluon repository at docs/site-example/.

Dependencies

To build Gluon, several packages need to be installed on the system. On a freshly installed Debian Stretch system the following packages are required:

• git (to get Gluon and other dependencies)
• subversion
• python (Python 3 doesn’t work)
• build-essential
• gawk
• unzip
• libncurses-dev (actually libncurses5-dev)
• libz-dev (actually zlib1g-dev)
• libssl-dev
• wget
• time (built-in time doesn’t work)

Building the images

To build Gluon, first check out the repository. Replace RELEASE with the version you’d like to checkout, e.g. v2020.1.

git clone https://github.com/freifunk-gluon/gluon.git gluon -b RELEASE

This command will create a directory named gluon/. It might also tell a scary message about being in a detached state. Don’t panic! Everything’s fine. Now, enter the freshly created directory:

cd gluon

It’s time to add (or create) your site configuration. If you already have a site repository, just clone it:

git clone https://github.com/freifunk-alpha-centauri/site-ffac.git site

If you want to build a new site, create a new git repository site/:

mkdir site
cd site
git init

Copy site.conf, site.mk and i18n from docs/site-example:

cp ../docs/site-example/site.conf .
cp ../docs/site-example/site.mk .
cp -r ../docs/site-example/i18n .

Edit these files as you see fit and commit them into the site repository. Extensive documentation about the site configuration can be found at: Site configuration. The site directory should always be a git repository by itself; committing site-specific files to the Gluon main repository should be avoided, as it will make updates more complicated.

Next go back to the top-level Gluon directory and build Gluon:

cd ..
make update                        # Get other repositories used by Gluon
make GLUON_TARGET=ar71xx-generic   # Build Gluon

In case of errors read the messages carefully and try to fix the stated issues (e.g. install missing tools not available or look for Troubleshooting in the wiki.

ar71xx-generic is the most common target and will generate images for most of the supported hardware. To see a complete list of supported targets, call make without setting GLUON_TARGET.

To build all targets use a loop like this:

for TARGET in $(make list-targets); do
  make GLUON_TARGET=$TARGET
done

You should generally reserve 5GB of disk space and additionally about 10GB for each GLUON_TARGET.

The built images can be found in the directory output/images. Of these, the factory images are to be used when flashing from the original firmware a device came with, and sysupgrade is to upgrade from other versions of Gluon or any other OpenWrt-based system.

Note: The images for some models are identical; to save disk space, symlinks are generated instead of multiple copies of the same image. If your webserver’s configuration prohibits following symlinks, you can use the following command to resolve these links while copying the images:

cp -rL output/images /var/www

Cleaning the build tree

There are two levels of make clean:

make clean GLUON_TARGET=ar71xx-generic

will ensure all packages are rebuilt for a single target. This normally not necessary, but may fix certain kinds of build failures.

make dirclean

will clean the entire tree, so the toolchain will be rebuilt as well, which will take a while.

opkg repositories

Gluon is mostly compatible with OpenWrt, so the normal OpenWrt package repositories can be used for Gluon as well.

This is not true for kernel modules; the Gluon kernel is incompatible with the kernel of the default OpenWrt images. Therefore, Gluon will not only generate images, but also an opkg repository containing all core packages provided by OpenWrt, including modules for the kernel of the generated images.

Signing keys

Gluon does not support HTTPS for downloading packages; fortunately, opkg deploys public-key cryptography to ensure package integrity.

The Gluon images will contain public keys from two sources: the official OpenWrt keyring (to allow installing userspace packages) and a Gluon-specific key (which is used to sign the generated package repository).

OpenWrt will handle the generation and handling of the keys itself. When making firmware releases based on Gluon, it might make sense to store the keypair, so updating the module repository later is possible.

Make variables

Gluon’s build process can be controlled by various variables. They can usually be set on the command line or in site.mk.

Common variables

GLUON_BRANCH

Sets the default branch of the autoupdater. If unset, the autoupdater is disabled by default. For the make manifest command, GLUON_BRANCH defines the branch to generate a manifest for.

GLUON_DEPRECATED

Controls whether images for deprecated devices should be built. The following values are supported:

• 0: Do not build any images for deprecated devices.
• upgrade: Only build sysupgrade images for deprecated devices.
• full: Build both sysupgrade and factory images for deprecated devices.

Usually, devices are deprecated because their flash size is insufficient to support future Gluon versions. The recommended setting is 0 for new sites, and upgrade for existing configurations (where upgrades for existing deployments of low-flash devices are required).

GLUON_LANGS

Space-separated list of languages to include for the config mode/advanced settings. Defaults to en. en should always be included, other supported languages are de and fr.

GLUON_PRIORITY

Defines the priority of an automatic update in make manifest. See Autoupdater for a detailed description of this value.

GLUON_REGION

Some devices (at the moment the TP-Link Archer C7) contain a region code that restricts firmware installations. Set GLUON_REGION to eu or us to make the resulting images installable from the respective stock firmware.

GLUON_RELEASE

Firmware release number: This string is displayed in the config mode, announced via respondd/alfred and used by the autoupdater to decide if a newer version is available. The same GLUON_RELEASE has to be passed to make and make manifest to generate a correct manifest.

GLUON_TARGET

Target architecture to build.

Special variables

GLUON_DEBUG

Setting GLUON_DEBUG=1 will provide firmware images including debugging symbols usable with GDB or similar tools. Requires a device or target with at least 16 MB of flash space, e.g. x86-64. Unset by default.

GLUON_DEVICES

List of devices to build. The list contains the Gluon profile name of a device, the profile name is the first parameter of the device command in a target file. e.g. GLUON_DEVICES="avm-fritz-box-4020 tp-link-tl-wdr4300-v1". Empty by default to build all devices of a target.

GLUON_IMAGEDIR

Path where images will be stored. Defaults to $(GLUON_OUTPUTDIR)/images.

GLUON_PACKAGEDIR

Path where the opkg package repository will be stored. Defaults to $(GLUON_OUTPUTDIR)/packages.

GLUON_OUTPUTDIR

Path where output files will be stored. Defaults to output.

GLUON_SITEDIR

Path to the site configuration. Defaults to site.

Site configuration

The site consists of the files site.conf and site.mk. In the first community based values are defined, which both are processed during the build process and runtime. The last is directly included in the make process of Gluon.

Configuration

The site.conf is a lua dictionary with the following defined keys.

hostname_prefix

A string which shall prefix the default hostname of a device.

site_name

The name of your community.

site_code

The code of your community. It is good practice to use the TLD of your community here.

domain_seed

32 bytes of random data, encoded in hexadecimal, used to seed other random values specific to the mesh domain. It must be the same for all nodes of one mesh, but should be different for firmware that is not supposed to mesh with each other.

The recommended way to generate a value for a new site is:

echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)

prefix4 : optional

The IPv4 Subnet of your community mesh network in CIDR notation, e.g.

prefix4 = '10.111.111.0/18'

Required if next_node.ip4 is set.

prefix6

The IPv6 subnet of your community mesh network, e.g.

prefix6 = 'fdca::ffee:babe:1::/64'

node_prefix6

The ipv6 prefix from which the unique IP-addresses for nodes are selected in babel-based networks. This may overlap with prefix6. e.g.

node_prefix6 = 'fdca::ffee:babe:2::/64'

node_client_prefix6

The ipv6 prefix from which the client-specific IP-address is calculated that is assigned to each node by l3roamd to allow efficient communication when roaming. This is exclusively useful when running a routing mesh protocol like babel. e.g.

node_client_prefix6 = 'fdca::ffee:babe:3::/64'

timezone

The timezone of your community live in, e.g.

-- Europe/Berlin
timezone = 'CET-1CEST,M3.5.0,M10.5.0/3'

ntp_servers

List of NTP servers available in your community or used by your community, e.g.:

ntp_servers = {'1.ntp.services.ffac','2.ntp.services.ffac'}

This NTP servers must be reachable via IPv6 from the nodes. If you don’t want to set an IPv6 address explicitly, but use a hostname (which is recommended), see also the FAQ.

opkg : optional

opkg package manager configuration.

There are two optional fields in the opkg section:

• openwrt overrides the default OpenWrt repository URL. The default URL would correspond to http://downloads.openwrt.org/snapshots/packages/%A and usually doesn’t need to be changed when nodes are expected to have IPv6 internet connectivity.
• extra specifies a table of additional repositories (with arbitrary keys)

opkg = {
  openwrt = 'http://opkg.services.ffac/openwrt/snapshots/packages/%A',
  extra = {
    gluon = 'http://opkg.services.ffac/modules/gluon-%GS-%GR/%S',
  },
}

There are various patterns which can be used in the URLs:

• %d is replaced by the OpenWrt distribution name (“openwrt”)
• %v is replaced by the OpenWrt version number (e.g. “17.01”)
• %S is replaced by the target board (e.g. “ar71xx/generic”)
• %A is replaced by the target architecture (e.g. “mips_24kc”)
• %GS is replaced by the Gluon site code (as specified in site.conf)
• %GV is replaced by the Gluon version
• %GR is replaced by the Gluon release (as specified in site.mk)

regdom : optional

The wireless regulatory domain responsible for your area, e.g.:

regdom = 'DE'

Setting regdom is mandatory if wifi24 or wifi5 is defined.

wifi24 : optional

WLAN configuration for 2.4 GHz devices. channel must be set to a valid wireless channel for your radio.

There are currently two interface types available. You may choose to configure any subset of them:

• ap creates a master interface where clients may connect
• mesh creates an 802.11s mesh interface with forwarding disabled

Each interface may be disabled by setting disabled to true. This will only affect new installations. Upgrades will not change the disabled state.

ap requires a single parameter, a string, named ssid which sets the interface’s ESSID. This is the WiFi the clients connect to.

mesh requires a single parameter, a string, named id which sets the mesh id, also visible as an open WiFi in some network managers. Usually you don’t want users to connect to this mesh-SSID, so use a cryptic id that no one will accidentally mistake for the client WiFi.

mesh also accepts an optional mcast_rate (kbit/s) parameter for setting the multicast bitrate. Increasing the default value of 1000 to something like 12000 is recommended.

wifi24 = {
  channel = 11,
  ap = {
    ssid = 'alpha-centauri.freifunk.net',
  },
  mesh = {
    id = 'ueH3uXjdp',
    mcast_rate = 12000,
  },
},

wifi5 : optional

Same as wifi24 but for the 5Ghz radio.

Additionally a range of channels that are safe to use outsides on the 5 GHz band can be set up through outdoor_chanlist, which allows for a space-separated list of channels and channel ranges, separated by a hyphen. When set this offers the outdoor mode flag for 5 GHz radios in the config mode which reconfigures the AP to select its channel from outdoor chanlist, while respecting regulatory specifications, and disables mesh on that radio. The outdoors option in turn allows to configure when outdoor mode will be enabled. When set to true all 5 GHz radios will use outdoor channels, while on false the outdoor mode will be completely disabled. The default setting is 'preset', which will enable outdoor mode automatically on outdoor-capable devices.

wifi5 = {
  channel = 44,
  outdoor_chanlist = "100-140",

  [...]
},

next_node : package

Configuration of the local node feature of Gluon

next_node = {
  name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
  ip4 = '10.23.42.1',
  ip6 = 'fdca:ffee:babe:1::1',
  mac = '16:41:95:40:f7:dc'
}

All values of this section are optional. If the IPv4 or IPv6 address is omitted, there will be no IPv4 or IPv6 anycast address. The MAC address defaults to 16:41:95:40:f7:dc; this value usually doesn’t need to be changed, but it can be adjusted to match existing deployments that use a different value.

When the nodes’ next-node address is used as a DNS resolver by clients (by passing it via DHCP or router advertisements), it may be useful to allow resolving a next-node hostname without referring to an upstream DNS server (e.g. to allow reaching the node using such a hostname via HTTP or SSH in isolated mesh segments). This is possible by providing one or more names in the name field.

mesh

Configuration of general mesh functionality.

To avoid inter-mesh links, Gluon can encapsulate the mesh protocol in VXLAN for Mesh-on-LAN/WAN. It is recommended to set mesh.vxlan to true to enable VXLAN in new setups. Setting it to false disables this encapsulation to allow meshing with other nodes that don’t support VXLAN (Gluon 2017.1.x and older). In multi-domain setups, mesh.vxlan is optional and defaults to true.

Gluon generally segments layer-2 meshes so that each node becomes IGMP/MLD querier for its own local clients. This is necessary for reliable multicast snooping. The segmentation is realized by preventing IGMP/MLD queries from passing through the mesh. See also gluon-mesh-batman-adv for details.

By default, not only queries are filtered, but also membership report and leave packets, as they add to the background noise of the mesh. As a consequence, snooping switches outside the mesh that are connected to a Gluon node need to be configured to forward all multicast traffic towards the mesh; this is usually not a problem, as such setups are unusual. If you run a special-purpose mesh that requires membership reports to be working, this filtering can be disabled by setting the optional filter_membership_reports value to false.

In addition, options specific to the batman-adv routing protocol can be set in the batman_adv section:

The mandatory value routing_algo selects the batman-adv protocol variant. The following values are supported:

• BATMAN_IV
• BATMAN_V

The optional value gw_sel_class sets the gateway selection class, the default is 20 for B.A.T.M.A.N. IV and 5000 kbit/s for B.A.T.M.A.N. V.

• B.A.T.M.A.N. IV: with the value 20 the gateway is selected based on the link quality (TQ) only; with class 1 it is calculated from both, the TQ and the announced bandwidth.
• B.A.T.M.A.N. V: with the value 1500 the gateway is selected if the throughput is at least 1500 kbit/s faster than the throughput of the currently selected gateway.

For details on determining the threshold, when to switch to a new gateway, see batctl manpage, section “gw_mode”.

mesh = {
  vxlan = true,
  filter_membership_reports = false,
  batman_adv = {
    routing_algo = 'BATMAN_IV',
    gw_sel_class = 1,
  },
}

mesh_vpn

Remote server setup for the mesh VPN.

The enabled option can be set to true to enable the VPN by default. mtu defines the MTU of the VPN interface, determining a proper MTU value is described in the FAQ.

By default the public key of a node’s VPN daemon is not added to announced respondd data; this prevents malicious ISPs from correlating VPN sessions with specific mesh nodes via public respondd data. If this is of no concern in your threat model, this behaviour can be disabled (and thus announcing the public key be enabled) by setting pubkey_privacy to false. At the moment, this option only affects fastd.

The fastd section configures settings specific to the fastd VPN implementation.

If configurable is set to false or unset, the method list will be replaced on updates with the list from the site configuration. Setting configurable to true will allow the user to add the method null to the beginning of the method list or remove null from it, and make this change survive updates. Setting configurable is necessary for the package gluon-web-mesh-vpn-fastd, which adds a UI for this configuration.

In any case, the null method should always be the first method in the list if it is supported at all. You should only set configurable to true if the configured peers support both the null method and methods with encryption.

You can set syslog_level from verbose (default) to warn to reduce syslog output.

The tunneldigger section is used to define the tunneldigger broker list.

Note: It doesn’t make sense to include both fastd and tunneldigger sections in the same configuration file, as only one of the packages gluon-mesh-vpn-fastd and gluon-mesh-vpn-tunneldigger should be installed with the current implementation.

Note: It may be interesting to include the package gluon-iptables-clamp-mss-to-pmtu in the build when using gluon-mesh-babel to work around icmp blackholes on the internet.

mesh_vpn = {
  -- enabled = true,
  mtu = 1312,
  -- pubkey_privacy = true,

  fastd = {
    methods = {'salsa2012+umac'},
    -- configurable = true,
    -- syslog_level = 'warn',
    groups = {
      backbone = {
        -- Limit number of connected peers from this group
        limit = 1,
        peers = {
          peer1 = {
            key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
            -- Having multiple domains prevents SPOF in freifunk.net
            remotes = {
              'ipv4 "vpn1.alpha-centauri.freifunk.net" port 10000',
              'ipv4 "vpn1.alpha-centauri-freifunk.de" port 10000',
            },
          },
          peer2 = {
            key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
            -- You can also omit the ipv4 to allow both connection via ipv4 and ipv6
            remotes = {'"vpn2.alpha-centauri.freifunk.net" port 10000'},
          },
          peer3 = {
            key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
            -- In addition to domains you can also add ip addresses, which provides
            -- resilience in case of dns outages
            remotes = {
              '"vpn3.alpha-centauri.freifunk.net" port 10000',
              '[2001:db8::3:1]:10000',
              '192.0.2.3:10000',
            },
          },
        },
        -- Optional: nested peer groups
        -- groups = {
        --   lowend_backbone = {
        --     limit = 1,
        --     peers = ...
        --   },
        -- },
      },
      -- Optional: additional peer groups, possibly with other limits
      -- peertopeer = {
      --   limit = 10,
      --   peers = { ... },
      -- },
    },
  },

  tunneldigger = {
    brokers = {'vpn1.alpha-centauri.freifunk.net'}
  },

  bandwidth_limit = {
    -- The bandwidth limit can be enabled by default here.
    enabled = false,

    -- Default upload limit (kbit/s).
    egress = 200,

    -- Default download limit (kbit/s).
    ingress = 3000,
  },
}

mesh_on_wan : optional

Enables the mesh on the WAN port (true or false).

mesh_on_wan = true,

mesh_on_lan : optional

Enables the mesh on the LAN port (true or false).

mesh_on_lan = true,

poe_passthrough : optional

Enable PoE passthrough by default on hardware with such a feature.

autoupdater : package

Configuration for the autoupdater feature of Gluon.

The mirrors are checked in random order until the manifest could be downloaded successfully or all mirrors have been tried.

autoupdater = {
  branch = 'stable',
  branches = {
    stable = {
      name = 'stable',
      mirrors = {
        'http://[fdca:ffee:babe:1::fec1]/firmware/stable/sysupgrade/',
        'http://autoupdate.alpha-centauri.freifunk.net/firmware/stable/sysupgrade/',
      },
      -- Number of good signatures required
      good_signatures = 2,
      pubkeys = {
        'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someguy
        'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', -- someother
      }
    }
  }
}

All configured mirrors must be reachable from the nodes via IPv6. If you don’t want to set an IPv6 address explicitly, but use a hostname (which is recommended), see also the FAQ.

config_mode : optional

Additional configuration for the configuration web interface. All values are optional.

When no hostname is specified, a default hostname based on the hostname_prefix and the node’s primary MAC address is assigned. Manually setting a hostname can be enforced by setting hostname.optional to false.

To not prefill the hostname-field in config-mode with the default hostname, set hostname.prefill to false.

By default, no altitude field is shown by the gluon-config-mode-geo-location package. Set geo_location.show_altitude to true if you want the altitude field to be visible.

The geo_location.osm section is only relevant when the gluon-config-mode-geo-location-osm package is used. The center.lon and center.lat values are mandatory in this case and define the default center of the map when no position has been picked yet. The zoom level defaults to 12 in this case. openlayers_url allows to override the base URL of the build/ol.js and css/ol.css files (the default is https://cdn.rawgit.com/openlayers/openlayers.github.io/master/en/v5.2.0).

The remote login page only shows SSH key configuration by default. A password form can be displayed by setting remote_login.show_password_form to true; in this case, remote_login.min_password_length defines the minimum password length.

config_mode = {
  hostname = {
    optional = false,
    prefill = true,
  },
  geo_location = {
    show_altitude = true,
    osm = {
      center = {
        lat = 52.951947558,
        lon = 8.744238281,
      },
      zoom = 13,
      -- openlayers_url = 'http://ffac.example.org/openlayer',
    },
  },
  remote_login = {
    show_password_form = true,
    min_password_length = 10,
  },
},

roles : optional

Optional role definitions. Nodes will announce their role inside the mesh. This will allow in the backend to distinguish between normal, backbone and service nodes or even gateways (if they advertise that role). It is up to the community which roles to define. See the section below as an example. default takes the default role which is set initially. This value should be part of list. If you want node owners to change the role via config mode add the package gluon-web-node-role to site.mk.

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.

roles = {
  default = 'node',
  list = {
    'node',
    'test',
    'backbone',
    'service',
  },
},

setup_mode : package

Allows skipping setup mode (config mode) at first boot when attribute skip is set to true. This is optional and may be left out.

setup_mode = {
  skip = true,
},

Build configuration

The site.mk is a Makefile which defines various values involved in the build process of Gluon.

GLUON_DEPRECATED

Controls whether images for deprecated devices should be built. The following values are supported:

• 0: Do not build any images for deprecated devices.
• upgrade: Only build sysupgrade images for deprecated devices.
• full: Build both sysupgrade and factory images for deprecated devices.

Usually, devices are deprecated because their flash size is insufficient to support future Gluon versions. The recommended setting is 0 for new sites, and upgrade for existing configurations (where upgrades for existing deployments of low-flash devices are required).

GLUON_FEATURES

Defines a list of features to include. The feature list is used to generate the default package set.

GLUON_SITE_PACKAGES

Defines a list of packages which should be installed in addition to the default package set. It is also possible to remove packages from the default set by prepending a minus sign to the package name.

GLUON_RELEASE

The current release version Gluon should use.

GLUON_PRIORITY

The default priority for the generated manifests (see the autoupdater documentation for more information).

GLUON_REGION

Region code to build into images where necessary. Valid values are the empty string, us and eu.

GLUON_LANGS

List of languages (as two-letter-codes) to be included in the web interface. Should always contain en.

Feature flags

With the addition of more and more features that interact in complex ways, it has become necessary to split certain packages into multiple parts, so it is possible to install just what is needed for a specific use case. One example is the package gluon-status-page-mesh-batman-adv: There are batman-adv-specific status page components; they should only be installed when both batman-adv and the status page are enabled, making the addition of a specific package for this combination necessary.

With the ongoing modularization, e.g. for the purpose of supporting new routing protocols, specifying all such split packages in site.mk would soon become very cumbersome: In the future, further components like respondd support or languages might be split off as separate packages, leading to entangled package names like gluon-mesh-vpn-fastd-respondd or gluon-status-page-mesh-batman-adv-i18n-de.

For this reason, we have introduced feature flags, which can be specified in the GLUON_FEATURES variable. These flags allow to specify a set of features on a higher level than individual package names.

Most Gluon packages can simply be specified as feature flags by removing the gluon- prefix: The feature flag corresponding to the package gluon-mesh-batman-adv-15 is mesh-batman-adv-15.

The file package/features in the Gluon repository (or features in site feeds) can specify additional rules for deriving package lists from feature flags, e.g. specifying both status-page and mesh-batman-adv-15 will automatically select the additional package gluon-status-page-mesh-batman-adv. In the future, selecting the flags mesh-vpn-fastd and respondd might automatically enable the additional package gluon-mesh-vpn-fastd-respondd, and enabling status-page and mesh-batman-adv-15 with de in GLUON_LANGS could add the package gluon-status-page-mesh-batman-adv-i18n-de.

In short, it is not necessary anymore to list all the individual packages that are relevant for a firmware; instead, the package list is derived from a list of feature flags using a flexible ruleset defined in the Gluon repo or site package feeds. To some extent, it will even allow us to further modularize existing Gluon packages, without necessitating changes to existing site configurations.

It is still possible to override such automatic rules using GLUON_SITE_PACKAGES (e.g., -gluon-status-page-mesh-batman-adv to remove the automatically added package gluon-status-page-mesh-batman-adv).

For convenience, there are two feature flags that do not directly correspond to a Gluon package:

• web-wizard

  Includes the gluon-config-mode-… base packages (hostname, geolocation and contact info), as well as the gluon-config-mode-autoupdater (when autoupdater is in GLUON_FEATURES), and gluon-config-mode-mesh-vpn (when mesh-vpn-fastd or mesh-vpn-tunneldigger are in GLUON_FEATURES)

• web-advanced

  Includes the gluon-web-… base packages (admin, network, WiFi config), as well as the gluon-web-autoupdater (when autoupdater is in GLUON_FEATURES)

We recommend to use GLUON_SITE_PACKAGES for non-Gluon OpenWrt packages only and completely rely on GLUON_FEATURES for Gluon packages, as it is shown in the example site.mk.

Config mode texts

The community-defined texts in the config mode are configured in PO files in the i18n subdirectory of the site configuration. The message IDs currently defined are:

gluon-config-mode:welcome

Welcome text on the top of the config wizard page.

gluon-config-mode:pubkey

Information about the public VPN key on the reboot page.

gluon-config-mode:novpn

Information shown on the reboot page, if the mesh VPN was not selected.

gluon-config-mode:contact-help

Description for the usage of the contact field

gluon-config-mode:contact-note

Note shown (in small font) below the contact field

gluon-config-mode:hostname-help

Description for the usage of the hostname field

gluon-config-mode:geo-location-help

Description for the usage of the longitude/latitude fields (and altitude, if shown)

gluon-config-mode:altitude-label

Label for the altitude field

gluon-config-mode:reboot

General information shown on the reboot page.

There is a POT file in the site example directory which can be used to create templates for the language files. The command msginit -l en -i ../../docs/site-example/i18n/gluon-site.pot can be used from the i18n directory to create an initial PO file called en.po if the gettext utilities are installed.

Note

An empty msgstr, as is the default after running msginit, leads to the msgid being printed as-is. It does not hide the whole text, as might be expected.

Depending on the context, you might be able to use comments like <!-- empty --> as translations to effectively hide the text.

Site modules

The file modules in the site repository is completely optional and can be used to supply additional package feeds from which packages are built. The git repositories specified here are retrieved in addition to the default feeds when make update is called.

This file’s format is very similar to the toplevel modules file of the Gluon tree, with the important different that the list of feeds must be assigned to the variable GLUON_SITE_FEEDS. Multiple feed names must be separated by spaces, for example:

GLUON_SITE_FEEDS='foo bar'

The feed names may only contain alphanumerical characters, underscores and slashes. For each of the feeds, the following variables are used to specify how to update the feed:

PACKAGES_${feed}_REPO

The URL of the git repository to clone (usually git:// or http(s)://)

PACKAGES_${feed}_COMMIT

The commit ID of the repository to use

PACKAGES_${feed}_BRANCH

Optional: The branch of the repository the given commit ID can be found in. Defaults to the default branch of the repository (usually master)

These variables are always all uppercase, so for an entry foo in GLUON_SITE_FEEDS, the corresponding configuration variables would be PACKAGES_FOO_REPO, PACKAGES_FOO_COMMIT and PACKAGES_FOO_BRANCH. Slashes in feed names are replaced by underscores to get valid shell variable identifiers.

Examples

site.mk

##	gluon site.mk makefile example

##	GLUON_FEATURES
#		Specify Gluon features/packages to enable;
#		Gluon will automatically enable a set of packages
#		depending on the combination of features listed

GLUON_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

##	GLUON_SITE_PACKAGES
#		Specify additional Gluon/OpenWrt packages to include here;
#		A minus sign may be prepended to remove a packages from the
#		selection that would be enabled by default or due to the
#		chosen feature flags

GLUON_SITE_PACKAGES := haveged iwinfo

##	DEFAULT_GLUON_RELEASE
#		version string to use for images
#		gluon relies on
#			opkg compare-versions "$1" '>>' "$2"
#		to decide if a version is newer or not.

DEFAULT_GLUON_RELEASE := 0.6+exp$(shell date '+%Y%m%d')

# Variables set with ?= can be overwritten from the command line

##	GLUON_RELEASE
#		call make with custom GLUON_RELEASE flag, to use your own release version scheme.
#		e.g.:
#			$ make images GLUON_RELEASE=23.42+5
#		would generate images named like this:
#			gluon-ff%site_code%-23.42+5-%router_model%.bin

GLUON_RELEASE ?= $(DEFAULT_GLUON_RELEASE)

# Default priority for updates.
GLUON_PRIORITY ?= 0

# Region code required for some images; supported values: us eu
GLUON_REGION ?= eu

# Languages to include
GLUON_LANGS ?= en de

# Do not build images for deprecated devices
GLUON_DEPRECATED ?= 0

site.conf

-- This is an example site configuration for Gluon v2020.1
--
-- Take a look at the documentation located at
-- https://gluon.readthedocs.io/ for details.
--
-- This configuration will not work as is. You're required to make
-- community specific changes to it!
{
  -- Used for generated hostnames, e.g. freifunk-abcdef123456. (optional)
  -- hostname_prefix = 'freifunk-',

  -- Name of the community.
  site_name = 'Freifunk Alpha Centauri',

  -- Shorthand of the community.
  site_code = 'ffxx',

  -- 32 bytes of random data, encoded in hexadecimal
  -- This data must be unique among all sites and domains!
  -- Can be generated using: echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
  domain_seed = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',

  -- Prefixes used within the mesh.
  -- prefix6 is required, prefix4 can be omitted if next_node.ip4
  -- is not set.
  prefix4 = '10.xxx.0.0/20',
  prefix6 = 'fdxx:xxxx:xxxx::/64',

  -- Timezone of your community.
  -- See https://openwrt.org/docs/guide-user/base-system/system_configuration#time_zones
  timezone = 'CET-1CEST,M3.5.0,M10.5.0/3',

  -- List of NTP servers in your community.
  -- Must be reachable using IPv6!
  ntp_servers = {'1.ntp.services.ffxx'},

  -- Wireless regulatory domain of your community.
  regdom = 'DE',

  -- Wireless configuration for 2.4 GHz interfaces.
  wifi24 = {
    -- Wireless channel.
    channel = 1,

    -- ESSID used for client network.
    ap = {
      ssid = 'alpha-centauri.freifunk.net',
      -- disabled = true, -- (optional)
    },

    mesh = {
      -- Adjust these values!
      id = 'ueH3uXjdp', -- usually you don't want users to connect to this mesh-SSID, so use a cryptic id that no one will accidentally mistake for the client WiFi
      mcast_rate = 12000,
      -- disabled = true, -- (optional)
    },
  },

  -- Wireless configuration for 5 GHz interfaces.
  -- This should be equal to the 2.4 GHz variant, except
  -- for channel.
  wifi5 = {
    channel = 44,
    outdoor_chanlist = '100-140',
    ap = {
      ssid = 'alpha-centauri.freifunk.net',
    },
    mesh = {
      -- Adjust these values!
      id = 'ueH3uXjdp',
      mcast_rate = 12000,
    },
  },

  mesh = {
    vxlan = true,
    batman_adv = {
      routing_algo = 'BATMAN_IV',
    },
  },

  -- The next node feature allows clients to always reach the node it is
  -- connected to using a known IP address.
  next_node = {
    -- anycast IPs of all nodes
    -- name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
    ip4 = '10.xxx.0.xxx',
    ip6 = 'fdxx:xxxx:xxxx::xxxx',
  },

  -- Options specific to routing protocols (optional)
  -- mesh = {
    -- Options specific to the batman-adv routing protocol (optional)
    -- batman_adv = {
      -- Gateway selection class (optional)
      -- The default class 20 is based on the link quality (TQ) only,
      -- class 1 is calculated from both the TQ and the announced bandwidth
      -- gw_sel_class = 1,
    -- },
  -- },

  mesh_vpn = {
    -- enabled = true,
    mtu = 1312,

    fastd = {
      -- Refer to https://fastd.readthedocs.io/en/latest/ to better understand
      -- what these options do.

      -- List of crypto-methods to use.
      methods = {'salsa2012+umac'},
      -- configurable = true,
      -- syslog_level = 'warn',

      groups = {
        backbone = {
          -- Limit number of connected peers to reduce bandwidth.
          limit = 1,

          -- List of peers.
          peers = {
            peer1 = {
              key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',

              -- This is a list, so you might add multiple entries.
              remotes = {'ipv4 "xxx.somehost.invalid" port xxxxxx'},
            },
            peer2 = {
              key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
              -- You can also omit the ipv4 to allow both connection via ipv4 and ipv6
              remotes = {'"xxx.somehost2.invalid" port xxxxx'},
            },
          },

          -- Optional: nested peer groups
          -- groups = {
            -- backbone_sub = {
              -- ...
            -- },
          -- ...
          -- },
        },
        -- Optional: additional peer groups, possibly with other limits
        -- backbone2 = {
          -- ...
        -- },
      },
    },

    bandwidth_limit = {
      -- The bandwidth limit can be enabled by default here.
      enabled = false,

      -- Default upload limit (kbit/s).
      egress = 200,

      -- Default download limit (kbit/s).
      ingress = 3000,
    },
  },

  autoupdater = {
    -- Default branch. Don't forget to set GLUON_BRANCH when building!
    branch = 'stable',

    -- List of branches. You may define multiple branches.
    branches = {
      stable = {
        name = 'stable',

        -- List of mirrors to fetch images from. IPv6 required!
        mirrors = {'http://1.updates.services.ffhl/stable/sysupgrade'},

        -- Number of good signatures required.
        -- Have multiple maintainers sign your build and only
        -- accept it when a sufficient number of them have
        -- signed it.
        good_signatures = 2,

        -- List of public keys of maintainers.
        pubkeys = {
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Bob
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Mary
        },
      },
    },
  },
}

i18n/en.po

msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Project-Id-Version: PACKAGE VERSION\n"
"PO-Revision-Date: 2016-02-04 14:28+0100\n"
"Last-Translator: David Lutz <kpanic@hirnduenger.de>\n"
"Language-Team: English\n"
"Language: en\n"
"MIME-Version: 1.0\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

msgid "gluon-config-mode:welcome"
msgstr ""
"Welcome to the setup wizard of your new Freifunk Alpha Centauri node. Please "
"fill out the following form and submit it."

msgid "gluon-config-mode:domain"
msgstr "Domain"

msgid "gluon-config-mode:domain-select"
msgstr ""
"Here you have the possibility of selecting the mesh domain in which your node "
"is placed. Please keep in mind that your router only connects with the nodes "
"of the selected domain."

msgid "gluon-config-mode:pubkey"
msgstr ""
"<p>This is your Freifunk node's public key. The node won't be able to "
"connect to the mesh VPN until the key has been registered on the Freifunk "
"servers. To register, send the key together with your node's name "
"(<em><%=pcdata(hostname)%></em>) to "
"<a href=\"mailto:keys@alpha-centauri.freifunk.net?subject="
"<%= urlencode('Registration: ' .. hostname) %>&amp;body="
"<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\nkey ') %>"
"%22<%= pubkey %>%22;"
"<%= urlencode('\n\nI have taken note that the contact I entered in the ') %>"
"<%= urlencode('node is publicly available on the Internet and can be ') %>"
"<%= urlencode('used by any services (e.g. the meshviewer map).') %>"
"<%= urlencode('\n\nThanks, \n\n') %>"
"\">keys@alpha-centauri.freifunk.net</a>. Of course, your e-mail address will "
"be treated confidentially and will not be passed on.</p>"
"<div class=\"the-key\">"
" # <%= pcdata(hostname) %><br />"
"<%= pubkey %>"
"</div>"
"<p>Your node <em><%= pcdata(hostname) %></em> is currently rebooting and will "
"try to connect to other nearby Freifunk nodes via WLAN and to a VPN-gateway "
"via your internet connection after the reboot is finished.</p>"
"<p>Don't forget to plug the network cable from the LAN port to the WAN port."
"</p>"

msgid "gluon-config-mode:novpn"
msgstr ""
"<p>You have selected <strong>not</strong> to use the mesh VPN. "
"Your node will only be able to connect to the Freifunk network if other nodes "
"in reach already have a connection.</p>"
"Please send an e-mail with the name of your node "
"(<em><%=pcdata(hostname)%></em>) and some additional information to "
"<a href=\"mailto:keys@alpha-centauri.freifunk.net?subject="
"<%= urlencode('Registration: ' .. hostname) %>&amp;body="
"<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\nkey ') %>"
"%22<%= pubkey %>%22;"
"<%= urlencode('\n\nI have taken note that the contact I entered in the ') %>"
"<%= urlencode('node is publicly available on the Internet and can be ') %>"
"<%= urlencode('used by any services (e.g. the meshviewer map).') %>"
"<%= urlencode('\n\nThanks, \n\n') %>"
"\">keys@alpha-centauri.freifunk.net</a>. Of course, your e-mail address will "
"be treated confidentially and will not be passed on.</p>"
"<p>Your node <em><%= pcdata(hostname) %></em> is currently rebooting and will "
"try to connect to other nearby Freifunk nodes after that.</p>"

msgid "gluon-config-mode:reboot"
msgstr ""
"<p>For more information about the Freifunk community on Alpha Centauri, have a "
"look at <a href=\"https://alpha-centauri.freifunk.net/\" target=\"_blank\">our "
"homepage</a>.</p>"
"<p>To get back to this configuration interface, press the reset button for "
"about 10 seconds during normal operation. The device will then reboot into "
"config mode.</p>"
"<p>Have fun with your node and exploring of the Freifunk network!</p>"

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-hostname/i18n/
msgid "gluon-config-mode:hostname-help"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-geo-location/i18n/
msgid "gluon-config-mode:geo-location-help"
msgstr ""

msgid "gluon-config-mode:altitude-label"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-contact-info/i18n/
msgid "gluon-config-mode:contact-help"
msgstr ""

msgid "gluon-config-mode:contact-note"
msgstr ""

i18n/de.po

msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Project-Id-Version: PACKAGE VERSION\n"
"PO-Revision-Date: 2015-03-19 20:28+0100\n"
"Last-Translator: Matthias Schiffer <mschiffer@universe-factory.net>\n"
"Language-Team: German\n"
"Language: de\n"
"MIME-Version: 1.0\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

msgid "gluon-config-mode:welcome"
msgstr ""
"Willkommen zum Einrichtungsassistenten für deinen neuen Alpha Centauri "
"Freifunk-Knoten. Fülle das folgende Formular deinen Vorstellungen "
"entsprechend aus und sende es ab."

msgid "gluon-config-mode:domain"
msgstr "Domäne"

msgid "gluon-config-mode:domain-select"
msgstr ""
"Hier hast du die Möglichkeit, die Mesh-Domäne, in der sich dein Knoten "
"befindet, auszuwählen. Bitte denke daran, dass sich dein Knoten nur mit den "
"Knoten der ausgewählten Domäne verbinden kann."

msgid "gluon-config-mode:pubkey"
msgstr ""
"<p>Dies ist der öffentliche Schlüssel deines Freifunk-Knotens. Erst nachdem "
"er auf den Servern des Freifunk-Projektes auf Alpha Centauri eingetragen "
"wurde, kann sich dein Knoten mit dem Mesh-VPN dort verbinden. Bitte schicke "
"dazu diesen Schlüssel und den Namen deines Knotens "
"(<em><%=pcdata(hostname)%></em>) an "
"<a href=\"mailto:keys@alpha-centauri.freifunk.net?subject="
"<%= urlencode('Anmeldung: ' .. hostname) %>&amp;body="
"<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\nkey ') %>"
"%22<%= pubkey %>%22;"
"<%= urlencode('\n\nIch habe zur Kenntnis genommen, dass der im ') %>"
"<%= urlencode('Knoten von mir eingetragene Kontakt im Meshnetz ') %>"
"<%= urlencode('öffentlich abfragbar ist und von beliebigen Diensten ') %>"
"<%= urlencode('(z.B. der Freifunk-Karte) veröffentlicht werden kann.') %>"
"<%= urlencode('\n\nGruß, \n\n') %>"
"\">keys@alpha-centauri.freifunk.net</a>. Deine E-Mail Adresse wird "
"selbstverständlich vertraulich behandelt und nicht weitergegeben."
"</p>"
"<div class=\"the-key\">"
"# <%= pcdata(hostname) %><br />"
"<%= pubkey %>"
"</div>"
"<p>Dein Knoten startet gerade neu und wird anschließend versuchen, sich mit "
"anderen Freifunkknoten in seiner Nähe über WLAN sowie über deine"
"Internetverbindung über das VPN-Gateway zu verbinden.</p>"
"<p>Vergiss nicht das Netzwerkkabel vom LAN Port in den WAN Port "
"umzustecken.</p>"

msgid "gluon-config-mode:novpn"
msgstr ""
"<p><strong>Du hast ausgewählt die Internetverbindung (Mesh-VPN) nicht zu "
"nutzen</strong>. Dein Knoten kann also nur dann eine Verbindung zum "
"Freifunk-Netz aufbauen, wenn andere Freifunk-Knoten in WLAN-Reichweite sind."
"<p>Bitte schicke uns eine E-Mail mit dem Namen deines Knotens "
"(<em><%= pcdata(hostname) %></em>) und ein paar Informationen an <a href="
"\"mailto:freifunk-keys@lists.in-kiel.de?"
"subject=<%= urlencode('Anmeldung: ' .. hostname) %>&amp;"
"body=<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\n# kein mesh-VPN') %>"
"<%= urlencode('\n\nIch habe zur Kenntnis genommen, dass der im ') %>"
"<%= urlencode('Knoten von mir eingetragene Kontakt im Meshnetz ') %>"
"<%= urlencode('öffentlich abfragbar ist und von beliebigen Diensten ') %>"
"<%= urlencode('(z.B. der Freifunk-Karte) veröffentlicht werden kann.') %>"
"<%= urlencode('\n\nGruß, \n\n') %>"
"\">kontakt@alpha-centauri.freifunk.net</a>. Deine E-Mail Adresse wird "
"selbstverständlich vertraulich behandelt und nicht weitergegeben.</p>"
"<p>Dein Knoten <em><%= pcdata(hostname) %></em> startet gerade neu und wird "
"anschließend versuchen, sich mit anderen Freifunkknoten in seiner Nähe über "
"WLAN zu verbinden.</p>"

msgid "gluon-config-mode:reboot"
msgstr ""
"<p>Weitere Informationen zur "
"Alpha Centauri Freifunk-Community findest du auf "
"<a href=\"https://alpha-centauri.freifunk.net/\" target=\"_blank\">unserer "
"Webseite</a>.</p>"
"<p>Um zu dieser Konfigurationsseite zurückzugelangen, drücke im normalen "
"Betrieb für ca. 10 Sekunden den Reset-Button. Das Gerät wird dann im Config "
"Mode neustarten.</p>"
"<p>Viel Spaß mit deinem Knoten und der Erkundung von Freifunk!</p>"

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-hostname/i18n/
msgid "gluon-config-mode:hostname-help"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-geo-location/i18n/
msgid "gluon-config-mode:geo-location-help"
msgstr ""

msgid "gluon-config-mode:altitude-label"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-contact-info/i18n/
msgid "gluon-config-mode:contact-help"
msgstr ""

msgid "gluon-config-mode:contact-note"
msgstr ""

modules

# This file allows specifying additional repositories to use
# when building gluon.
#
# In most cases, it is not required so don't add it.

##	GLUON_SITE_FEEDS
#		for each feed name given, add the corresponding PACKAGES_* lines
#		documented below
#GLUON_SITE_FEEDS='my_own_packages'

##	PACKAGES_$feedname_REPO
#		the  git repository from where to clone the package feed
#PACKAGES_MY_OWN_PACKAGES_REPO=https://github.com/.../my-own-packages.git


##	PACKAGES_$feedname_COMMIT
#		the version/commit of the git repository to clone
#PACKAGES_MY_OWN_PACKAGES_COMMIT=123456789aabcda1a69b04278e4d38f2a3f57e49

##  PACKAGES_$feedname_BRANCH
#   the branch to check out
#PACKAGES_MY_OWN_PACKAGES_BRANCH=my_branch

site-repos in the wild

A non-exhaustive list of site-repos from various communities can be found on the wiki: https://github.com/freifunk-gluon/gluon/wiki/Site-Configurations

Supported Devices & Architectures

ar71xx-generic

• 8devices
  • Carambola 2
• ALFA Network
  • AP121 [1]
  • AP121F
  • AP121U [1]
• Allnet
  • ALL0315N
• AVM
  • Fritz!Box 4020 [2]
  • Fritz!WLAN Repeater 300E [2]
  • Fritz!WLAN Repeater 450E [2]
• Buffalo
  • WZR-HP-AG300H / WZR-600DHP
  • WZR-HP-G300NH
  • WZR-HP-G300NH2
  • WZR-HP-G450H
• D-Link
  • DAP-1330 (A1)
  • DIR-505 (A1, A2)
  • DIR-825 (B1)
• GL.iNet
  • 6408A
  • 6416A
  • GL-AR150
  • GL-AR300M
  • GL-AR750
• Linksys
  • WRT160NL
• Netgear
  • WNDR3700 (v1, v2)
  • WNDR3800
  • WNDRMAC (v2)
• OCEDO
  • Koala
• OpenMesh
  • A40
  • A60
  • MR600 (v1, v2)
  • MR900 (v1, v2)
  • MR1750 (v1, v2)
  • OM2P (v1, v2, v4)
  • OM2P-HS (v1, v2, v3, v4)
  • OM2P-LC
  • OM5P
  • OM5P-AN
  • OM5P-AC (v1, v2)
• TP-Link
  • Archer C5 (v1)
  • Archer C59 (v1)
  • Archer C7 (v2, v4, v5)
  • CPE210 (v1.0, v1.1, v2.0, v3.0)
  • CPE220 (v1.1)
  • CPE510 (v1.0, v1.1)
  • CPE520 (v1.1)
  • RE450 (v1)
  • TL-WDR3500 (v1)
  • TL-WDR3600 (v1)
  • TL-WDR4300 (v1)
  • TL-WR710N (v1, v2.1)
  • TL-WR810N (v1)
  • TL-WR842N/ND (v1, v2, v3)
  • TL-WR1043N/ND (v1, v2, v3, v4, v5)
  • TL-WR2543N/ND (v1)
  • WBS210 (v1.20)
  • WBS510 (v1.20)
• Ubiquiti
  • Air Gateway
  • Air Gateway LR
  • Air Gateway PRO
  • Air Router
  • Bullet M2/M5
  • Loco M2/M5
  • Loco M2/M5 XW
  • Nanostation M2/M5
  • Nanostation M2/M5 XW
  • Picostation M2
  • Rocket M2/M5
  • Rocket M2/M5 Ti
  • Rocket M2/M5 XW
  • UniFi AC Mesh
  • UniFi AC Mesh Pro
  • UniFi AP
  • UniFi AP AC Lite
  • UniFi AP AC LR
  • UniFi AP AC Pro
  • UniFi AP LR
  • UniFi AP Pro
  • UniFi AP Outdoor
  • UniFi AP Outdoor+
• Western Digital
  • My Net N600
  • My Net N750
• ZyXEL
  • NBG6616

ar71xx-nand

• Aerohive
  • HiveAP 121
• Netgear
  • WNDR3700 (v4)
  • WNDR4300 (v1)
• ZyXEL
  • NBG6716

ar71xx-tiny [1]

• D-Link
  • DIR-615 (C1)
• TP-Link
  • TL-MR13U (v1)
  • TL-MR3020 (v1)
  • TL-MR3040 (v1, v2)
  • TL-MR3220 (v1, v2)
  • TL-MR3420 (v1, v2)
  • TL-WA701N/ND (v1, v2)
  • TL-WA730RE (v1)
  • TL-WA750RE (v1)
  • TL-WA801N/ND (v1, v2, v3)
  • TL-WA830RE (v1, v2)
  • TL-WA850RE (v1)
  • TL-WA860RE (v1)
  • TL-WA901N/ND (v1, v2, v3, v4, v5)
  • TL-WA7210N (v2)
  • TL-WA7510N (v1)
  • TL-WR703N (v1)
  • TL-WR710N (v2)
  • TL-WR740N (v1, v3, v4, v5)
  • TL-WR741N/ND (v1, v2, v4, v5)
  • TL-WR743N/ND (v1, v2)
  • TL-WR840N (v2)
  • TL-WR841N/ND (v3, v5, v7, v8, v9, v10, v11, v12)
  • TL-WR843N/ND (v1)
  • TL-WR940N (v1, v2, v3, v4, v5, v6)
  • TL-WR941ND (v2, v3, v4, v5, v6)

ath79-generic

• devolo
  • WiFi pro 1200e [4]
  • WiFi pro 1200i
  • WiFi pro 1750c
  • WiFi pro 1750e [4]
  • WiFi pro 1750i
  • WiFi pro 1750x
• GL.iNet
  • GL-AR300M-Lite
• OCEDO
  • Raccoon
• TP-Link
  • Archer C6 (v2)

brcm2708-bcm2708

• RaspberryPi 1

brcm2708-bcm2709

• RaspberryPi 2

ipq40xx-generic

• AVM
  • FRITZ!Box 4040 [2]
  • FRITZ!Repeater 1200 [3]
• GL.iNet
  • GL-B1300
• NETGEAR
  • EX6100 (v2)
  • EX6150 (v2)
• OpenMesh
  • A42
  • A62
• ZyXEL
  • NBG6617
  • WRE6606

ipq806x-generic

• NETGEAR
  • R7800

lantiq-xrx200

• AVM
  • FRITZ!Box 7360 (v1, v2) [2] [4]
  • FRITZ!Box 7360 SL [2] [4]
  • FRITZ!Box 7362 SL [3] [4]
  • FRITZ!Box 7412 [3]

lantiq-xway

• AVM
  • FRITZ!Box 7312 [2]
  • FRITZ!Box 7320 [2] [4]
  • FRITZ!Box 7330 [2] [4]
  • FRITZ!Box 7330 SL [2] [4]

mpc85xx-generic

• TP-Link
  • TL-WDR4900 (v1)

mpc85xx-p1020

• Aerohive
  • HiveAP 330
• Enterasys
  • WS-AP3710i
• OCEDO
  • Panda

ramips-mt7620

• GL.iNet
  • GL-MT300A
  • GL-MT300N
  • GL-MT750
• Nexx
  • WT3020AD/F/H
• TP-Link
  • Archer C2 v1
  • Archer C20 (v1)
  • Archer C20i
  • Archer C50 v1
• Xiaomi
  • MiWiFi Mini

ramips-mt7621

• ASUS
  • RT-AC57U
• D-Link
  • DIR-860L (B1)
• NETGEAR
  • EX6150 (v1)
  • R6220
• Ubiquiti
  • EdgeRouter X
  • EdgeRouter X-SFP
• ZBT
  • WG3526-16M
  • WG3526-32M

ramips-mt76x8

• GL.iNet
  • GL-MT300N v2
  • VIXMINI
• NETGEAR
  • R6120
• TP-Link
  • Archer C50 v3
  • Archer C50 v4
  • TL-MR3020 v3
  • TL-MR3420 v5
  • TL-WA801ND v5
  • TL-WR841N v13
  • TL-WR902AC v3
• VoCore
  • VoCore2

ramips-rt305x [1]

• A5-V11
• D-Link
  • DIR-615 (D1, D2, D3, D4, H1)
• VoCore
  • VoCore (8M, 16M)

sunxi-cortexa7

• LeMaker
  • Banana Pi M1

x86-generic

• x86-generic
• x86-virtualbox
• x86-vmware

See also: x86 support

x86-geode

• x86-geode

See also: x86 support

x86-64

• x86-64-generic
• x86-64-virtualbox
• x86-64-vmware

See also: x86 support

Footnotes

[1]	(1, 2, 3, 4) The device or target is reaching its end of life soon. This means that support in the next major release of Gluon is doubtful.

[2]	(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) For instructions on how to flash AVM devices, visit https://fritzfla.sh

[3]	(1, 2, 3) For instructions on how to flash AVM NAND devices, see the respective commit which added support in OpenWrt.

[4]	(1, 2, 3, 4, 5, 6, 7, 8) All LAN ports on this device are used as WAN.

x86 support

Gluon can run on normal x86 systems, for example virtual machines and VPN boxes. By default, there is no WLAN support on x86 though.

Targets

The following targets for x86 images exist:

x86-generic

Generic x86 support with many different ethernet drivers; should run on most x86 systems.

There are three images:

• generic (compressed “raw” image, can written to a disk directly or booted with qemu)
• virtualbox (VDI image)
• vmware (VMDK image)

These images differ in the image file format, the content is the same. Therefore a single x86-generic sysupgrade image is provided, only.

x86-geode

x86 image for Geode CPUs.

x86-64

64bit version of x86-generic.

Frequently Asked Questions

What hardware is supported?

A table with hardware supported by Gluon can be found on the OpenWrt Wiki. If you want to find out if your device can potentially be supported have a look at Adding support for new hardware for detailed hardware requirements.

Why does DNS not work on the nodes?

Gluon nodes will ignore the DNS server on the WAN port for everything except the mesh VPN, which can lead to confusion.

All normal services on the nodes exclusively use the DNS server on the mesh interface. This DNS server must be announced in router advertisements (using radvd or a similar software) from one or more central servers in meshes based on batman-adv. If your mesh does not have global IPv6 connectivity, you can setup your radvd not to announce a default route by setting the default lifetime to 0; in this case, the radvd is only used to announce the DNS server.

What is a good MTU on the mesh-vpn?

Setting the MTU on the transport interface requires careful consideration, as setting it too low will cause excessive fragmentation and setting it too high may leave peers with a broken tunnel due to packet loss.

Consider these key values:

• Payload: Allow for the transport of IPv6 packets, by adhering to the minimum MTU of 1280 Byte specified in RFC 2460 - and configure MSS clamping accordingly, - and announce your link MTU via Router Advertisements and DHCP
• Encapsulation: Account for the overhead created by the configured mesh protocol encapsulating the payload, which is up to 32 Byte (14 Byte Ethernet + 18 Byte batadv).
• PMTU: What MTU does the path between your gateway and each of its peers support?

For reference, the complete MTU stack looks like this:

Minimum MTU

Calculate the minimum transport MTU by adding the encapsulation overhead to the minimum payload MTU required. This is the lowest recommended value, since going lower would cause unnecessary fragmentation for clients which respect the announced link MTU.

Example: Our network currently uses batman-adv v15, it therefore requires up to 32 Bytes of encapsulation overhead on top of the minimal link MTU required for transporting IPv6.:

\        1312              1294          1280                                 0
 \---------+-----------------+-------------+----------------------------------+
  \TAP     |    batadv v15   |   Ethernet  |            Payload               |
   \-------+-----------------+-------------+----------------------------------+
    \      ^
           |

        MTU_LOW = 1280 Byte + 14 Byte + 18 Byte = 1312 Byte

Maximum MTU

Calculating the maximum transport MTU is interesting, because it increases the throughput, by allowing larger payloads to be transported, but also more difficult as you have to take into account the tunneling overhead and each peers PMTU, which varies between providers. The underlying reasons are mostly PPPoE, Tunneling and IPv6 transition technologies like DS-Lite.

Example: The peer with the smallest MTU on your network is behind DS-Lite and can transport IPv4 packets up to 1436 Bytes in size. Your tunnel uses IPv4 (20 Byte), UDP (8 Byte), Fastd (24 byte) and you require TAP (14 Byte) for Layer 2 (Ethernet) Tunneling.:

1436                1416     1408                    1384          1370    \
  +-------------------+--------+-----------------------+-------------+------\
  |        IP         |  UDP   |         Fastd         |     TAP     |    bat\
  +-------------------+--------+-----------------------+-------------+--------\
                                                                     ^         \
                                                                     |

     MTU_HIGH = 1436 Byte - 20 Byte - 8 Byte - 24 Byte - 14 Byte = 1370 Byte

Conclusion

Determining the maximum MTU can be a tedious process, especially since the PMTU of peers could change at any time. The general recommendation for maximized compatibility is therefore the minimum MTU of 1312 Byte, which works well with both IPv4 and IPv6.

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:

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.

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.

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_BRANCH when building to override the default branch set in the site configuration.

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.

Automated nightly builds

A fully automated nightly build could use the following commands:

git pull
(git -C site pull)
make update
make clean GLUON_TARGET=ar71xx-generic
NUM_CORES_PLUS_ONE=$(expr $(nproc) + 1)
make -j$NUM_CORES_PLUS_ONE GLUON_TARGET=ar71xx-generic GLUON_BRANCH=experimental GLUON_RELEASE=$GLUON_RELEASE
make manifest GLUON_BRANCH=experimental GLUON_RELEASE=$GLUON_RELEASE
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

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 Site configuration 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. If you need to preserve a user defined wifi channel during upgrades you can configure this via the uci section gluon-core.wireless:

uci set gluon-core.@wireless[0].preserve_channels='1'

Keep in mind that nodes running wifi interfaces on custom channels can’t mesh with default nodes anymore!

Private WLAN

It is possible to set up a private WLAN that bridges the WAN port and is separated from the mesh network. Please note that you should not enable mesh_on_wan simultaneously.

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

Wired mesh (Mesh-on-WAN/LAN)

In addition to meshing over WLAN and VPN, it is also possible to configure wired meshing over the LAN or WAN ports. This allows nodes to be connected directly or over wireless bridges.

Mesh-on-WAN can be enabled in addition to the mesh VPN, so multiple nodes in the same local network that is used as VPN uplink can also mesh directly. Enabling Mesh-on-WAN should be avoided if the local network is also bridged with a WLAN access point, as meshing over batman-adv causes large amounts of multicast traffic, which will take up a lot of airtime.

Enabling Mesh-on-LAN replaces the normal “client network” function of the LAN ports, as client network ports may never be connected (so care must be taken to always enable Mesh-on-LAN before connecting two nodes’ LAN ports).

Wired mesh encapsulation

Since version 2018.1, Gluon supports encapsulating wired mesh traffic in VXLAN, a new standard with use cases similar to VLANs, but a much greater ID space of 24bit; in addition, VXLAN packets pass through VLAN-aware switches without any special configuration.

Encapsulating mesh traffic has two advantages:

• By using a different VXLAN ID for each site and mesh domain, accidental wired mesh connections between nodes of different domains will be prevented. This has special importance when nodes migrate between domains automatically, as currently possible through different site-specific packages.
• While batman-adv traffic does not interact with non-mesh traffic in the same wired network in any way (so Gluon nodes can mesh over existing wired networks), this is not the case for layer 3 mesh protocols like Babel. Encapsulating the traffic allows to distinguish mesh traffic from unrelated packets.

As enabling VXLAN encapsulation will prevent wired mesh communication with old nodes that do not support VXLAN yet, VXLANs can be enabled per-domain using the site configuration setting mesh.vxlan. VXLAN is enabled by default in multidomain setups; in single-domain site configurations, the mesh.vxlan setting is mandatory. We recommend to enable VXLAN encapsulation in all new sites and domains.

Non-encapsulated (“legacy”) wired meshing will be removed in a future Gluon release. We cannot give a concrete timeframe for the removal yet; a missing prerequisite is the implementation of a robust migration path for existing deployments.

Configuration

Both Mesh-on-WAN and Mesh-on-LAN can be configured on the “Network” page of the Advanced settings (if the package gluon-web-network is installed).

It is also possible to enable Mesh-on-WAN and Mesh-on-LAN by default by adding mesh_on_wan = true and mesh_on_lan = true to site.conf.

Commandline

Enable Mesh-on-WAN:

uci set network.mesh_wan.disabled=0
uci commit network

Disable Mesh-on-WAN:

uci set network.mesh_wan.disabled=1
uci commit network

Enable Mesh-on-LAN:

uci set network.mesh_lan.disabled=0
for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
  uci del_list network.client.ifname=$ifname
done
uci commit network

Disable Mesh-on-LAN:

uci set network.mesh_lan.disabled=1
for ifname in $(cat /lib/gluon/core/sysconfig/lan_ifname); do
  uci add_list network.client.ifname=$ifname
done
uci commit network

Please note that this configuration has changed in Gluon 2016.1. Using the old commands on 2016.1 and later will break the corresponding options in the Advanced settings.

DNS forwarder

A Gluon node can be configured to act as a DNS forwarder. Requests for the next-node hostname(s) can be answered locally, without querying the upstream resolver.

Note: While this reduces answer time and allows to use the next-node hostname without upstream connectivity, this feature should not be used for next-node hostnames that are FQDN when the zone uses DNSSEC.

One or more upstream resolvers can be configured in the dns.servers setting. When next_node.name is set, A and/or AAAA records for the next-node IP addresses are placed in the dnsmasq configuration.

dns = {
  servers = { '2001:db8::1', },
},

next_node = {
  name = { 'nextnode.location.community.example.org', 'nextnode', 'nn' },
  ip6 = '2001:db8:8::1',
  ip4 = '198.51.100.1',
}

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 (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.

The following datatypes 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.

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 and have a look the existing providers.

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:

uci set gluon.core.domain="newdomaincode"
gluon-reconfigure
reboot

via config mode:

To allow switching the domain via config mode, config-mode-domain-select has to be added to GLUON_FEATURES in the site.mk.

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
  • mesh_on_wan
  • mesh_on_lan
  • single_as_lan
  • 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 as an own 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

##	gluon site.mk makefile example

##	GLUON_FEATURES
#		Specify Gluon features/packages to enable;
#		Gluon will automatically enable a set of packages
#		depending on the combination of features listed

GLUON_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

##	GLUON_MULTIDOMAIN
#		Build gluon with multidomain support.

GLUON_MULTIDOMAIN=1

##	GLUON_SITE_PACKAGES
#		Specify additional Gluon/LEDE packages to include here;
#		A minus sign may be prepended to remove a packages from the
#		selection that would be enabled by default or due to the
#		chosen feature flags


GLUON_SITE_PACKAGES := haveged iwinfo

##	DEFAULT_GLUON_RELEASE
#		version string to use for images
#		gluon relies on
#			opkg compare-versions "$1" '>>' "$2"
#		to decide if a version is newer or not.

DEFAULT_GLUON_RELEASE := 0.6+exp$(shell date '+%Y%m%d')

# Variables set with ?= can be overwritten from the command line

##	GLUON_RELEASE
#		call make with custom GLUON_RELEASE flag, to use your own release version scheme.
#		e.g.:
#			$ make images GLUON_RELEASE=23.42+5
#		would generate images named like this:
#			gluon-ff%site_code%-23.42+5-%router_model%.bin

GLUON_RELEASE ?= $(DEFAULT_GLUON_RELEASE)

# Default priority for updates.
GLUON_PRIORITY ?= 0

# Region code required for some images; supported values: us eu
GLUON_REGION ?= eu

# Languages to include
GLUON_LANGS ?= en de

# Do not build images for deprecated devices
GLUON_DEPRECATED ?= 0

site.conf

{
  site_name = 'Centauri Mesh',
  site_code = 'centauri',
  default_domain = 'alpha_centauri',

  timezone = 'CET-1CEST,M3.5.0,M10.5.0/3',
  ntp_server = {'ntp1.example.org', 'ntp2.example.org'},
  regdom = 'DE',

  wifi24 = {
    mesh = {
      mcast_rate = 12000,
    },
  },

  wifi5 = {
    mesh = {
      mcast_rate = 12000,
    },
  },

  mesh_vpn = {
    mtu = 1312,

    fastd = {
      methods = {'salsa2012+umac'},
    },

    bandwidth_limit = {
      enabled = false,
      egress = 200, -- kbit/s
      ingress = 3000, -- kbit/s
    },
  },

  autoupdater = {
    branch = 'stable',

    branches = {
      stable = {
        name = 'stable',
        mirrors = {'http://update.example.org/stable/sysupgrade'},
        good_signatures = 2,
        pubkeys = {
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Bob
          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Mary
        },
      },
    },
  },
}

domains/alpha_centauri.conf

{
  -- multiple codes/names can be defined, the first one is the primary name
  -- additional aliases can be defined
  domain_names = {
    alpha_centauri = 'Alpha Centauri',
    rigil_kentaurus = 'Rigil Kentaurus',
    proxima_centauri = 'Proxima Centauri',
  },

  -- 32 byte random data in hexadecimal encoding
  -- This data must be unique among all sites and domains!
  -- Can be generated using: echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
  domain_seed = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',

  -- unique network prefixes per domain
  prefix4 = '10.xxx.0.0/20',
  prefix6 = 'fdxx:xxxx:xxxx:xxxx::/64',

  next_node = {
    ip4 = '10.xxx.yyy.zzz',
    ip6 = 'fdxx:xxxx:xxxx:xxxx::xxxx',
  },

  wifi24 = {
    ap = {
      ssid = "alpha-centauri.example.org",
      channel = 1,
    },
    mesh = {
      id = 'ueH3uXjdp', -- usually you don't want users to connect to this mesh-SSID, so use a cryptic id that no one will accidentally mistake for the client WiFi
    },
  },

  wifi5 = {
    ap = {
      ssid = "alpha-centauri.example.org",
      channel = 44,
    },
    mesh = {
      id = 'ueH3uXjdp',
    },
  },

  mesh = {
    batman_adv = {
      routing_algo = 'BATMAN_IV',
    },
  },

  mesh_vpn = {
    fastd = {
      groups = {
        backbone = {
          peers = {
            peer1 = {
              key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
              remotes = {'"peer1.example.org" port xxxxx'},
            },
            peer2 = {
              key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
              remotes = {'"peer2.example.org" port xxxxx'},
            },
          },
        },
      },
    },
  },
}

i18n/en.po

msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Project-Id-Version: PACKAGE VERSION\n"
"PO-Revision-Date: 2016-02-04 14:28+0100\n"
"Last-Translator: David Lutz <kpanic@hirnduenger.de>\n"
"Language-Team: English\n"
"Language: en\n"
"MIME-Version: 1.0\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

msgid "gluon-config-mode:welcome"
msgstr ""
"Welcome to the setup wizard of your new Freifunk Alpha Centauri node. Please "
"fill out the following form and submit it."

msgid "gluon-config-mode:domain"
msgstr "Domain"

msgid "gluon-config-mode:domain-select"
msgstr ""
"Here you have the possibility of selecting the mesh domain in which your node "
"is placed. Please keep in mind that your router only connects with the nodes "
"of the selected domain."

msgid "gluon-config-mode:pubkey"
msgstr ""
"<p>This is your Freifunk node's public key. The node won't be able to "
"connect to the mesh VPN until the key has been registered on the Freifunk "
"servers. To register, send the key together with your node's name "
"(<em><%=pcdata(hostname)%></em>) to "
"<a href=\"mailto:keys@alpha-centauri.freifunk.net?subject="
"<%= urlencode('Registration: ' .. hostname) %>&amp;body="
"<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\nkey ') %>"
"%22<%= pubkey %>%22;"
"<%= urlencode('\n\nI have taken note that the contact I entered in the ') %>"
"<%= urlencode('node is publicly available on the Internet and can be ') %>"
"<%= urlencode('used by any services (e.g. the meshviewer map).') %>"
"<%= urlencode('\n\nThanks, \n\n') %>"
"\">keys@alpha-centauri.freifunk.net</a>. Of course, your e-mail address will "
"be treated confidentially and will not be passed on.</p>"
"<div class=\"the-key\">"
" # <%= pcdata(hostname) %><br />"
"<%= pubkey %>"
"</div>"
"<p>Your node <em><%= pcdata(hostname) %></em> is currently rebooting and will "
"try to connect to other nearby Freifunk nodes via WLAN and to a VPN-gateway "
"via your internet connection after the reboot is finished.</p>"
"<p>Don't forget to plug the network cable from the LAN port to the WAN port."
"</p>"

msgid "gluon-config-mode:novpn"
msgstr ""
"<p>You have selected <strong>not</strong> to use the mesh VPN. "
"Your node will only be able to connect to the Freifunk network if other nodes "
"in reach already have a connection.</p>"
"Please send an e-mail with the name of your node "
"(<em><%=pcdata(hostname)%></em>) and some additional information to "
"<a href=\"mailto:keys@alpha-centauri.freifunk.net?subject="
"<%= urlencode('Registration: ' .. hostname) %>&amp;body="
"<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\nkey ') %>"
"%22<%= pubkey %>%22;"
"<%= urlencode('\n\nI have taken note that the contact I entered in the ') %>"
"<%= urlencode('node is publicly available on the Internet and can be ') %>"
"<%= urlencode('used by any services (e.g. the meshviewer map).') %>"
"<%= urlencode('\n\nThanks, \n\n') %>"
"\">keys@alpha-centauri.freifunk.net</a>. Of course, your e-mail address will "
"be treated confidentially and will not be passed on.</p>"
"<p>Your node <em><%= pcdata(hostname) %></em> is currently rebooting and will "
"try to connect to other nearby Freifunk nodes after that.</p>"

msgid "gluon-config-mode:reboot"
msgstr ""
"<p>For more information about the Freifunk community on Alpha Centauri, have a "
"look at <a href=\"https://alpha-centauri.freifunk.net/\" target=\"_blank\">our "
"homepage</a>.</p>"
"<p>To get back to this configuration interface, press the reset button for "
"about 10 seconds during normal operation. The device will then reboot into "
"config mode.</p>"
"<p>Have fun with your node and exploring of the Freifunk network!</p>"

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-hostname/i18n/
msgid "gluon-config-mode:hostname-help"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-geo-location/i18n/
msgid "gluon-config-mode:geo-location-help"
msgstr ""

msgid "gluon-config-mode:altitude-label"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-contact-info/i18n/
msgid "gluon-config-mode:contact-help"
msgstr ""

msgid "gluon-config-mode:contact-note"
msgstr ""

i18n/de.po

msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Project-Id-Version: PACKAGE VERSION\n"
"PO-Revision-Date: 2015-03-19 20:28+0100\n"
"Last-Translator: Matthias Schiffer <mschiffer@universe-factory.net>\n"
"Language-Team: German\n"
"Language: de\n"
"MIME-Version: 1.0\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

msgid "gluon-config-mode:welcome"
msgstr ""
"Willkommen zum Einrichtungsassistenten für deinen neuen Alpha Centauri "
"Freifunk-Knoten. Fülle das folgende Formular deinen Vorstellungen "
"entsprechend aus und sende es ab."

msgid "gluon-config-mode:domain"
msgstr "Domäne"

msgid "gluon-config-mode:domain-select"
msgstr ""
"Hier hast du die Möglichkeit, die Mesh-Domäne, in der sich dein Knoten "
"befindet, auszuwählen. Bitte denke daran, dass sich dein Knoten nur mit den "
"Knoten der ausgewählten Domäne verbinden kann."

msgid "gluon-config-mode:pubkey"
msgstr ""
"<p>Dies ist der öffentliche Schlüssel deines Freifunk-Knotens. Erst nachdem "
"er auf den Servern des Freifunk-Projektes auf Alpha Centauri eingetragen "
"wurde, kann sich dein Knoten mit dem Mesh-VPN dort verbinden. Bitte schicke "
"dazu diesen Schlüssel und den Namen deines Knotens "
"(<em><%=pcdata(hostname)%></em>) an "
"<a href=\"mailto:keys@alpha-centauri.freifunk.net?subject="
"<%= urlencode('Anmeldung: ' .. hostname) %>&amp;body="
"<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\nkey ') %>"
"%22<%= pubkey %>%22;"
"<%= urlencode('\n\nIch habe zur Kenntnis genommen, dass der im ') %>"
"<%= urlencode('Knoten von mir eingetragene Kontakt im Meshnetz ') %>"
"<%= urlencode('öffentlich abfragbar ist und von beliebigen Diensten ') %>"
"<%= urlencode('(z.B. der Freifunk-Karte) veröffentlicht werden kann.') %>"
"<%= urlencode('\n\nGruß, \n\n') %>"
"\">keys@alpha-centauri.freifunk.net</a>. Deine E-Mail Adresse wird "
"selbstverständlich vertraulich behandelt und nicht weitergegeben."
"</p>"
"<div class=\"the-key\">"
"# <%= pcdata(hostname) %><br />"
"<%= pubkey %>"
"</div>"
"<p>Dein Knoten startet gerade neu und wird anschließend versuchen, sich mit "
"anderen Freifunkknoten in seiner Nähe über WLAN sowie über deine"
"Internetverbindung über das VPN-Gateway zu verbinden.</p>"
"<p>Vergiss nicht das Netzwerkkabel vom LAN Port in den WAN Port "
"umzustecken.</p>"

msgid "gluon-config-mode:novpn"
msgstr ""
"<p><strong>Du hast ausgewählt die Internetverbindung (Mesh-VPN) nicht zu "
"nutzen</strong>. Dein Knoten kann also nur dann eine Verbindung zum "
"Freifunk-Netz aufbauen, wenn andere Freifunk-Knoten in WLAN-Reichweite sind."
"<p>Bitte schicke uns eine E-Mail mit dem Namen deines Knotens "
"(<em><%= pcdata(hostname) %></em>) und ein paar Informationen an <a href="
"\"mailto:freifunk-keys@lists.in-kiel.de?"
"subject=<%= urlencode('Anmeldung: ' .. hostname) %>&amp;"
"body=<%= urlencode('# ' .. hostname .. '\n# ' .. sysconfig.primary_mac .. '\n# kein mesh-VPN') %>"
"<%= urlencode('\n\nIch habe zur Kenntnis genommen, dass der im ') %>"
"<%= urlencode('Knoten von mir eingetragene Kontakt im Meshnetz ') %>"
"<%= urlencode('öffentlich abfragbar ist und von beliebigen Diensten ') %>"
"<%= urlencode('(z.B. der Freifunk-Karte) veröffentlicht werden kann.') %>"
"<%= urlencode('\n\nGruß, \n\n') %>"
"\">kontakt@alpha-centauri.freifunk.net</a>. Deine E-Mail Adresse wird "
"selbstverständlich vertraulich behandelt und nicht weitergegeben.</p>"
"<p>Dein Knoten <em><%= pcdata(hostname) %></em> startet gerade neu und wird "
"anschließend versuchen, sich mit anderen Freifunkknoten in seiner Nähe über "
"WLAN zu verbinden.</p>"

msgid "gluon-config-mode:reboot"
msgstr ""
"<p>Weitere Informationen zur "
"Alpha Centauri Freifunk-Community findest du auf "
"<a href=\"https://alpha-centauri.freifunk.net/\" target=\"_blank\">unserer "
"Webseite</a>.</p>"
"<p>Um zu dieser Konfigurationsseite zurückzugelangen, drücke im normalen "
"Betrieb für ca. 10 Sekunden den Reset-Button. Das Gerät wird dann im Config "
"Mode neustarten.</p>"
"<p>Viel Spaß mit deinem Knoten und der Erkundung von Freifunk!</p>"

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-hostname/i18n/
msgid "gluon-config-mode:hostname-help"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-geo-location/i18n/
msgid "gluon-config-mode:geo-location-help"
msgstr ""

msgid "gluon-config-mode:altitude-label"
msgstr ""

# Leave empty to use the default text, which can be found in:
# package/gluon-config-mode-contact-info/i18n/
msgid "gluon-config-mode:contact-help"
msgstr ""

msgid "gluon-config-mode:contact-note"
msgstr ""

modules

# This file allows specifying additional repositories to use
# when building gluon.
#
# In most cases, it is not required so don't add it.

##	GLUON_SITE_FEEDS
#		for each feed name given, add the corresponding PACKAGES_* lines
#		documented below
#GLUON_SITE_FEEDS='my_own_packages'

##	PACKAGES_$feedname_REPO
#		the  git repository from where to clone the package feed
#PACKAGES_MY_OWN_PACKAGES_REPO=https://github.com/.../my-own-packages.git


##	PACKAGES_$feedname_COMMIT
#		the version/commit of the git repository to clone
#PACKAGES_MY_OWN_PACKAGES_COMMIT=123456789aabcda1a69b04278e4d38f2a3f57e49

##  PACKAGES_$feedname_BRANCH
#   the branch to check out
#PACKAGES_MY_OWN_PACKAGES_BRANCH=my_branch

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.

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.

Mesh-VPN

Gluon integrates several OSI-Layer 2 tunneling protocols to enable interconnects between local meshes and provide internetwork access. Available protocols currently are:

• fastd
• L2TPv3 (via tunneldigger)

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. Its primary drawback are the necessary context-switches when forwarding packets.

L2TPv3 is an in-kernel tunneling protocol that performs well, but offers no security properties by itself. The brokering of the tunnel happens through tunneldigger, its primary drawback being the lack of IPv6 support.

fastd

Configurable Cipher

From the site configuration fastd can be allowed to offer toggleable encryption in the config mode with the intent to increase throughput, although in practice the gain is minimal.

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 to the mesh_vpn.fastd.methods table if you want “Performance mode” as default (not recommended)

Gateway configuration:

1. Prepend the null cipher in fastd’s method list

Config Mode: The resulting firmware will allow users to choose between secure (encrypted) and fast (unencrypted) transport.

Unix socket: To confirm whether the correct cipher is being used, fastds unix socket can be interrogated, after installing for example socat.

opkg update
opkg install socat
socat - UNIX-CONNECT:/var/run/fastd.mesh_vpn.socket

Development Basics

Gluon’s source is kept in git repositories at GitHub.

Bug Tracker

The main repo does have issues enabled.

IRC

Gluon’s developers frequent the IRC chatroom #gluon on hackint. There is a webchat that allows for easy access from within your webbrowser. You’re welcome to join us!

Working with repositories

To update the repositories used by Gluon, just adjust the commit IDs in modules and rerun

make update

make update also applies the patches that can be found in the directories found in patches; the resulting branch will be called patched, while the commit specified in modules can be referred to by the branch base.

After new patches have been committed on top of the patched branch (or existing commits since the base commit have been edited or removed), the patch directories can be regenerated using

make update-patches

If applying a patch fails because you have changed the base commit, the repository will be reset to the old patched branch and you can try rebasing it onto the new base branch yourself and after that call make update-patches to fix the problem.

Always call make update-patches after making changes to a module repository as make update will overwrite your commits, making git reflog the only way to recover them!

Development Guidelines

Lua should be used instead of sh whenever sensible. The following criteria should be considered:

• Is the script doing more than just executing external commands? if so, use Lua
• Is the script parsing/editing json-data? If so, use Lua for speed
• When using sh, use jsonfilter instead of json_* functions for speed

Code formatting may sound like a topic for the pedantic, however it helps if the code in the project is formatted in the same way. The following basic rules apply:

• use tabs instead of spaces
• trailing whitespaces must be eliminated

If you add Lua scripts to gluon, check formatting with luacheck.

Adding support for new hardware

This page will give a short overview on how to add support for new hardware to Gluon.

Hardware requirements

Having an ath9k, ath10k or mt76 based WLAN adapter is highly recommended, although other chipsets may also work. VAP (multiple SSID) support is a requirement.

Adding profiles

The vast majority of devices with ath9k WLAN is based on the ar71xx target of OpenWrt. If the hardware you want to add support for is ar71xx, adding a new profile is sufficient.

Profiles are defined in targets/* in a shell-based DSL (so common shell command syntax like if can be used).

The device command is used to define an image build for a device. It takes two or three parameters.

The first parameter defines the Gluon profile name, which is used to refer to the device and is part of the generated image name. The profile name must be same as the output of the following command (on the target device), so the autoupdater can work:

lua -e 'print(require("platform_info").get_image_name())'

While porting Gluon to a new device, it might happen that the profile name is unknown. Best practise is to generate an image first by using an arbitrary value and then executing the lua command on the device and use its output from then on.

The second parameter defines the name of the image files generated by OpenWrt. Usually, it is also the OpenWrt profile name; for devices that still use the old image build code, a third parameter with the OpenWrt profile name can be passed. The profile names can be found in the image Makefiles in openwrt/target/linux/<target>/image/Makefile.

Examples:

device tp-link-tl-wr1043n-nd-v1 tl-wr1043nd-v1
device alfa-network-hornet-ub hornet-ub HORNETUB

Suffixes and extensions

By default, image files are expected to have the extension .bin. In addition, the images generated by OpenWrt have a suffix before the extension that defaults to -squashfs-factory and -squashfs-sysupgrade.

This can be changed using the factory and sysupgrade commands, either at the top of the file to set the defaults for all images, or for a single image. There are three forms with 0 to 2 arguments (all work with sysupgrade as well):

factory SUFFIX .EXT
factory .EXT
factory

When only an extension is given, the default suffix is retained. When no arguments are given, this signals that no factory (or sysupgrade) image exists.

Aliases

Sometimes multiple models use the same OpenWrt images. In this case, the alias command can be used to create symlinks and additional entries in the autoupdater manifest for the alternative models.

Standalone images

On targets without per-device rootfs support in OpenWrt, the commands described above can’t be used. Instead, factory_image and sysupgrade_image are used:

factory_image PROFILE IMAGE .EXT
sysupgrade_image PROFILE IMAGE .EXT

Again, the profile name must match the value printed by the aforementioned Lua command. The image name must match the part between the target name and the extension as generated by OpenWrt and is to be omitted when no such part exists.

Packages

The packages command takes an arbitrary number of arguments. Each argument defines an additional package to include in the images in addition to the default package sets defined by OpenWrt. When a package name is prefixed by a minus sign, the packages are excluded instead.

The packages command may be used at the top of a target definition to modify the default package list for all images, or just for a single device (when the target supports per-default rootfs).

Configuration

The config command allows to add arbitrary target-specific OpenWrt configuration to be emitted to .config.

Notes

On devices with multiple WLAN adapters, care must also be taken that the primary MAC address is configured correctly. /lib/gluon/core/sysconfig/primary_mac should contain the MAC address which can be found on a label on most hardware; if it does not, /lib/gluon/upgrade/010-primary-mac in gluon-core might need a fix. (There have also been cases in which the address was incorrect even on devices with only one WLAN adapter, in these cases a OpenWrt bug was the cause).

Adding support for new hardware targets

Adding a new target is much more complex than adding a new profile. There are two basic steps required for adding a new target:

Package adjustments

One package that may need adjustments for new targets is libplatforminfo (to be found in packages/gluon/libs/libplatforminfo). If the new platform works fine with the definitions found in default.c, nothing needs to be done. Otherwise, create a definition for the added target or subtarget, either by symlinking one of the files in the templates directory, or adding a new source file.

On many targets, Gluon’s network setup scripts (mainly in the package gluon-core) won’t run correctly without some adjustments, so better double check that everything is fine there (and the files primary_mac, lan_ifname and wan_ifname in /lib/gluon/core/sysconfig/ contain sensible values).

Build system support

A definition for the new target must be created under targets, and it must be added to targets/targets.mk. The GluonTarget macro takes one to three arguments: the target name, the Gluon subtarget name (if the target has subtargets), and the OpenWrt subtarget name (if it differs from the Gluon subtarget). The third argument can be used to define multiple Gluon targets with different configuration for the same OpenWrt target, like it is done for the ar71xx-tiny target.

After this, is should be sufficient to call make GLUON_TARGET=<target> to build the images for the new target.

Package development

Gluon packages are OpenWrt packages and follow the same rules described at https://openwrt.org/docs/guide-developer/packages.

Gluon package makefiles

As many packages share the same or a similar structure, Gluon provides a package/gluon.mk that can be included for common definitions. This file replaces OpenWrt’s $(INCLUDE_DIR)/package.mk; it is usually included as include ../gluon.mk from Gluon core packages, or as include $(TOPDIR)/../package/gluon.mk from feeds.

Provided macros

• GluonBuildI18N (arguments: <source directory>)

  Converts the .po files for all enabled languages from the given source directory to the binary .lmo format and stores them in $(PKG_BUILD_DIR)/i18n.

• GluonInstallI18N

  Install .lmo files from $(PKG_BUILD_DIR)/i18n to /lib/gluon/web/i18n in the package install directory.

• GluonSrcDiet (arguments: <source directory>, <destination directory>)

  Copies a directory tree, processing all files in it using LuaSrcDiet. The directory tree should only contain Lua files.

• GluonCheckSite (arguments: <source file>)

  Intended to be used in a package postinst script. It will use the passed Lua snippet to verify package-specific site configuration.

• BuildPackageGluon (replaces BuildPackage)

  Extends the Package/<name> definition with common defaults, sets the package install script to the common Gluon/Build/Install, and automatically creates a postinst script using GluonCheckSite if a check_site.lua is found in the package directory.

Default build steps

These defaults greatly reduce the boilerplate in each package, but they can also be confusing because of the many implicit behaviors depending on files in the package directory. If any part of Gluon/Build/Compile or Gluon/Build/Install does not work as intended for a package, the compile and install steps can always be replaced or extended.

Build/Compile is set to Gluon/Build/Compile by default, which will

• run OpenWrt standard default commands (Build/Compile/Default) if a src/Makefile or src/CMakeLists.txt is found
• run GluonSrcDiet on all files in the luasrc directory
• run GluonBuildI18N if a i18n directory is found

Package/<name> defaults to Gluon/Build/Install for packages defined using BuildPackageGluon, which will

• copy all files from $(PKG_INSTALL_DIR) into the package if $(PKG_INSTALL) is 1
• copy all files from files into the package
• copy all Lua files built from luasrc into the package
• installs $(PKG_BUILD_DIR)/respondd.so to /usr/lib/respondd/$(PKG_NAME).so if src/respondd.c exists
• installs compiled i18n .lmo files

Feature flags

Feature flags provide a convenient way to define package selections without making it necessary to list each package explicitly.

The main feature flag definition file is package/features, but each package feed can provide additional definitions in a file called features at the root of the feed repository.

Each flag $flag without any explicit definition will simply include the package with the name gluon-$flag by default. The feature definition file can modify the package selection in two ways:

• The nodefault function suppresses default of including the gluon-$flag package
• The packages function adds a list of packages (or removes, when package names are prepended with minus signs) when a given logical expression is satisfied

Example:

nodefault 'web-wizard'

packages 'web-wizard' \
  'gluon-config-mode-hostname' \
  'gluon-config-mode-geo-location' \
  'gluon-config-mode-contact-info'

packages 'web-wizard & (mesh-vpn-fastd | mesh-vpn-tunneldigger)' \
  'gluon-config-mode-mesh-vpn'

This will

• disable the inclusion of a (non-existent) package called gluon-web-wizard
• enable three config mode packages when the web-wizard feature is enabled
• enable gluon-config-mode-mesh-vpn when both web-wizard and one of mesh-vpn-fastd and mesh-vpn-tunneldigger are enabled

Supported syntax elements of logical expressions are:

• & (and)
• | (or)
• ! (not)
• parentheses

Upgrade scripts

Basics

After each sysupgrade (including the initial installation), Gluon will execute all scripts under /lib/gluon/upgrade. These scripts’ filenames usually begin with a 3-digit number specifying the order of execution. Note that the script files need to be executable.

To get an overview of the ordering of all scripts of all packages, the helper script contrib/lsupgrade.sh in the Gluon repository can be used, which will print all upgrade scripts’ filenames and directories. If executed on a TTY, the filename will be highlighted in green, the repository in blue and the package in red.

Best practices

• Most upgrade scripts are written in Lua. This allows using lots of helper functions provided by Gluon, e.g. to access the site configuration or edit UCI configuration files.
• Whenever possible, scripts shouldn’t check if they are running for the first time, but just edit configuration files to achieve a valid configuration (without overwriting configuration changes made by the user where desirable). This allows using the same code to create the initial configuration and upgrade configurations on upgrades.
• If it is unavoidable to run different code during the initial installation, the sysconfig.gluon_version variable can be checked. This variable is nil during the initial installation and contains the previously installed Gluon version otherwise.

Script ordering

These are some guidelines for the script numbers:

• 0xx: Basic sysconfig setup
• 1xx: Basic system setup (including basic network configuration)
• 2xx: Wireless setup
• 3xx: Advanced network and system setup
• 4xx: Extended network and system setup (e.g. mesh VPN and next-node)
• 5xx: Miscellaneous (everything not fitting into any other category)
• 6xx .. 8xx: Currently unused
• 9xx: Upgrade finalization

WAN support

As the WAN port of a node will be connected to a user’s private network, it is essential that the node only uses the WAN when it is absolutely necessary. There are two cases in which the WAN port is used:

• Mesh VPN (package gluon-mesh-vpn-fastd)
• DNS to resolve the VPN servers’ addresses (package gluon-wan-dnsmasq)

After the VPN connection has been established, the node should be able to reach the mesh’s DNS servers and use these for all other name resolution.

If the device does not feature a WAN port, the LAN port is configured as WAN port. In case such a device has multiple LAN ports, all these can be used as WAN. Devices, which feature a “hybrid” port (labled as WAN/LAN), this port is used as WAN.

This behavior can be reversed using the single_as_lan site.conf option.

Routing tables

As a node may get IPv6 default routes both over the WAN and the mesh, Gluon uses two routing tables for IPv6. As all normal traffic should go over the mesh, the mesh routes are added to the default table (table 0). All routes on the WAN interface are put into table 1 (see /lib/gluon/upgrade/110-network in gluon-core).

There is also an ip -6 rule which routes all IPv6 traffic with a packet mark with the bit 1 set though table 1.

libpacketmark

libpacketmark is a library which can be loaded with LD_PRELOAD and will set the packet mark of all sockets created by a process in accordance with the LIBPACKETMARK_MARK environment variable. This allows setting the packet mark for processes which don’t support this themselves. The process must run as root (or at least with CAP_NET_ADMIN) for this to work.

Unfortunately there’s no nice way to set the packet mark via iptables for outgoing packets. The iptables will run after the packet has been created, to even when the packet mark is changed and the packet is re-routed, the source address won’t be rewritten to the default source address of the newly chosen route. libpacketmark avoids this issue as the packet mark will already be set when the packet is created.

gluon-wan-dnsmasq

To separate the DNS servers in the mesh from the ones on the WAN, the gluon-wan-dnsmasq package provides a secondary DNS daemon which runs on 127.0.0.1:54. It will automatically use all DNS servers explicitly configured in /etc/config/gluon-wan-dnsmasq or received via DNS/RA on the WAN port. It is important that no DNS servers for the WAN interface are configured in /etc/config/network and that peerdns is set to 0 so the WAN DNS servers aren’t leaked to the primary DNS daemon.

libpacketmark is used to make the secondary DNS daemon send its requests over the WAN interface.

The package gluon-mesh-vpn-fastd provides an iptables rule which will redirect all DNS requests from processes running with the primary group gluon-mesh-vpn to 127.0.0.1:54, thus making fastd use the secondary DNS daemon.

MAC addresses

Many devices don’t have enough unique MAC addresses assigned by the vendor (in batman-adv, each mesh interface needs an own MAC address that must be unique mesh-wide).

Gluon tries to solve this issue by using a hash of the primary MAC address as a 45 bit MAC address prefix. The resulting 8 addresses are used as follows:

• 0: client0; WAN
• 1: mesh0
• 2: (unused)
• 3: wan_radio0 (private WLAN); batman-adv primary address
• 4: client1; LAN
• 5: mesh1
• 6: (unused)
• 7: wan_radio1 (private WLAN); mesh VPN

gluon.site library

The gluon.site library allows convenient access to the site configuration from Lua scripts. Example:

local site = require 'gluon.site'
print(site.wifi24.ap.ssid())

The site object in this example does not directly represent the site.conf data structure; instead, it is wrapped in a way that makes it more convenient to access deeply nested elements. To access the underlying values, they must be unwrapped using the function call notation (the () after site.wifi24.ap.ssid in the example).

The wrapper objects have two advantages over simple Lua tables:

• Accessing non-existing values is never an error: site.wifi24.ap.ssid() will simply return nil if site.wifi24 or site.wifi24.ap do not exist

• Default values: A default value can be passed to the unwrapping function call:

  print(site.wifi24.ap.ssid('Default'))
  

  will return ‘Default’ instead of nil when the value is unset.

  Note that nil values and unset values are equivalent in Lua.

A simple way to access the whole site configuration as a simple table is to unwrap the top-level site object:

local site_table = site()

Controllers

Controllers live in the controller subdirectory of a gluon-web application (/lib/gluon/config-mode/controller for the config mode, /lib/gluon/status-page/controller for the status page). They define which pages (“routes”) exist under the application base URL, and what code is run when these pages are requested.

Controller scripts usually start with a package declaration, followed by calls to the entry function, which each define one route:

package 'gluon-web-admin'

entry({"admin"}, alias("admin", "info"), _("Advanced settings"), 10)
entry({"admin", "info"}, template("admin/info"), _("Information"), 1)

package defines the translation namespace for the titles of the defined pages as well as the referenced views and models. The entry function expects 4 arguments:

• path: Components of the path to define a route for.

  The above example defines routes for the paths admin and admin/info.

• target: Dispatcher for the route. See the following section for details.

• title: Page title (also used in navigation). The underscore function is used to mark the strings as translatable for i18n-scan.pl.

• order: Sort index in navigation (defaults to 100)

Navigation indexes are automatically generated for each path level. Pages can be hidden from the navigation by setting the hidden property of the node object returned by entry:

entry({"hidden"}, alias("foo"), _("I'm hidden!")).hidden = true

Dispatchers

• alias (path, …): Redirects to a different page. The path components are passed as individual arguments.
• call (func, …): Runs a Lua function for custom request handling. The given function is called with the HTTP object and the template renderer as first two arguments, followed by all additional arguments passed to call.
• template (view): Renders the given view. See Views.
• model (name): Displays and evaluates a form as defined by the given model. See the Models page for an explanation of gluon-web models.

The HTTP object

The HTTP object provides information about the HTTP requests and allows to add data to the reply. Using it directly is rarely necessary when gluon-web models and views are used.

Useful functions:

• getenv (key): Returns a value from the CGI environment passed by the webserver.
• formvalue (key): Returns a value passed in a query string or in the content of a POST request. If multiple values with the same name have been passed, only the first is returned.
• formvaluetable (key): Similar to formvalue, but returns a table of all values for the given key.
• status (code, message): Writes the HTTP status to the reply. Has no effect if a status has already been sent or non-header data has been written.
• header (key, value): Adds an HTTP header to the reply to be sent to the client. Has no effect when non-header data has already been written.
• prepare_content (mime): Sets the Content-Type header to the given MIME type, potentially setting additional headers or modifying the MIME type to accommodate browser quirks
• write (data, …): Sends the given data to the client. If headers have not been sent, it will be done before the data is written.

HTTP functions are called in method syntax, for example:

http:write('Output!')

The template renderer

The template renderer allows to render templates (views). The most useful functions are:

• render (view, scope, pkg): Renders the given view, optionally passing a table with additional variables to make available in the template. The passed package defines the translation namespace.
• render_string (str, scope, pkg): Same as render, but the template is passed directly instead of being loaded from the view directory.

The renderer functions are called in property syntax, for example:

renderer.render('layout')

Differences from LuCI

• Controllers must not use the module function to define a Lua module (gluon-web will set up a proper environment for each controller itself)
• Entries are defined at top level, not inside an index function
• The alias dispatcher triggers an HTTP redirect instead of directly running the dispatcher of the aliased route.
• The call dispatcher is passed a function instead of a string with a function name.
• The cbi dispatcher of LuCI has been renamed to model.
• The HTTP POST handler support the multipart/form-data encoding only, so enctype="multipart/form-data" must be included in all <form> HTML elements.
• Other dispatchers like form are not provided.

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:

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 toplevel 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 Data types

  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.

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)

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 Models 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:

<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: The template renderer

• http: The HTTP object

• 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 Internationalization support

Internationalization support

General guidelines

• All config mode packages must be fully translatable, with complete English and German texts.
• All new expert mode packages must be fully translatable. English texts are required.
• German translations are recommended. Other supported languages, especially French, are nice-to-have, but not required. If you don’t know a language well, rather leave the translation blank, so it is obvious that there is no proper translation yet.
• Existing expert mode packages should be made translatable as soon as possible.
• The “message IDs” (which are the arguments to the translate function) should be the English texts.

i18n support in Gluon

Internationalization support is available in all components (models, view and controllers) of gluon-web-based packages. Strings are translated using the translate, _translate and translatef functions (translate for static strings, translatef for printf-like formatted string; _translate works the same as translate, but will return nil instead of the original string when no translation is available).

In views, the special tags <%:...%> can be used to translate the contained string.

Example from the gluon-config-mode-geo-location package:

local share_location = s:option(Flag, "location", translate("Show node on the map"))

Note that translations are namespaced: each package will only use its own translation strings by default. For this purpose, the package name must by specified in a package’s controller. It is possible to access a different translation package using the i18n function from models and view, which is necessary when strings from the site configuration are used, or packages do not have their own controller (which is the case for config mode wizard components).

local site_i18n = i18n 'gluon-site'
local msg = site_i18n._translate('gluon-config-mode:welcome')

Adding translation templates to Gluon packages

The i18n support is based on the standard gettext system. For each translatable package, a translation template with extension .pot can be created using the i18n-scan.pl script in the contrib directory:

cd package/gluon-web-mesh-vpn-fastd
mkdir i18n
cd i18n
../../../contrib/i18n-scan.pl ../files ../luasrc > gluon-web-mesh-vpn-fastd.pot

The same command can be run again to update the template.

In addition, the Makefile must be adjusted. Instead of OpenWrt’s default package.mk, the Gluon version (../gluon.mk for core packages) must be used. The i18n files must be installed and PKG_CONFIG_DEPENDS must be added:

...
include ../gluon.mk

PKG_CONFIG_DEPENDS += $(GLUON_I18N_CONFIG)
...
define Build/Compile
  $(call GluonBuildI18N,gluon-web-mesh-vpn-fastd,i18n)
endef

define Package/gluon-web-mesh-vpn-fastd/install
  ...
  $(call GluonInstallI18N,gluon-web-mesh-vpn-fastd,$(1))
endef
...

Adding translations

A new translation file for a template can be added using the msginit command:

cd package/gluon-web-mesh-vpn-fastd/i18n
msginit -l de

This will create the file de.po in which the translations can be added.

The translation file can be updated to a new template version using the msgmerge command:

msgmerge -U de.po gluon-web-mesh-vpn-fastd.pot

After the merge, the translation file should be checked for “fuzzy matched” entries where the original English texts have changed. All entries from the translation file should be translated in the .po file (or removed from it, so the original English texts are displayed instead).

Adding support for new languages

A list of all languages supported by gluon-web can be found in package/gluon.mk. New languages just need to be added to GLUON_SUPPORTED_LANGS, and a human-readable language name must be defined.

Config Mode

The Config Mode consists of several modules that provide a range of different configuration options:

gluon-config-mode-core

This modules provides the core functionality for the config mode. All modules must depend on it.

gluon-config-mode-hostname

Provides a hostname field.

gluon-config-mode-autoupdater

Informs whether the autoupdater is enabled.

gluon-config-mode-mesh-vpn

Allows toggling of mesh-vpn-fastd and setting a bandwidth limit.

gluon-config-mode-geo-location

Enables the user to set the geographical location of the node.

gluon-config-mode-contact-info

Adds a field where the user can provide contact information.

Writing Config Mode modules

Config mode modules are located at /lib/gluon/config-mode/wizard and /lib/gluon/config-mode/reboot. Modules are named like 0000-name.lua and are executed in lexical order. In the standard package set, the order is, for wizard modules:

• 0050-autoupdater-info
• 0100-hostname
• 0300-mesh-vpn
• 0400-geo-location
• 0500-contact-info

The reboot module order is:

• 0100-mesh-vpn
• 0900-msg-reboot

All modules are run in the gluon-web model context and have access to the same variables as “full” gluon-web modules.

Wizards

Wizard modules must return a function that is provided with the wizard form and an UCI cursor. The function can create configuration sections in the form:

return function(form, uci)
  local s = form:section(Section)
  local o = s:option(Value, "hostname", "Hostname")
  o.default = uci:get_first("system", "system", "hostname")
  o.datatype = "hostname"

  function o:write(data)
    uci:set("system", uci:get_first("system", "system"), "hostname", data)
  end

  return {'system'}
end

The function may return a table of UCI packages to commit after the individual fields’ write methods have been executed. This is done to avoid committing the packages repeatedly when multiple wizard modules modify the same package.

Reboot page

Reboot modules are simply executed when the reboot page is rendered:

renderer.render_string("Hello World!")

gluon-client-bridge

This package provides a bridge (br-client) for connecting clients. It will also setup a wireless interface, provided it is configured in site.conf.

site.conf

wifi24.ap.ssid / wifi5.ap.ssid

SSID for the client network

gluon-config-mode-domain-select

This package provides a drop-down list for the config mode to select the domain the node will be placed in. If the selection has changed the upgrade scripts in /lib/gluon/upgrade/ are triggered to update the nodes configuration.

Hiding domains could be useful for default or testing domains, which should not be accidentally selected by a node operator.

domains/*.conf

hide_domain : optional (defaults to false)

• false shows this domain in drop-down list
• true hides this domain

Example:

hide_domain = true

gluon-ebtables-filter-multicast

The gluon-ebtables-filter-multicast package filters out various kinds of non-essential multicast traffic, as this traffic often constitutes a disproportionate burden on the mesh network. Unfortunately, this breaks many useful services (Avahi, Bonjour chat, …), but this seems unavoidable, as the current Avahi implementation is optimized for small local networks and causes too much traffic in large mesh networks.

The multicast packets are filtered between the nodes’ client bridge (br-client) and mesh interface (bat0) on output.

The following packet types are considered essential and aren’t filtered:

• ARP (except requests for/replies from 0.0.0.0)
• DHCP, DHCPv6
• ICMPv6 (except Echo Requests (ping) and Node Information Queries (RFC4620)
• IGMP

In addition, the following packet types are allowed to allow experimentation with layer 3 routing protocols.

• Babel
• OSPF
• RIPng

The following packet types are also allowed:

• BitTorrent Local Peer Discovery (it seems better to have local peers for BitTorrent than sending everything through the internet)

gluon-ebtables-filter-ra-dhcp

The gluon-ebtables-filter-ra-dhcp package tries to prevent common misconfigurations (i.e. connecting the client interface of a Gluon node to a private network) from causing issues for either of the networks.

The rules are the following:

• DHCP requests, DHCPv6 requests and Router Solicitations may only be sent from clients to the mesh, but aren’t forwarded from the mesh to clients
• DHCP replies, DHCPv6 replies and Router Advertisements from clients aren’t forwarded to the mesh

gluon-ebtables-limit-arp

The gluon-ebtables-limit-arp package adds filters to limit the amount of ARP requests client devices are allowed to send into the mesh.

The limits per client device, identified by its MAC address, are 6 packets per minute and 1 per second per node in total. A burst of up to 50 ARP requests is allowed until the rate-limiting takes effect (see --limit-burst in ebtables(8)).

Furthermore, ARP requests for a target IP already present in the batman-adv DAT cache are excluded from rate-limiting, in regard to both counting and filtering, as batman-adv will be able to respond locally without a burden for the mesh. Therefore, this limiter should not affect popular target IP addresses, like those of gateways or nameservers.

However it mitigates the impact on the mesh when a larger range of its IPv4 subnet is being scanned, which would otherwise result in a significant amount of ARP chatter, even for unused IP addresses.

This package is installed by default if the selected routing feature is mesh-batman-adv-15. It can be unselected via:

GLUON_SITE_PACKAGES := \
  -gluon-ebtables-limit-arp

gluon-ebtables-source-filter

The gluon-ebtables-source-filter package adds an additional layer-2 filter ruleset to prevent unreasonable traffic entering the network via the nodes. Unreasonable means traffic entering the mesh via a node which source IP does not belong to the configured IP space.

You may first check if there is a certain proportion of unreasonable traffic, before adding this package to the firmware image. Furthermore, you should not use this package if some kind of gateway or upstream network is provided by a device connected to the client port.

site.conf

prefix4 : optional

• IPv4 subnet

prefix6 :

• IPv6 subnet

extra_prefixes6 : optional

• list of additional IPv6 subnets

Example:

prefix4 = '198.51.100.0/21',
prefix6 = '2001:db8:8::/64',
extra_prefixes6 = {
  '2001:db8:9::/64',
  '2001:db8:100::/60',
},

gluon-hoodselector

This package provides an automated way to continuously select the correct domain based on the geolocation of a node. The purpose of Hoodselector is to automatically detect in which domain the node is located based on its geolocation settings. Therefore domains are required to have bounding boxes, defined as polygons or rectangles. Based on this information Hoodselector will select a domain from the list of known domains and migrate towards it without requiring a reboot. This package therefore provides a scalable and decentralized approach to automatic domain selection.

Background information

The main problem of the Nordwest Freifunk community was the quickly rising number of nodes in the network. This indirectly affected the stability of the network, because the noise inside the network, e.g. management traffic from the batman-adv protocol, was rising, too. Inside the community there were some ideas like building separate firmwares for each region. This solution would cause issues with splitting regions again and nodes scattered among regions which belong to a different region. Therefore we decided to develop a dynamic and decentralized management of regions called domains. The Hoodselector’s task is to choose the “right” domains in an intelligent way and to hold the network together and accessible.

A domain is defined by geostationary fixed shapes by using longitude & latitude in combination with the domain configuration system. Below you can see a visual example of a regional domain:

© OpenStreetMap contributors

Behaviour

The following is an abstract state diagram which gives an overview of the process:

The sequence of this diagram reflects the priority of its running modes. Each mode will be explained separately below.

geolocation mode

This mode will only be entered when a node has location coordinates set. Nodes with a position will set their domain based on it. The node will skip to the next mode when the node (a) has no position or (b) its position is not within any of the defined bounding boxes.

default domain mode

This mode will be entered if no other mode before fits. It provides a fallback to the default domain.

Domain shapes

There are two types of domains: the unique default one without a defined shape and others which contain shapes.

• default domain

The default domain doesn’t hold any shapes and represents the inverted area of all other shapes held by other domains with geo coordinates. It will only be entered if a node could not be matched to a geo domain. A suggested approach is to define the “old” network as default domain and gradually migrate nodes from there to geo domains.

• geo domains

A geo domain contains shapes, which are described by three dimensional arrays and represents the geographical size of the domain. There are two possible definitions of these shapes. The first one is using rectangles so that only two coordinates per box are needed to define it (see below for an example). The second one uses polygons which can have multiple edges. Each domain can hold multiple shapes.

site.conf

The designer of the shapes must always ensure that no overlapping polygons between domains will be created or else the order in the domain list will become relevant. If for example domain A and B overlap, Hoodselector would, for that overlapping area, only ever reach domain A, but never domain B. Here is an example of a rectangular definition of a shape: Example:

hoodselector = {
  shapes = {
    {
      {
        lat = 53.128,
        lon = 8.187
      },
      {
        lat = 53.163,
        lon = 8.216
      },
    },
  },
},

Here is an example of a shape defined by a triangle: Example:

hoodselector = {
  shapes = {
    {
      {
        lat = 53.128,
        lon = 8.187
      },
      {
        lat = 53.163,
        lon = 8.216
      },
      {
        lat = 53.196,
        lon = 8.194
      },
    },
  },
},

This package is incompatible with gluon-config-mode-domain-select.

gluon-mesh-batman-adv

B.A.T.M.A.N. Advanced (often referenced as batman-adv) is an implementation of the B.A.T.M.A.N. routing protocol in form of a linux kernel module operating on layer 2.

Layer 2 means that all client devices will operate in the same, virtual broadcast domain and will see each other “as if they were connected to one giant switch”.

This comes with a set of advantages (like quick and economical client device roaming, layer 3 protocol agnosticism, broadcast/multicast). But also impediments, especially layer 2 multicast overhead - which Gluon tries to mitigate to achieve a certain degree of scalability. See gluon-ebtables-filter-multicast and Multicast Architecture for details.

B.A.T.M.A.N. Advanced project homepage:

• https://www.open-mesh.org/projects/batman-adv/wiki/Wiki

B.A.T.M.A.N. Routing Algorithms

Two routing algorithms are selectable via site.conf mesh section: BATMAN_IV and BATMAN_V.

BATMAN_IV - stable

This is the recommended algorithm to use with gluon-mesh-batman-adv-15.

BATMAN_V - experimental

This is the experimental B.A.T.M.A.N. routing algorithm. It is packet format / compatibility stable but is still in development.

For more details, see:

• https://www.open-mesh.org/projects/batman-adv/wiki/BATMAN_V

Multicast Architecture

While generally broadcast capability is a nice feature of a layer 2 mesh protocol, it quickly reaches its limit.

For meshes with about 50 nodes / 100 clients, or more it is therefore highly recommended to add the gluon-ebtables-filter-multicast package. Also, with the mesh-batman-adv-15 feature, gluon-ebtables-limit-arp is selected by default.

Furthermore, by default IGMP and MLD messages are filtered. See site.conf mesh section and IGMP/MLD Domain Segmentation for details.

To achieve some level of scalability for multicast, multicast group awareness is implemented and utilized in the following ways:

Node-Local Multicast Handling

A Gluon node sends IGMP/MLD Queries with the following parameters on its local segment:

• Interval: 20 seconds
• Robustness: 9
• Query Response Interval: 5 seconds

This way, through the returning IGMP/MLD reports, the node learns which multicast groups its clients are interested in.

This is then used to deliver multicast packets to its own Wifi clients via individual Wifi unicast transmissions instead of a broadcast transmission.

The advantages of this are:

• Usually higher bitrates: Mostly lower airtime usage
• Acknowledged, retried transmissions (ARQ): Higher reliability
• If no local client is interested: Avoiding the transmission, no airtime usage

Notably multicast for IPv6 Neighbor Discovery usually has only a single multicast listener in the case of address resolution and usually no multicast listener for duplicate address detection. Which are the ideal cases for multicast snooping / multicast to unicast.

The unicast delivery is achieved through utilizing the multicast-to-unicast feature in OpenWrt/netifd. Which in turn utilizes the multicast-to-unicast conversion and hairpin features of the Linux bridge, plus the hostapd client isolation feature, to hand over full delivery control to the bridge.

Mesh-wide Multicast Handling

To be able to avoid transmissions not only on the “last mile”, the AP interface to the local clients, but also from the “last mile” into the mesh in the future multicast listener state is propagated through the mesh:

batman-adv (compat 15) taps into the Linux bridge and inherits the multicast groups into its translation table. Which then takes care of efficiently distributing this knowledge to other nodes.

While by that the receiver side is ready to go, the sender part in batman-adv is disabled for now in Gluon. It will be enabled in a future release.

IGMP/MLD Domain Segmentation

Internet Group Membership Protocol and Multicast Listener Discovery Protocol are the standardized network protocols to query, report and learn multicast group memberships on the local link for IPv4 (IGMP) and IPv6 (MLD).

By default Gluon filters IGMP and MLD queries and reports towards the mesh and runs an IGMP/MLD querier on each node for its own local clients. Furthermore Gluon tags the mesh side bridge port (bat0) as a multicast router port.

That way, even though the Linux client bridge in Gluon is unable to learn about multicast memberships behind other nodes, the multicast router port flag will force it to unconditionally hand over all multicast packets to batman-adv. Which even with IGMP/MLD filtered, will have full multicast membership knowledge through its own propagation through the batman-adv translation table.

Advantages are:

• Reduced overhead through reactive batman-adv multicast TT vs. periodic IGMP/MLD messages in the mesh
• Increased IGMP/MLD snooping robustness via local, per node IGMP/MLD queriers
• DDoS vector mitigation

Note: For nodes running an operating system other than Gluon, but a bridge interface on top of the batman-adv interface, you will need to set the multicast router flag there manually:

debian$ echo 2 > /sys/class/net/bat0/brport/multicast_router

“2” for this parameter means to always assume a multicast router behind this bridge port and to therefore forward all multicast packets to this port. Versus the default of “1” which means to learn about multicast routers via IGMP/MLD Queries, PIM and MRD messages; or “0” to always assume that there is no multicast router behind this port, meaning to only forward multicast to this port if an according multicast listener on this link was detected.

Further limitations: IGMP/MLD snooping switches (e.g. “enterprise switches”) behind the client network of a node (LAN ports) are unsupported. It is advised to disable IGMP/MLD snooping on those enterprise switches for now or to at least manually mark the port to the Gluon router as a “multicast router port”.

Alternatively, the filtering of IGMP/MLD reports can be disabled via the site.conf (which is not recommended in large meshes though). See site.conf mesh section for details.

gluon-radv-filterd

This package drops all incoming router advertisements except for the default router with the best metric according to B.A.T.M.A.N. advanced.

Note that advertisements originating from the node itself (for example via gluon-radvd) are not affected and considered at all.

Selected router

The router selection mechanism is independent from the batman-adv gateway mode. In contrast, the device originating the router advertisement could be any router or client connected to the mesh, as radv-filterd captures all router advertisements originating from it. All nodes announcing router advertisement with a default lifetime greater than 0 are being considered as candidates.

In case a router is not a batman-adv originator itself, its TQ is defined by the originator it is connected to. This lookup uses the batman-adv global translation table.

Initially the router is selected by choosing the candidate with the strongest TQ. When another candidate can provide a better TQ metric, that outperforms the currently selected router by X metric units, it will be picked as the new selected router. The hysteresis threshold is configurable and prevents excessive flapping of the gateway.

Local routers

Local routers (i.e. local internet gateways connected to some nodes) that are connected to the client interface via cable or WLAN instead of via the mesh (technically: appearing in the transtable_local) are taken into account with a fake TQ of 512, so that they are always preferred.

Be aware of problems if you plan to use local routers together with the gluon-ebtables-filter-ra-dhcp package. These router advertisements are filtered anyway and reach neither the node nor any other client. Therefore the use of local routers is not possible as long as the package gluon-radv-filterd is used.

respondd module

This package also contains a module for respondd that announces the currently selected router via the statistics.gateway6 property using its interface MAC address. Note that this is different from the statistics.gateway property, which contains the MAC address of the main B.A.T.M.A.N. adv slave interface of the selected IPv4 gateway.

site.conf

radv_filterd.threshold : optional

• minimal difference in TQ value that another gateway has to be better than the currently chosen gateway to become the new chosen gateway
• defaults to 20

Example:

radv_filterd = {
  threshold = 20,
}

gluon-scheduled-domain-switch

This package allows to switch a routers domain at a given point in time. This is needed for switching between incompatible transport protocols (e.g. wired meshing with and without VXLAN).

Nodes will switch when the defined switch-time has passed. In case the node was powered off while this was supposed to happen, it might not be able to acquire the correct time. In this case, the node will switch after it has not seen any gateway for a given period of time.

site.conf

All those settings have to be defined exclusively in the domain, not the site.

domain_switch : optional (needed for domains to switch)

target_domain :

• target domain to switch to

switch_after_offline_mins :

• amount of time without reachable gateway to switch unconditionally

switch_time :

• UNIX epoch after which domain will be switched

connection_check_targets :

• array of IPv6 addresses which are probed to determine if the node is connected to the mesh

Example:

domain_switch = {
  target_domain = 'new_domain',
  switch_after_offline_mins = 120,
  switch_time = 1546344000, -- 01.01.2019 - 12:00 UTC
  connection_check_targets = {
    '2001:4860:4860::8888',
    '2001:4860:4860::8844',
  },
},

gluon-web-admin

This package allows the user to set options like the password for ssh access within config mode. You can define in your site.conf whether it should be possible to access the nodes via ssh with a password or not and what the minimum password length must be.

site.conf

config_mode.remote_login.show_password_form : optional

• true the password section in config mode is shown
• false the password section in config mode is hidden
• defaults to false

config_mode.remote_login.min_password_length : optional

• sets the minimum allowed password length. Set this to 1 to disable the length check.
• defaults to 12

Example:

config_mode = {
  remote_login = {
    show_password_form = true, -- default false
    min_password_length = 12
  }
}

gluon-web-logging

The gluon-web-logging package adds a new section to advanced settings to allow GUI-based configuration of a remote syslog server.

Gluon 2020.1

This is the first release of Gluon in 2020, based on OpenWrt 19.07. It introduces the ath79 target, which will replace ar71xx in the short term.

Added hardware support

ath79-generic

• devolo WiFi pro 1200e
• devolo WiFi pro 1200i
• devolo WiFi pro 1750c
• devolo WiFi pro 1750e
• devolo WiFi pro 1750i
• devolo WiFi pro 1750x
• GL.iNet GL-AR300M-Lite
• OCEDO Raccoon
• TP-Link Archer C6 v2

ipq40xx-generic

• Aruba AP-303
• Aruba Instant On AP11
• AVM FRITZ!Repeater 1200

ipq806x-generic

• Netgear R7800

lantiq-xway

• AVM FRITZ!Box 7312
• AVM FRITZ!Box 7320
• AVM FRITZ!Box 7330
• AVM FRITZ!Box 7330 SL

lantiq-xrx200

• AVM FRITZ!Box 7360 (v1, v2)
• AVM FRITZ!Box 7360 SL
• AVM FRITZ!Box 7362 SL
• AVM FRITZ!Box 7412

mpc85xx-p1020

• Enterasys WS-AP3710i
• OCEDO Panda

ramips-mt7620

• TP-Link Archer C2 (v1)
• TP-Link Archer C20 (v1)
• TP-Link Archer C20i
• TP-Link Archer C50 (v1)
• Xiaomi MiWifi Mini

ramips-mt7621

• Netgear EX6150 (v1)
• Netgear R6220

ramips-mt76x8

• GL.iNet VIXMINI
• TP-Link TL-MR3020 (v3)
• TP-Link TL-WA801ND (v5)
• TP-Link TL-WR902AC (v3)

Removed hardware support

• ALFA Network Hornet-UB [1]
• ALFA Network Tube2H [1]
• ALFA Network N2 [1]
• ALFA Network N5 [1]

[1]	(1, 2, 3, 4) The kernel partition on this device is too small to build a working image.

Major changes

OpenWrt 19.07

Gluon v2020.1 is the first release to use OpenWrt 19.07. All targets therefore use Linux 4.14.166.

batman-adv compat v14 removal

Support for the long deprecated compat 14 version of batman-adv has been dropped. Communities still using this version should migrate to batman-adv using the scheduled domain switch.

IBSS wireless mesh removal

Support for the IBSS wireless protocol has been dropped. Communities still using IBSS are suggested to migrate to 802.11s using the scheduled domain switch.

Performance enhancements

We install zram-swap by default on ar71xx devices with 8MB of flash and 32MB of RAM.

Renamed targets

• The ipq40xx target was renamed to ipq40xx-generic.
• The ipq806x target was renamed to ipq806x-generic.

Status Page

• Gateway nexthop information has been added to the statuspage when batman-adv is used. This includes its MAC address and prettyname as well as the interface name towards the selected gateway.
• The site name has been added to the statuspage. If the node is in a multidomain setup it will also show the domain name.

DECT button to enter config mode

Many AVM devices don’t feature a separate RESET/WPS button, therefore starting this release we support entering the config mode via DECT buttons.

X86 partition size

The x86 partition size has been reduced to fit on disks with a capacity of 128 MB.

Bugfixes

Autoupdater aliases

We have added several new aliases for autoupdater compatibility on the following devices:

• Ubiquiti UniFi AC LR
• Raspberry Pi

Site changes

site.mk

• The GLUON_WLAN_MESH variable can be dropped, as 802.11s is the only supported wireless transport from now on.

Internals

Linting Targets

Support for linter make targets was added.

• make lint
• make lint-sh to only check shell scripts
• make lint-lua to only check lua scripts

These require the shellcheck and luacheck tools. The docker image has been updated accordingly.

Continuous integration

We have implemented continuous integration testing using Jenkins and thereby ensure that all lua and shell scripts are linted, that the documentation still builds and warnings are highlighted, and that Gluon still compiles, by testing a build on the x86_64 target. We expect this to significantly improve the feedback cycle and quality of contributions.

Gluon 2019.1.2

Bugfixes

• Fixes a buffer-overflow vulnerability in libubox, a core component of OpenWrt (CVE-2020-7248)
• Fixes a vulnerability in the OpenWrt package manager (opkg). By using this vulnerability, an attacker could bypass the integrity check of the package artifacts. (CVE-2020-7982)

Other Changes

• Linux kernel has been updated to either
  • 4.9.211 (ar71xx, brcm2708, mpc85xx) or
  • 4.14.167 (ipq40xx, ipq806x, mvebu, ramips, sunxi, x86).

Known issues

• Out of memory situations with high client count on ath9k. (#1768)

• The integration of the BATMAN_V routing algorithm is incomplete.

  • Mesh neighbors don’t appear on the status page. (#1726)

    Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput

    metric.
  • Throughput values are not correctly acquired for different interface types.

    (#1728)

    This affects virtual interface types like bridges and VXLAN.

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware especially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2019.1.1

Bugfixes

• Fixes device alias for Ubiquiti UniFi AC LR. (#1834) Autoupdates on this model were impossible before, since we were missing the proper device alias.
• Add correct ath10k firmware package for OCEDO Koala. (#1838)
• Fixes various batman-adv bugs with backports from 2019.4 and 2019.5 by updating the openwrt-routing packages feed.
• Fixes node role list. (#1851) With Gluon v2019.1 it became impossible to change the role of a node via the config mode.

Other Changes

• Linux kernel has been updated to either
  • 4.9.207 (ar71xx, brcm2708, mpc85xx) or
  • 4.14.160 (ipq40xx, ipq806x, mvebu, ramips, sunxi, x86).

Known issues

• Out of memory situations with high client count on ath9k. (#1768)

• The integration of the BATMAN_V routing algorithm is incomplete.

  • Mesh neighbors don’t appear on the status page. (#1726)

    Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput

    metric.
  • Throughput values are not correctly acquired for different interface types.

    (#1728)

    This affects virtual interface types like bridges and VXLAN.

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware especially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2019.1

Important notes

Gluon v2019.1.x will be the last series of releases to support batman-adv-legacy (v14 compat) and IBSS (Ad-hoc) mesh links. Migration features have been developed and should be used during this release cycle to migrate to batman-adv v15 compat and/or 802.11s mesh links. These migration features are the scheduled domain switching (since v2018.2.1) and batman-adv module coexistence (since v2019.1, see below). The migration must be completed before an upgrade to future Gluon releases (v2019.2 or later) becomes possible.

With Gluon v2019.1, nodes will not answer respondd queries on [ff02::2:1001]:1001 anymore. Respondd querier setups still using this address must be updated to the new address [ff05::2:1001]:1001 (supported since Gluon v2017.1). This change was required due to cross-domain leakage of respondd data. If you are using hopglass-server to query respondd data, you need to update it to at least commit f0e2c0a5.

If you are upgrading from a version prior to v2018.1, please note that the flash layout on some devices (TP-Link CPE/WBS 210/510) was changed. To avoid upgrade failures, make sure to upgrade to Gluon 2017.1.8 or the latest Gluon 2016.2.x (unreleased) before installing Gluon 2018.1, 2018.2 or 2019.1.

Added hardware support

ar71xx-generic

• D-Link
  • DAP-1330 A1

ar71xx-tiny [1]

• TP-Link
  • TL-WR840N v2

ipq40xx

• 8devices
  • Jalapeno

mpc85xx-p1020 [2]

• Aerohive
  • HiveAP 330

ramips-mt7621

• ASUS
  • RT-AC57U [3]

[1]	This target will be reaching its end of life soon. This means that support in the next major release of Gluon is doubtful.

[2]	This is a new target.

[3]	Device or target does not support AP+IBSS mode: This device or target will not be built when GLUON_WLAN_MESH is set to ibss.

Note

The ipq806x target has been flagged as broken, as none of its devices are fully supported in this OpenWrt release yet. You might have to update your build scripts accordingly.

New features

batman-adv coexistence

To allow a migration from B.A.T.M.A.N. Adv. compat 14 this Gluon release offers the ability to ship both B.A.T.M.A.N. Adv. compat versions 14 and 15 in the same image. The mesh.batman_adv.routing_algo option is used to decide which module gets loaded and the scheduled domain switching functionality can be used to migrate between the two versions.

Note that if you were using gluon-mesh-batman-adv-14 (“batman-adv-legacy”) before you will need to update the mesh.batman_adv.routing_algo setting from BATMAN_IV to BATMAN_IV_LEGACY if you want to stay on v14 compat.

See the mesh section for the site.conf configuration of this feature.

Outdoor Mode

Radio devices hosted outdoors are often affected by different regulation than if they were installed indoors. The outdoor mode allows for the reconfiguration of 5 GHz radios onto different channels and channel ranges. Regulatory policies like DFS currently make it difficult to use the 5 GHz band for mesh networking because it’s never certain that nodes will stay on the same channel. If enabled, by setting wifi5.outdoor_chanlist, a number of devices that are commonly installed outdoors will have outdoor mode automatically enabled during their initial setup, specifically:

• Ubiquiti

  • Bullet M
  • Litebeam M5
  • Nanostation M5
  • Nanostation M5 Loco
  • Rocket M5
  • Rocket M5 TI
  • Unifi AC Mesh
  • Unifi AC Mesh Pro
  • Unifi Outdoor

• TP-Link

  • CPE510
  • WBS510

See the wifi5 section for the site.conf configuration of this feature.

Device Deprecation

The ar71xx-tiny and several devices in the ramips-rt305x target have been marked as deprecated. The GLUON_DEPRECATED flag was introduced to offer communities the choice on how to deal with the ending support for those devices. Devices or targets marked as deprecated will very likely not be included in following Gluon releases anymore, usually due to their insufficient flash size.

See the Build configuration section for details.

Hoodselector: Geolocation Mode

The new hoodselector package allows a node to automatically reevaluate its selected mesh domain at runtime. In this release we support its geolocation feature.

See the gluon-hoodselector documentation for details.

x86 images support firstboot

x86 images are now using squashfs instead of ext4 and can now have their configuration reset by using firstboot.

Bugfixes

• Fixes passwordless SSH access when gluon-authorized-keys was used without gluon-setup-mode. (#1777)
• Fixes cross-domain leakage of respondd data by not joining the link-local multicast group on br-client. Nodes will not be answering respondd queries on [ff02::2:1001]:1001 anymore. Respondd queries using that address must be updated to the new address [ff05::2:1001]:1001. (#1701)

Site changes

When updating a site configuration from Gluon 2018.2.x, the following changes must be made:

site.mk

• We now require the GLUON_DEPRECATED variable to be set to decide how to handle the image generation for deprecated devices. (#1745)
• The variable DEVICES that controls which devices to build images for has been renamed to GLUON_DEVICES. (#1686)
• The gluon-radvd package is now included by default and can be dropped from FEATURES and GLUON_SITE_PACKGES.

site.conf

• The mesh.batman_adv.routing_algo option is now required when the batman-adv routing protocol is used. (#1622)

  To continue using batman-adv v14 compat you need to set this option from BATMAN_IV to BATMAN_IV_LEGACY.

• The options wifi*.basic_rates and wifi*.supported_rates have been removed, as the legacy 802.11b rates are now disabled by default. (#1716)

Gateway recommendations

These are recommendations for running non-Gluon nodes, like for example gateways, in your mesh network:

• Since Gluon v2018.1 the IGMP/MLD segmentation feature was enabled by default. When bat0 is run with a bridge on top the bat0 bridge port should be set to receive all multicast traffic unconditionally:

  # echo 2 > /sys/class/net/bat0/brport/multicast_router
  

  See the chapter on IGMP/MLD Domain Segmentation for more details.

Internals

Debug Build Flag

Setting GLUON_DEBUG=1 will provide firmware images including debugging symbols usable with GDB or similar tools. Requires a device or target with at least 16 MB of flash space, e.g. x86-64. Unset by default.

Lua target files

Target definitions were rewritten in Lua; this was necessary to implement the device deprecation feature. It also offers the option for more flexible tagging of devices in the future. (#1745)

luacheck

Lua scripts can now be properly linted and analyzed using luacheck. Run luacheck package scripts target in the Gluon project root. (#1741)

Docker build environment

A minimal docker-based build environment is now available in contrib/Dockerfile. (#1738)

Reload of domain-related services

A mechanism to reload domain related services is now available. (#1710)

Known issues

• Out of memory situations with high client count on ath9k. (#1768)

• The integration of the BATMAN_V routing algorithm is incomplete.

  • Mesh neighbors don’t appear on the status page. (#1726)

    Many tools have the BATMAN_IV metric hardcoded, these need to be updated to account for the new throughput

    metric.
  • Throughput values are not correctly acquired for different interface types.

    (#1728)

    This affects virtual interface types like bridges and VXLAN.

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware especially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.2.4

End of life

This will be the final release of the v2018.2.x series. Updating to the v2019.1.x release series is the recommended course of action, which should be fairly easy.

Bugfixes

• Fixes device alias for Ubiquiti UniFi AC LR. (#1834) Autoupdates on this model were impossible before, since we were missing the proper device alias.
• Add correct ath10k firmware package for OCEDO Koala. (#1838)
• Fixes various batman-adv bugs with backports from 2019.4 and 2019.5 by updating the openwrt-routing packages feed

Other changes

• Linux kernel has been updated to either
  • 4.9.207 (ar71xx, brcm2708, mpc85xx) or
  • 4.14.160 (ipq40xx, ipq806x, mvebu, ramips, sunxi, x86).

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware especially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.2.3

Added hardware support

ar71xx-generic

• TP-Link
  • CPE210 v3

ar71xx-nand

• Aerohive
  • HiveAP 121

mcp85xx-p1020

• Aerohive
  • HiveAP 330

ramips-mt76x8

• TP-Link
  • TL-MR3420 v5 [1]

[1]	Device or target does not support AP+IBSS mode: This device or target will not be built when GLUON_WLAN_MESH is set to ibss.

Bugfixes

• Fixes passwordless SSH access when gluon-authorized-keys was used without gluon-setup-mode. (#1777)
• Fixes ingress traffic shaping. A necessary kernel config value was not set. (#1790)
• Fixes the generation of the bootloader image for the AVM FRITZ!Box 4040. (#1766)
• Fixes the IBSS mesh on the GL.iNet AR750. The wrong driver/firmware package was previously selected. (#1792)
• Fixes the primary mac selection on the TP-Link Archer C25 v1. (#1771)

Other changes

• Linux kernel has been updated to either
  • 4.9.188 (ar71xx, brcm2708, mpc85xx) or
  • 4.14.137 (ipq40xx, ipq806x, mvebu, ramips, sunxi, x86).

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware especially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.2.2

Removed hardware support

Support for the Onion Omega has been removed since the device does not have an ethernet port, and even with the ethernet shield connected the interface would not have been configured.

Bugfixes

• Fixes vulnerabilities that allowed for remote crashes and denial of service attacks through the Linux kernels TCP selective acknowledgement implementation. (CVE-2019-11477, CVE-2019-11478 and CVE-2019-11479)
• Fixes a bug in the image generation for the Netgear R6120 where the OverlayFS might not be created on boot as the JFFS2 end-of-filesystem marker was omitted by the vendor firmware. This resulted in the router not being able to save its configuration and seemingly “being stuck” in config-mode. (#1722)
• Fixes oddities in the calculation of non-wireless clients published through respondd on batman-adv networks. Previously both the kernel wifi layer and batman-adv were consulted, which led to issues because they use different timeout values. (#1676)
• Fixes doubled batman-adv management overhead, introduced with Gluon v2017.1. A timer in batman-adv was wrongly started twice, resulting in each node emitting not one but two OGMs from the same originator per 5 seconds. (#1446)
• Fixes an issue, where services provided by a node (such as DNS resolver or status-page) might become unavailable due to other misbehaving nodes on the same layer 2 segment. (#1659)
• Fixes traffic shaping not working correctly when using tunneldigger, as well as the migration between fastd and tunneldigger (#1736)

Other changes

• Linux kernel has been updated to 4.9.182 or 4.14.128, depending on the target

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.2.1

Added hardware support

ar71xx-generic

• AVM
  • Fritz!WLAN Repeater 300E

ramips-mt7620

• Nexx
  • WT3020AD/F/H [1]

ramips-mt76x8

• Gl.iNet
  • MT300N (v2) [1]
• Netgear
  • R6120 [1]
• TP-Link
  • Archer C50 (v3, v4) [1]
  • TL-WR841N (v13) [1]

[1]	(1, 2, 3, 4, 5) Device or target does not support AP+IBSS mode: This device or target will not be built when GLUON_WLAN_MESH is set to ibss.

Bugfixes

• Fixes a bug in the batman-adv respondd module that caused duplicate IPv6 addresses in nodeinfo replies (#1615)

  This was visible on the status page and several map implementations. The new implementation uses netlink instead of parsing /proc/net/if_inet6.

• Fixes a localization issue in gluon-config-mode-geo-location which resulted in a partial translation of the wizard’s location section text. (#1611)

• Fixes the display of the improved memory usage estimation in gluon-status-page

  This change was actually already merged in time for v2018.2 but the JavaScript was not rebuilt.

• Fixes automatic updates for several devices by adding and updating the autoupdater image names

  This affects the following devices:

  • GL.iNet GL-AR150,
  • GL.iNet GL-AR300M
  • GL.iNet GL-AR750
  • Raspberry Pi Model B+ Rev 1.2

• Fixes the primary MAC address selection for Unifi AC Lite/Mesh/Pro/Mesh Pro (#1629)

• Fixes low data rate selection for multicast and management frames on ath10k and ath10k-ct (#1644)

  A patchset has been backported that notifies these drivers of requested data rate changes

• Fixes the data rate selection in ath10k and ath10k-ct when no mcast_rate is configured (#1657)

  Previously a missing mcast_rate could result in broken 5 GHz connectivity

New features

Scheduled domain switch

Gluon has support for multiple domains since its v2018.1 release. The scheduled domain switch allows for reliable migrations between domains at a preconfigured time. This can be useful for communities that, among other things, plan to

• migrate between IBSS and 802.11s
• activate VXLAN encapsulation on wired mesh links

Improved frequency band distribution of dual-band radios

A new algorithm that improves the distribution of dual-band radios was added. They will now be evenly distributed between the 2.4 and 5 GHz band, with a preference towards 2.4 GHz.

If a device has only a single dual-band radio, like the AVM FRITZ!WLAN Repeater 300E, it will be configured for 2.4 GHz.

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.2

OpenWrt has been updated to the new major release 18.06.x. Depending on the target, this includes the Linux kernel 4.9.146 or 4.14.89.

The new OpenWrt release introduces a dependency on GNU time. On Debian/Ubuntu, this can be found in the package time. The shell builtin time, which is available by default, is not sufficient.

Added hardware support

ar71xx-generic

• AVM
  • Fritz!WLAN Repeater 450E
• OCEDO
  • Koala
• TP-Link
  • Archer C7 v5
  • TL-WR810N v1
• Ubiquiti
  • UniFi AC Mesh Pro
• ZyXEL
  • NBG6616

ipq40xx [1] [2]

• AVM
  • FRITZ!Box 4040
• GL.iNet
  • GL-B1300
• NETGEAR
  • EX6100v2
  • EX6150v2
• OpenMesh
  • A42
  • A62
• ZyXEL
  • NBG6617
  • WRE6606

ramips-mt7621 [2]

• D-Link
  • DIR-860L B1
• ZBT
  • WG3526-16M
  • WG3526-32M

[1]	New target

[2]	(1, 2) AP+IBSS mode unsupported: This target is not built when GLUON_WLAN_MESH is set to ibss.

Note

The ramips-mt7628 target has been renamed to ramips-mt76x8, and the sunxi target has been renamed to sunxi-cortexa7. You might have to update your build scripts accordingly.

New features

Besides many smaller improvements and optimizations, we’d like to highlight the following larger new features:

OpenStreetMap-based map in config wizard

When the feature config-mode-geo-location-osm (package gluon-config-mode-geo-location-osm) is enabled, the configuration wizard will try to load an OSM-based map to allow the user to specify the node location. Loading the map requires a working internet connection, for example via WLAN (while connected to the Gluon node via Ethernet).

See the config_mode section for the site.conf configuration of this feature.

Experimental support for the Babel mesh routing protocol

As the layer-2 based routing protocol batman-adv does not scale well in large mesh networks, we are experimenting with alternatives. Babel is a promising layer-3 mesh routing protocol, which might become the recommended protocol in a future version of Gluon.

Use the feature flag mesh-babel for Babel. Note that our Babel support is still experimental and not ready for production. If you are interested in trying it out, please contact us on our mailing list or in our IRC channel.

gluon-ebtables-limit-arp enabled by default

The gluon-ebtables-limit-arp package, introduced in Gluon 2018.1, is now included by default. In case of issues, it can be removed by adding -gluon-ebtables-limit-arp to GLUON_SITE_PACKAGES.

Site changes

If an opkg repository for lede was configured the key needs to be migrated to openwrt. lede is ignored and without an openwrt key the default OpenWrt repository is used.

No other changes need to be made to site.conf or site.mk when upgrading from Gluon v2018.1.x.

Internals

• We have switched from LuCI’s nixio library to the more actively developed luaposix

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.1.4

Bugfixes

• Fix regression in autoupdater version comparison function

  Due to a regression in Gluon 2018.1, the autoupdater would incorrectly consider certain version strings equal and not attempt to upgrade. In particular, any string and its prefix were considered equal when the prefix did not end with a digit. For example, the following relations were not evaluated correctly:

  • 1.0 < 1.0.1
  • 1.0~pre < 1.0

• Fix unintended difference between autoupdater version comparison and dpkg/opkg

  Alphanumeric characters were considered less than end-of-string, when the intended behaviour (as implemented by dpkg and opkg) is that only ~ is less than end-of-string. This broke relations like the following:

  • 1.0 < 1.0a
  • 1.0a < 1.0ab
  • 1.0a < 1.0a1

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.1.3

Bugfixes

• Fix kernel module dependency collection for external modules (#1580)

  A regression in v2018.1.2 prevented the batman-adv kmod from being loaded on devices without WiFi drivers.

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.1.2

Bugfixes

• Fix a bug leading to missing IPv6 addresses in respondd announcements (#1523)

  The pattern that was used to match addresses from /proc/net/if_inet6 did not expect interface indexes growing past two characters.

• Mark ipq806x target as broken for unstable client WiFi (#1505)

  Station connections to the QCA9880 radio on the TP-Link C2600s are frequently disconnected, leading to an abysmal user experience.

• Fix button behaviour on FRITZ!Box 4020 (#1544)

  Buttons were triggering an instant reboot into config mode, fix by setting buttons to active low instead of active high.

• Prevent caching of redirects on config mode and status page (#1530)

  As the path to both config mode and status page were changed between versions users could be affected by a redirect to a no more valid URL.

• batman-adv has received two bugfixes, which were backported from v2018.4

Other changes

• Linux kernel has been updated to v4.4.153

Known issues

• Missing kernel module dependencies prevent batman-adv from being loaded on devices without WiFi drivers (#1578)

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.1.1

Bugfixes

• Fix a bug leading to configuration loss on upgrade under certain circumstances (#1496)

  The issue can only occur when upgrading from 2018.1 and there are multiple mirror entries in site.conf (specifically, an early failure for one of the mirrors, e.g. during DNS resolution, followed by a successful upgrade from a different mirror triggers the issue).

  This is a regression in Gluon 2018.1.

• Fix next-node ARP issue (#1488)

  A routing table issue led to ARP requests being sent from the next-node IPv4 address, but with a node-specific source MAC address. This could make the next-node IPv4 address unreachable.

  This is a regression in Gluon 2018.1.

• Fix build on hosts with glibc 2.28

  Fixed by various tool upgrades in LEDE (bison, e2fsutils, …)

Other changes

• Linux kernel has been updated to v4.4.148

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

Gluon 2018.1

Important notes

This version changes the flash partition layout on some devices (TP-Link CPE/WBS 210/510). To avoid upgrade failures, make sure to upgrade to Gluon 2017.1.8 or the latest Gluon 2016.2.x (unreleased) before installing Gluon 2018.1.

Some of the following paragraphs describe so-called “feature flags”. This new concept is explained in Feature flags.

Added hardware support

ar71xx-generic

• ALFA NETWORK
  • AP121F
• AVM
  • FRITZ!Box 4020
• OpenMesh
  • A40
  • A60
  • OM2P v4
  • OM2P-HS v4
• TP-Link
  • Archer C59 v1 [2]
  • CPE210 v2

ar71xx-nand

• ZyXEL
  • NBG6716

ar71xx-tiny

• TP-Link
  • TL-WA901ND v5

ipq806x [1] [2]

• TP-Link
  • Archer C2600

ramips-mt7620 [1] [2]

• GL Innovations
  • GL-MT300A
  • GL-MT300N
  • GL-MT750

ramips-mt7628 [1] [2]

• VoCore
  • VoCore 2

ramips-rt305x [1] [2]

• A5
  • V11
• D-Link
  • DIR615 (D1, D2, D3, D4, H1)
• VoCore
  • VoCore (8MB, 16MB)

sunxi [1]

• LeMaker/SinoVoip
  • Banana Pi (M1)

[1]	(1, 2, 3, 4, 5) New target

[2]	(1, 2, 3, 4, 5) Device or target does not support AP+IBSS mode: This device or target will not be built when GLUON_WLAN_MESH is set to ibss.

New features

Multidomain support

When mesh networks grow too large, it becomes necessary to split them into multiple independent mesh domains to allow the meshes to work with reasonable performance. Formerly, the only way to achieve this with Gluon was to build a separate set of firmware images for each domain.

With Gluon 2018.1, multidomain firmwares can be used to achieve the same, using only a single site configuration that is basis for several different domain-specific configurations. The feature is explained in detail in Multidomain Support.

Wired mesh encapsulation

Gluon now supports encapsulating wired mesh traffic (Mesh on LAN/WAN) in VXLAN. See Wired mesh (Mesh-on-WAN/LAN) for details on this feature.

Router advertisement filtering

Similar to the builtin batman-adv gateway feature for IPv4, the gluon-radv-filterd package (radv-filterd feature flag) allows to filter IPv6 router advertisements received from the mesh so that only the RAs with the best routing metric (TQ) reach the clients, ensuring that the “best” (topologically closest) gateway is chosen as the IPv6 default route, thereby reducing gateway crosstalk.

At the moment, this feature only filters RAs forwarded to clients; the RAs handled on the nodes themselves will be unfiltered, so the nodes will still use arbitrary default gateways.

IGMP/MLD segmentation

The IGMP/MLD segmentation feature previously provided by the gluon-ebtables-segment-mld package has been extended and moved into the Gluon core; it does not exist as a separate package anymore.

Filtering IGMP/MLD queries directed towards the mesh ensures that each node becomes the multicast querier for its own clients (unless there are other multicast-aware switches connected to the node), rather than electing a single, basically arbitrary node in the mesh to become the querier. Overall, this should significantly improve the reliability of multicast in the mesh. This is especially important for IPv6, as the IPv6 Neighbour Discovery Protocol (NDP) is based on local multicast.

See also the documentation of the site.conf mesh section.

gluon-ebtables-limit-arp

The gluon-ebtables-limit-arp (ebtables-limit-arp feature flag) package adds filters to limit the rate of ARP requests client devices are allowed to send into the mesh.

Certain client applications are known to generate a significant amount of such ARP requests and are reportedly becoming more and more common. Without this package, such clients are one known cause for mesh wide load and congestion problems (see also the Known issues section below).

Because of this package’s implementation, which relies on frequent dynamic updates - something ebtables does not perform well at - it is not included by default, as it can cause unnecessary load. Feedback, especially with a close look on load and congestion on nodes with a large number of changing client devices, is very much welcome. Depending on the feedback, we might enable this feature by default in a future release.

Public key in respondd data (optional)

If desired, the fastd public key of a node can be included in the respondd nodeinfo data, facilitating the correlations of VPN peers and nodes. As the VPN key is transmitted unencrypted in the fastd handshake, this would theoretically allow an ISP to determine which nodes are operated behind which internet line. Therefore, this feature must be enabled explicitly by setting mesh_vpn.pubkey_privacy to false in site.conf.

B.A.T.M.A.N. V (experimental)

When using batman-adv compat 15, it is now possible to switch to the new routing algorithm B.A.T.M.A.N. V (while the old algorithm is called B.A.T.M.A.N. IV) by setting mesh.batman_adv.routing_algo to "BATMAN_V". Note that the new routing algorithm is not backwards-compatible, so nodes using different algorithms can not interoperate.

Site changes

site.mk

• Due to improved package dependency handling, the packages gluon-config-mode-core and gluon-setup-mode do not need to be listed explicitly in site.mk anymore; they will be pulled in implicitly.
• Including the ebtables-limit-arp feature flag is recommended. Please note the abovementioned caveats on this feature.
• We recommend to use GLUON_FEATURES for all Gluon packages, and rely on GLUON_SITE_PACKAGES for non-Gluon (OpenWrt) packages only, as explained in Feature flags.
• The GLUON_ATH10K_MESH variable was renamed to GLUON_WLAN_MESH.

site.conf

When updating a site configuration from Gluon 2017.1.x, the following changes must be made:

• domain_seed = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  

  These 32 bytes of random data (encoded in hexadecimal) are used to seed a number of site/domain specific random values that must be the same on all nodes of the same mesh, but different for different meshes. The following command can be used to generate such a random value:

  echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
  

  In multidomain setups, repeat this command for each domain.

  At this time, only the VXLAN ID for wired meshing is derived from the domain seed.

• mesh = {
    vxlan = true, -- or false
    -- ...
  },
  

  In single domain setups, the new mesh.vxlan option is mandatory. It should be set to true in new meshes; existing setups should set it to false to retain compatibility with older versions of Gluon.

  In multidomain setups, mesh.vxlan defaults to true and does not need to be set explicitly. It can still be set to false for individual domains that should allow wired meshing with existing setups, which is also useful for migrating an existing mesh to a multidomain-capable firmware.

• Password change form

  The password change form in the “Advanced settings” is not shown by default anymore, as SSH keys are the recommended means of authentication. It is still possible to set a password via SSH while in config mode.

  Set

  config_mode = {
    remote_login = {
      show_password_form = true,
      -- ...
    },
    -- ...
  },
  

  to restore the old behaviour.

  When shown, the password form requires a minimum password length of 12 characters now. This requirement can be modified using the config_mode.remote_login.min_password_length setting.

• Next-node hostnames

  The builtin DNS resolver of Gluon can be configured to resolve a next-node hostname to the next-node IP address without querying an upstream DNS server. Since Gluon v2018.1, multiple names can be specified. Old configurations setting next_node.name to a string must be updated to provide an array of strings instead:

  next_node = {
    name = { 'nextnode.location.community.example.org' },
    -- ...
  },
  

i18n

It is now possible to override a few labels and descriptions in the configuration wizard. The available message IDs are listed in Config mode texts.

These new i18n strings are optional; leaving them empty or unset will retain the default texts.

Internals

Status page rewrite

The status page has been rewritten to simplify the code and reduce its size. Rather than having a static frontend and retrieving all information via JavaScript, all static information in the status page is now generated on the node, and JavaScript is only used for dynamic data.

Many status page API endpoints have been removed; for all remaining endpoints, CORS (Cross-Origin Resource Sharing) has been disabled, as it led to a privacy issues: malicious websites could access the API via cross-site scripting, determining which node a user was connected to.

The removal of CORS breaks compatibility with the node switching feature of the old status page implementation: In the new status page, switching to another node will reload the whole status page from the target node, while the old implementation would only switch to another backend host. While this will facilitate future updates, as frontend and backend always come from the same node and no stable API needs to be maintained, it prevents switching from the old status page to nodes running the new version.

To achieve all this, the status page was ported to the gluon-web framework. The new status page also makes use of Gluon’s usual i18n facilities now. In addition, the gluon-web-model package was split out of the gluon-web core package, as model support is only required for config mode packages, but not for the new status page.

i18n namespaces

In earlier version of Gluon, all gluon-web (formerly LuCI) packages shared the same i18n namespace, so independent packages could override each others translations (with an arbitrary translation of the same string “winning”). This issue has been solved by giving each package its own translation namespace, which is defined by the package directive in a package’s controller. It is still possible to access a different i18n namespace (e.g. gluon-web base or site translations), which is described in Internationalization support.

Package Makefile cleanup

The Makefiles of the individual Gluon packages have been cleaned up significantly by moving a lot of boilerplate code to package/gluon.mk. The new features of package/gluon.mk are explained in detail in Package development.

Site checker

• New JSON/Lua path specification

  The old string-based path specifications in site check scripts (e.g. 'autoupdater.branch') have been replaced with arrays ({'autoupdater', 'branch'}). This will implicitly ensure that autoupdater is a table when it exists (simplifying checks for deep structures), and it makes it easier to specify paths with variable components (by referencing a variable as an array element).

• Alternatives

  The site check library has gained support for alternatives. It is now possible to check if a configuration satisfies one of multiple checks:

  -- foo can be a boolean or a string!
  alternatives(function()
    need_boolean({'foo'})
  end, function()
    need_string({'foo'})
  end)
  

  As many branches (functions) as necessary can be passed to a single alternatives call, which will succeed when at least one of the branches succeeds.

batman-adv multicast optimizations

After various extra rounds of testing and fixes, the batman-adv (compat 15) multicast optimizations were reenabled: knowledge about potential multicast listeners is gathered and distributed through the mesh again.

This is the next step towards the addition of the actual multicast distribution optimizations, which are being prepared in #1357. When finished, the optimizations will help reduce the remaining Layer-2-specific network overhead, e.g. multicasted ICMPv6 messages.

No behaviour changes are expected yet, as the multicast sender side is still disabled. Once the majority of the mesh network has been updated to Gluon 2018.1, it can be activated on dedicated nodes by including #1357 in the firmware build. Test feedback is very welcome.

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory or high load due to memory pressure on weak hardware specially in larger meshes (#1243)

  Optimizations in Gluon 2018.1 have significantly improved memory usage. There are still known bugs leading to unreasonably high load that we hope to solve in future releases.

• Configuration loss on upgrade under certain circumstances (#1496)

  The issue can only occur when upgrading from 2018.1 and there are multiple mirror entries in site.conf (specifically, an early failure for one of the mirrors, e.g. during DNS resolution, followed by a successful upgrade from a different mirror triggers the issue).

  This is a regression in Gluon 2018.1.

• Next-node ARP issue (#1488)

  A routing table issue leads to ARP requests being sent from the next-node IPv4 address, but with a node-specific source MAC address. This can make the next-node IPv4 address unreachable.

  This is a regression in Gluon 2018.1.

Gluon 2017.1.8

Added hardware support

ar71xx-generic

• GL.iNet GL-AR750
• TP-Link Archer C7 v4
• Ubiquiti UniFi AC Mesh

ar71xx-tiny

• TP-Link TL-WR940N v6

Bugfixes

• Fix refcounting issue in batman-adv leading to hangs on interface restarts (#1258)

  This fix applied to both batman-adv compat 14 (legacy) and 15.

• Various batman-adv bugfixes have been backported (f5b3c0c3bc7e and 5947ba300e50, fixing #1321, #1380, #1382, #1419 and a number of other minor issues)

  The listed bugs could lead to high rates of batman-adv management traffic (causing considerable load), trigger warnings about packet checksum failures in certain non-standard interface configurations, and possibly other issues.

Other changes

• Linux kernel has been updated to v4.4.129 (LEDE/81573ea25924)

• The description of the “contact information” field in the configuration wizard has been extended with regard to the EU General Data Protection Regulation (GDPR) (fd355cf0ef7b)

  The mandatory site option for the contact information field has been removed.

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory on weak hardware in larger meshes (#1243)

Gluon 2017.1.7

Bugfixes

• Fix boot failure on many Ubiquiti devices (#1370)

  A kernel update in Gluon 2017.1.6 led to boot failures on Ubiquiti Airmax M2/M5 (NanoStation, Bullet, etc.) if the device had been running AirOS 5.6 before installing Gluon/OpenWrt. The XW hardware revision is unaffected.

  While the root cause is a bug in Ubiquiti’s bootloader, the issue is mitigated in Gluon 2017.1.7.

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory on weak hardware in larger meshes (#1243)

Gluon 2017.1.6

Bugfixes

• Remove broken DNS cache feature (#1362)

  It was found that dnsmasq does not handle all answer records equally. In particular, its cached answers are missing DNSKEY and DS records, breaking DNSSEC validation on clients.

  Nodes can still resolve the next-node hostname locally and will continue to work as DNS forwarders. The DNS cache feature may return if dnsmasq is fixed or if we switch to a different resolver.

• Ensure that corefiles are stored in /tmp rather than cluttering the root filesystem (00df8b76e54c)

  Nodes upgrades from Gluon v2016.2.x or earlier did not set kernel.core_pattern correctly, leading to corefiles being stored in the current directory (usually / for system services) in the case of crashes.

  This is a regression introduced in Gluon v2017.1.

• Only request a single IPv6 address instead of a prefix on the WAN interface (5db54ba78c3)

• Fix signal graph on status page when there are many neighbours (packages/d1e0b6e0bdae)

• Fix config files managed by opkg not being saved on sysupgrades on ar71xx-tiny (LEDE/17c0362178ca, LEDE/75be005e8bdc)

• Fix kernel crash in batman-adv-14 (#1358)

  Starting with Gluon v2017.1, respondd could trigger a kernel crash caused by a use-after-free in batman-adv-14, in particular after a gateway disappeared.

  batman-adv-15 is not affected.

• Increase bridge multicast querier timeout (“robustness”) to avoid “querier appeared/disappeared” log spam by batman-adv in the presence of an external querier (e305a8c01917)

• Fix “broken pipe” log spam caused by the status page (883c32f2f1dc)

• Reduce memory limit of WLAN packet queues to 256KB on devices with small RAM (e63c6ca01f50)

  Will hopefully make out-of-memory crashes in busy meshes less likely.

• Improve image validation for TP-Link CPE/WBS 210/510 and make it ready for future images (LEDE/6577fe2198f5)

  Future OpenWrt/Gluon images will move the image metadata (“support-list”) of the CPE/WBS 210/510 images to a different offset. Make sysupgrade ready to allow installing such images.

  This change was also backported to Gluon v2016.2.x to allow direct updates to future Gluon master versions without installing v2017.1.x first.

• Sporadic segfaults of busybox (ash) when running shell scripts on ar71xx have disappeared with the latest updates (#1157)

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Frequent reboots due to out-of-memory on weak hardware in larger meshes (#1243)

Gluon 2017.1.5

Added hardware support

ar71xx-generic

• TP-Link TL-WR1043N v5

ramips-mt7621

• Ubiquiti EdgeRouter-X
• Ubiquiti EdgeRouter-X SFP

Bugfixes

• Fix build with empty site/modules (#1262)
• Fix Ethernet stalls at high throughput on certain devices (#1101)
• Update Tunneldigger to support connections with servers running newer kernel versions (9ed6ff752eb7)
• Fix batman-adv Bridge Loop Avoidance (BLA) with gluon-ebtables-filter-multicast (#1198)

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Sporadic segfaults of busybox (ash) when running shell scripts on ar71xx (#1157)

  The workaround added in Gluon v2017.1.1 has greatly reduced the frequency of segfaults, but it did not make them disappear completely.

• Frequent reboots due to out-of-memory on weak hardware in larger meshes (#1243)

Gluon 2017.1.4

Added hardware support

ar71xx-generic

• GL Innovations GL-AR300M

Bugfixes

• LEDE has been updated to the latest stable commit, including various fixes for the kernel (including security updates), and making opkg work again. This also includes fixes for the KRACK issue (which is irrelevant for most Gluon deployments, as Gluon nodes are rarely used as WLAN clients) (b62af904bbfd, ba56b41ddaf6, ad0824136e5b, 017fbe88bb8a)
• Fix DNS resolution for mesh VPN (fastd / tunneldigger) on ARM-based targets (#1245)
• Fix a build issue in kmod-jool (06842728233a)
• Fix enabling/disabling PoE Passthrough in site.conf or in the advanced settings (7268e49a301f, 7c2636d28264)

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Sporadic segfaults of busybox (ash) when running shell scripts on ar71xx (#1157)

  The workaround added in Gluon v2017.1.1 has greatly reduced the frequency of segfaults, but it did not make them disappear completely.

Gluon 2017.1.3

The LEDE base of Gluon has been updated to v17.01.3, including various updates, stability improvements and security fixes. This includes some critical fixes to core packages like dnsmasq (see below for details); upgrading all Gluon nodes to v2017.1.3 is highly recommended.

Bugfixes

• dnsmasq has been upgraded to v2.78, fixing CVE-2017-13704, CVE-2017-14491, CVE-2017-14492, CVE-2017-14493, CVE-2017-14494, 2017-CVE-14495 and 2017-CVE-14496

  While many of the most severe (remote code execution) vulnerabilities are in the DHCP component of dnsmasq, which is not active on a Gluon node unless in Config Mode, CVE-2017-14491 does affect us. An attacker can cause memory corruption and possibly remote code execution by deploying a malicious DNS server and tricking a node into querying this server.

• The Linux kernel has been upgraded to v4.4.89

• Multiple security issues have been fixed in packages that are not usually part of the Gluon build, including tcpdump, curl and mbedtls

  Please refer to the LEDE commit log for details.

• Filtering of multicast packets between the mesh and the local-node interface has been fixed (#1230)

  This issue was causing gluon-radvd to send a router advertisement to the local clients whenever a router solicitation from the mesh was received. In busy meshes, it would continuously send router advertisements every 3 seconds.

• Reject autoupdater mirror URLs not starting with http:// during build (9ab93992d1fc)

• Fix MAC addresses on TP-Link TL-WR1043ND v4 when installing Gluon over newer stock firmwares (#1223)

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Sporadic segfaults of busybox (ash) when running shell scripts on ar71xx (#1157)

  The workaround added in Gluon v2017.1.1 has greatly reduced the frequency of segfaults, but did not make them disappear completely.

Gluon 2017.1.2

New features

• Preserve gw_mode on sysupgrades (#1196)

  When a Gluon node is used as uplink (for example by connecting it to a router with a DHCP server directly, instead of using non-Gluon servers for the internet uplink), the gw_mode must be set to server on that node. The changed gw_mode is now preserved on upgrades.

• Allow configuring the batman-adv routing algorithm (BATMAN IV or BATMAN V) in site.conf (#1185)

  BATMAN V still hasn’t received extensive testing (and is incompatible with BATMAN IV). This new option allows to set up BATMAN V-based test meshes. If unset, the routing algorithm will default to BATMAN IV.

  Configuration:

  mesh = {
    batman_adv = {
      routing_algo = 'BATMAN_V'
    }
  }
  

• New show-release Make target

  The command make show-release can be used to print the release number defined by GLUON_RELEASE to the standard output. This can be useful for build scripts when a $(shell ...) expression is used in site.mk to generate the release number.

Bugfixes

• The image build code used for some devices has been fixed, solving multiple issues (#1193)

  Problems caused by this issue include:

  • sysupgrade rejecting Allnet images
  • OpenMesh devices losing their configuration on upgrades

  This is a regression introduced in Gluon v2017.1.

• Improve sysupgrade error handling (#1160)

  If for some reason processes don’t react to SIGKILL (usually because of a kernel bug), a node could hang forever in sysupgrade, requiring a power cycle. This has been fixed, triggering a reboot instead.

• Also display gluon-config-mode:novpn message when Tunneldigger is installed, but disabled (#1172)

  It was only displayed on nodes with fastd before.

• Fix migration of enabled/disabled state between fastd and Tunneldigger (#1187)

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Sporadic segfaults of busybox (ash) when running shell scripts on ar71xx (#1157)

  The workaround added in Gluon v2017.1.1 has greatly reduced the frequency of segfaults, but did not make them disappear completely.

Gluon 2017.1.1

Bugfixes

• The autoupdater manifest has been extended to allow automatic upgrades from old x86-kvm and x86-xen_domu systems to the new x86-generic image (869ceb4)

• Make flash writable again on Ubiquiti PicoStations with certain bootloader versions (and possibly other devices) (9a787c9)

  Units affected by this issue running Gluon v2017.1 can’t leave config mode and no regular sysupgrades are possible. TFTP recovery is necessary to make them work again.

• Add workaround to prevent sporadic segfaults of busybox (ash) when running shell scripts on ar71xx (#1157)

• Disable batman-adv multicast optimizations to work around issue causing large amounts of management traffic (819758f)

  Multicast optimizations will be enabled again when a proper fix is available.

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2017.1

General changes

Gluon 2017.1 is the first release of Gluon based on the LEDE 17.01 branch. The kernel has been updated from 3.18.x to 4.4.x.

We’ve used the opportunity to greatly simplify the Gluon build system, removing many hacks that were required to make the build work with older OpenWrt releases.

The output/modules directory is now called output/packages and provides a replacement for the whole repository with target-specific packages of LEDE (in contrast to packages that are common for all targets of the same architecture). Another change to the build system makes it necessary that the same GLUON_RELEASE value that is used to build the images is also set for make manifest.

GCC 4.8 or newer is now required to build Gluon.

Note: There is an issue in all Gluon versions before 2016.2.6 that will lead to x86 systems losing their configuration when upgrading to Gluon 2017.1! Older Gluon versions should be upgraded to 2016.2.6 first before switching to 2017.1.

Another potential issue mostly affects virtual machines: Gluon 2017.1 images are bigger than 2016.2.x images on x86. If your virtual harddisk is based on a 2016.2.x image, it must be resized to 273MB or bigger before upgrading to Gluon 2017.1. Using qemu, the command

qemu-img resize $IMAGE 273MB

can be used to do this.

Added hardware support

ar71xx-generic

• TP-Link
  • RE450
  • WBS210 v1.20
  • WBS510 v1.20
• Ubiquiti
  • AirGateway LR
  • AirGateway PRO
  • Rocket M2/M5 Ti
  • UniFi AP LR

ar71xx-tiny

The new ar71xx-tiny target has split out of ar71xx-generic; all ar71xx-generic devices with only 4MB of flash have been moved to this target.

In contrast to ar71xx-generic, ar71xx-tiny does not support opkg anymore to save some space.

• TP-Link
  • TL-WA730RE v1
  • TL-WA7210N v2

x86-generic

The x86-kvm and x86-xen_domu targets have been removed; the x86-generic images now support these use cases as well, so no separate targets are needed anymore.

x86-geode

The new x86-geode target for hardware based on Geode CPUs has been added.

New features

• Localization support has been added to the status page. In addition to German, there are English and Russian translations now (#1044)

• Add support for making nodes a DNS cache for clients (#1000)

• Add L2TP via tunneldigger as an alternative VPN system (#978)

  L2TP will usually give better performance than fastd as it runs in kernel space, but it does not provide encryption. Also, tunneling over IPv6 is currently unsupported by tunneldigger.

  It is not possible to include both fastd and tunneldigger in the same firmware.

• Add source filter package (#1015)

  The new package gluon-ebtables-source-filter can be used to prevent traffic using unexpected IP addresses or packet types from entering the mesh.

  See also: gluon-ebtables-source-filter

Bugfixes

• Disabling batman-adv on an interface (for example when an Ethernet link is lost or before sysupgrades) could lead to a kernel crash in certain configurations (#680)

• A race condition in the network setup scripts could lead to incomplete setup during boot or when interfaces were added or removed from batman-adv after Ethernet link changes (#905)

  The fix also solved the long-standing issue of Ethernet-only nodes (i.e. no WLAN or VPN mesh) not booting up correctly without an Ethernet mesh link.

• Some fixes in the WLAN stack of LEDE have improved the stability of the ath9k driver (#605)

Site changes

site.mk

• The gluon-legacy package does not exist anymore
• All gluon-luci- packages have been renamed to gluon-web-; gluon-luci-portconfig is now called gluon-web-network
• The gluon-next-node package has been merged into the Gluon core and must not be specified in site.mk anymore

site.conf

• The fastd_mesh_vpn configuration section has been restructured to allow sharing more options with tunneldigger. Instead of

  fastd_mesh_vpn = {
    mtu = 1280,
    configurable = true,
    methods = {'salsa2012+umac'},
    groups = { ... },
    bandwidth_limit = { ... },
  }
  

  the configuration must look like this now:

  mesh_vpn = {
    mtu = 1280,
    fastd = {
      configurable = true,
      methods = {'salsa2012+umac'},
      groups = { ... },
    }
    bandwidth_limit = { ... },
  }
  

• The opkg.openwrt option has been renamed to opkg.lede

i18n

• The escape function has been removed as it was duplicating the existing pcdata function. All uses of escape in i18n templates must be changed to use pcdata instead.
• The gluon-config-mode:altitude-label and gluon-config-mode:altitude-help translation IDs have been added to allow adjusting the texts for different kinds of altitudes that might be expected.
• The optional gluon-config-mode:novpn label has been added, which will be shown in place of gluon-config-mode:pubkey when mesh VPN is disabled.

Internals

• The LuCI base libraries have been replaced by a stripped-down version called “gluon-web” (#1007)

  Custom packages will need to be adjusted; in particular, all uses of luci.model.uci need to be replaced with simple-uci. The Gluon documentation explains the most important changes required to migrate from LuCI to gluon-web.

• respondd now listens on ff05::2:1001 in addition to ff02::2:1001 for mesh-wide operation (#984)

  Eventually, ff02::2:1001 will be available for exchanging information between neighbouring nodes only; map servers should be moved to ff05::2:1001.

• batman-adv has been updated to version 2017.1

• Directly running make commands in the lede directory is supported now. Consequently, build targets like target/linux/clean and package/NAME/compile can’t be used in the Gluon repository root anymore.

  The command make config will set up the LEDE .config in the way a normal Gluon build would, so it’s possible to build individual packages for testing and development afterwards.

• Target definitions have been migrated from a Make-based format to a simpler shell-based DSL

• Gluon does not pass any custom variables into the LEDE build anymore, so things like GLUONDIR, GLUON_VERSION, or GLUON_SITEDIR aren’t available to package Makefiles in Gluon 2017.1.

  Instead of $(GLUONDIR)/package.mk, $(TOPDIR)/../package/gluon.mk must be included in custom packages now.

Known issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.2.7

This release only fixes a single regression introduced in Gluon v2016.2.6, and add support for building using Perl 5.26.

Bugfixes

• Improve sysupgrade error handling (#1160)

  If for some reason processes don’t react to SIGKILL (usually because of a kernel bug), a node could hang forever in sysupgrade, requiring a power cycle. This has been fixed, triggering a reboot instead.

• Backport fixes to support building with Perl 5.26 or newer (76753ed)

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.2.6

Added hardware support

ar71xx-generic

• TP-Link TL-WR841N/ND v12

Bugfixes

• Fix CVE-2016-10229 (#1097)

  Fortunately, the standard Gluon setup is not vulnerable, as the issue only affects applications that use MSG_PEEK on UDP sockets. dnsmasq does use MSG_PEEK, but only in the DHCP component, which is not enabled during normal node operation.

• Fix roaming issue affecting communication between clients (#1121)

  This issue affects all previous releases of Gluon v2016.2.x.

• Fix build against OpenSSL 1.1 (b6a22ce)

• Fix build with long path names (#1120)

• Use new staged sysupgrade procedure (d4a69c0)

  The new sysupgrade fixes an issue affecting x86, causing nodes to lose their configuration on upgrade when the size of the kernel partition grows. This is the case when upgrading from Gluon v2016.2.x to newer (LEDE-based) Gluon versions. This means that a Gluon node running an older version must be upgraded to Gluon v2016.2.6 first before switching to a LEDE-based version!

  One downside of the staged sysupgrade is that all processes, including the SSH server, will be terminated at the start of the sysupgrade to allow unmounting the root filesystem. This makes it impossible to get any feedback from the upgrade process without a serial console.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.2.5

This version contains only a single bugfix for a regression introduced in Gluon v2016.2.4. As the regression affects batman-adv compat 15 only, firmwares using the compat 14 legacy version don’t need to be updated.

Bugfixes

• Fix kernel crash with batman-adv compat 15 (d452a7c)

  An incorrect backport of a fix for a very improbable kernel crash caused a much more frequent kernel crash. The backport has been fixed.

  This bug a regression in Gluon v2016.2.4.

Known Issues

• x86 sysupgrade (sometimes) loses config when kernel partition grows (#1010)

  This issue affects upgrades from v2016.2.x and older to the Gluon master only, we hope to fix it before the next major release.

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.2.4

Bugfixes

• Fix batman-adv (compat 15) not being able to transmit packages of specific sizes (b7eeef9)

  We suspect that this issue was also the reason for the autoupdater/wget hangs observed by many communities. Non-Gluon nodes like gateways should be updated to batman-adv 2017.0.1 to get the fix.

• Fix build after ftp.all.kernel.org discontinuation (#1059)

• Fix high load because of frequent calls of the respondd initscript (9a0aeb9)

  The respondd restart triggers added in v2016.2.3 ran a significant portion of the respondd initscript for each router advertisement received. This was fixed by a backport of a netifd patch.

• x86 sysupgrade fixes (41fd50d, ad37e2b)

  This fixes sysupgrade on mmcblk and similar devices.

Other changes

• The manifest generator has been extended to generate SHA256 checksums in addition to SHA512 ones (f9d59be)

  We have recently switched the autoupdater to SHA256 in the Gluon master to avoid mixing two different lengths of hashes for no good reason. This makes the manifests of Gluon v2016.2.x compatible with the new autoupdater so it doesn’t prevent backports or downgrades.

  Note: Downgrades of major Gluon versions are generally unsupported and will often lead to broken configurations.

Known Issues

• x86 sysupgrade (sometimes) loses config when kernel partition grows (#1010)

  This issue affects upgrades from v2016.2.x and older to the Gluon master only, we hope to fix it before the next major release.

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.2.3

Added hardware support

ar71xx-generic

• TP-Link TL-WR940N v4
• TP-Link TL-WR1043ND v4

Removed hardware support

Support for Meraki devices (MR12/16/62/66) has been removed for now because of severe problems (all devices were using the same MAC addresses). Support will return when the issues have been fixed.

Bugfixes

• Automatically restart respondd on failure (#863)

  There have been many reports of respondd processes disappearing; the exact cause is unclear, but might be related to the batman-adv debugfs interface and/or out-of-memory conditions.

  A new respondd initscript uses procd to automatically restart respondd when it dies.

• Make autoupdater timeouts more robust (#987)

  It was reported that wget processes sometimes hang indefinitely during the autoupdater manifest download. The autoupdater has been improved to ensure that wget can always be interrupted after a timeout.

  This issue, together with the recent addition of lock files to ensure that only one instance of the autoupdater can run at a time, had caused the autoupdater to blocked completely by hanging processes in some cases (till a node was rebooted).

• Fix regulation domain switching in ath10k (#1001)

  Prevents use of too high transmission power in some cases.

• Ensure that prefix6 in site.conf is always a /64 prefix (6b62e2f)

  Other prefix lengths were never supported and don’t make sense in many places the prefix is used. Ensure that such configurations will not pass validation.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.2.2

Added hardware support

ar71xx-generic

• TP-Link
  • CPE210/510 EU/US versions
  • TL-WA801N/ND v3
  • TL-WR841ND v11 EU/US versions

Bugfixes

• Fix boot on certain QCA955x-based devices (e.g. OpenMesh OM5P AC v2) (#965)

  This issue was a regression in Gluon v2016.2.1.

• Build: Fix git downloads from git.kernel.org on Debian Wheezy (#919)

  We’ve switched back from HTTPS to the git protocol for now to avoid using the old GnuTLS version of Debian Wheezy which can’t establish a HTTPS connection with git.kernel.org anymore.

  This issue was a regression in Gluon v2016.2.

• Fix RX filter of Ubiquiti UAP Outdoor+ (d43147a8e03d)

  This issue was a regression in Gluon v2016.2.

• Fix switched WAN/LAN interface assignment on CPE210 (59deb2064d54)

  This issue was a regression in Gluon v2016.2.

• Significantly reduce CPU load used by signal strength LEDs (#897)

• Fix ethernet port of the Ubiquiti UAP AC Lite (#911)

• Build: Don’t use host /tmp directory (f9072a36411b)

  Fixes build when /tmp is mounted with noexec.

• Fix mesh interface type respondd/alfred announcements when using VLANs over IBSS (#941)

• Fix next-node ebtables rules without next_node.ip4 (9dbe9f785d2b)

  Gluon v2016.2 added support for using the next-node feature without specifying an IPv4 address. Some scripts had not been adjusted, making the next-node unreliable when no IPv4 address was specified.

Other changes

• x86-generic and x86-64 images now have PATA and MMC support to allow using them on various devices that were previously unsupported.

• Clean up opkg postinst scripts up on image generation

  OpenWrt does this by default to save a little space.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.2.1

Added hardware support

ar71xx-generic

• TP-Link
  • TL-WA901ND v4

Bugfixes

• Make status page work with disabled cookies/local storage (#912)

• Update kernel to 3.18.44

  Fixes CVE-2016-5195 and CVE-2016-7117. It is unlikely that these issues pose a threat to usual Gluon setups, but installing additional packages may make a system vulnerable. In any case, updating is highly recommended.

• Downgrade mac80211 to an earlier state

  Unfortunately, a mac80211 update that was done shortly before the release of Gluon v2016.2 (that seemed necessary to properly support ath10k devices) had again caused severe ath9k stability issues that remained unreported until v2016.2 was out.

  We have now reverted mac80211 to an earlier state that was reported to be very stable (while keeping the ath10k-specific changes); in addition, some patches that were reported to cause connection or performance issues with certain clients have been reverted. While is it still not perfectly stable, is should be at least as good as (and probably better than) the v2016.1.x release series.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Git HTTPS downloads from git.kernel.org fail on Debian Wheezy (#919)

  The GnuTLS version on Debian Wheezy is too old and can’t establish a connection with git.kernel.org anymore. A newer GnuTLS version is available in wheezy-backports, but as there is no libcurl3-gnutls package linked against the new version, installing the new version has no effect.

Gluon 2016.2

Added hardware support

ar71xx-generic

• ALFA Network
  • Tube2H
  • N2
  • N5
• Buffalo
  • WZR-HP-G300NH2
• GL Innovations
  • GL-AR150
• OpenMesh
  • MR1750 v1, v2 [1]
  • OM2P-HS v3
  • OM5P-AC v1, v2 [1]
• TP-Link
  • Archer C5 v1 [1]
  • Archer C7 v2 [1]
  • TL-WR710N v2.1
  • TL-WR842N/ND v3
• Ubiquiti
  • UniFi AP AC Lite [1]
  • UniFi AP AC Pro [1]

[1]	(1, 2, 3, 4, 5, 6) Device uses the ath10k WLAN driver; no image is built unless GLUON_ATH10K_MESH is set as described in Make variables

brcm2708-bcm2708

• RaspberryPi 1

brcm2708-bcm2709

• RaspberryPi 2

New features

• Many UBNT Airmax XM model names are detected correctly now (e.g., the Loco is no longer displayed as Bullet) (#632)

  Also, various new image aliases have been added for these devices.

• batman-adv: mesh_no_rebroadcast is now enabled for Mesh-on-WAN/LAN (#652)

• The new UCI option gluon-core.@wireless[0].preserve_channels can be used to prevent a changed WLAN channel from being reset on firmware upgrades (#640)

• PoE passthrough can now be configured from site.conf and the Advanced Settings on TP-Link CPE 210/510 and Ubiquiti NanoStations (#328)

• The config mode altitude field can now be hidden using the config_mode.geo_location.show_altitude site.conf setting (#693)

• The contact information field in the config mode can be made obligatory using the config_mode.owner.obligatory site.conf option

• The node name setting in the config mode is no longer restricted to valid DNS hostnames, but allows any UTF-8 string (#414)

• Besides the hostname, public key, site config and primary MAC address, the contact information can now be accessed from config mode site texts

• The functions escape and urlescape for HTML and URL escaping are now available from config mode site texts. They should always be used when including user-provided information like hostnames and contact information in HTML code or URLs.

• Dropbear has been updated to a newer version, enabling new SSH crypto methods and removing some old ones like DSA. This reduces the time needed for the first boot and makes SSH logins faster (#223)

• WLAN basic and supported rate sets have been made configurable, to allow disabling 802.11b rates (#810)

• ath10k-based devices are now supported officially; it’s possible to choose between IBSS- and 11s-capable firmwares in site.mk (#864)

• The prefix4 and next_node.ip4 site.conf options are optional now.

Bugfixes

• The stability of the ath9k WLAN driver has been improved significantly (#605)

  mac80211, hostapd and other related drivers and services have been backported from LEDE 42f559e.

• Extremely slow downloads could lead to multiple instances of the autoupdater running concurrently (#582)

  A lockfile is used to prevent this and timeouts have been added to download processes.

• Usage of static DNS servers on the WAN port has been fixed (#886)

  This is a regression introduced in Gluon v2016.1.6.

Other changes

• The “Expert Mode” has been renamed to “Advanced Settings”

Site changes

site.mk

If you want to support ath10k-based devices, you should set GLUON_ATH10K_MESH and GLUON_REGION as described in Make variables.

i18n

As the hostname field may now contain an arbitrary UTF-8 string, escaping must be added.

Change

<%=hostname%>

to

<%=escape(hostname)%>

Inside of URLs, urlescape must be used instead of escape.

Internals

• Mesh interfaces are now configured in a protocol-independent way in UCI (#870)

  The MAC address assignment of all mesh and WLAN interfaces has been modified to prepare for support of Ralink/Mediatek-based WLAN chips.

• Preparations for supporting the new batman-adv multicast optimizations have been made (#674, #675, #679)

• All Lua code is minified now to save some space

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Advanced Settings is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.1.6

Bugfixes

• build: fix nodejs host build on Debian Wheezy (#776)

• build: fix parallel builds with Make 4.2+

  Trying to use -j N with Make 4.2 would spawn an unlimited number of processes, eventually leading to memory exhaustion.

• build: fix occasional build failure in libpcap package

• build: don’t require hexdump for x86 builds (#811)

  Trying to build Gluon for x86 on systems without hexdump would silently generate broken images.

• Add support for DNS servers given by their link-local IPv6 address in Router Advertisements (#854)

• ar71xx-generic: correctly setup LNA GPIOs on CPE210/510 (#796)

  Improves the reception by about 20dB.

• ar71xx-generic: switch default WAN/LAN assignment on Ubiquiti UAP Pro (#764)

  Switch to the usual “PoE is WAN/setup mode, secondary is LAN” scheme. This only affects new installations; the assignment won’t be changed on updates unless the configuration is reset.

• ar71xx-generic: fix ath10k memory leak (#690)

• ar71xx-generic: add support for new TP-Link region codes (#860)

  TP-Link has started providing US- and EU-specific firmwares for the Archer C7 v2. To generate Gluon images installable from these new firmwares, the GLUON_REGION variable must be set to eu or us in site.mk or on the make command line (the images will still be installable from all old firmwares without region codes).

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Expert Mode is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.1.5

Added hardware support

ar71xx-generic

• OpenMesh

• MR600 (v1, v2)
• MR900 (v1, v2)
• OM2P (v1, v2)
• OM2P-HS (v1, v2)
• OM2P-LC
• OM5P
• OM5P-AN

• Ubiquiti

• Rocket M XW

• TP-LINK

• TL-WR841N/ND v11

Bugfixes

• build: fix race condition caused by using certain make targets (like clean, images or package/*) with parallel build options without doing a full build before

• build: fix package dependency issue causing “recursive dependency” warning

  This dependency issue could lead to broken configurations and reportedly caused failed builds in some cases when additional (site-specific) packages were used.

• build: Gluon will now build correctly with GCC 6 as host compiler

• Fix configuration of batman-adv when VLANs are used on top of IBSS interfaces (regression due to netifd update in Gluon 2016.1.4)

• Add back missing ath10k firmware (regression due to mac80211 update in Gluon 2016.1.4)

• Gluon can now be used on all supported Ubiquiti AirMAX devices without downgrading to AirOS 5.5.x before

  Gluon 2016.1.1 added support for most Ubiquiti AirMAX devices with AirOS 5.6.x without downgrading AirOS, but left some devices (at least some PicoStations and Bullets) with unwritable flash. This issue has been resolved (#687).

• Add upgrade script to automatically remove whitespace from configured geolocation

  The new respondd implementation included in Gluon 2016.1 is stricter about the number format than the old one and doesn’t accept trailing whitespace (so one or both coordinates are missing from the output).

  The Config Mode has been fixed to strip whitespace from numeric fields in new configurations since Gluon 2016.1.1. This still left old configurations, which are now fixed by this script.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Expert Mode is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.1.4

Added hardware support

ar71xx-generic

• 8devices Carambola 2
• Meraki MR12/MR62/MR16/MR66

Bugfixes

• Major update of all WLAN drivers

  We’ve taken the unusual step of updating the WLAN drivers (“wireless-backports”) to a much newer version, as it was reported that the new version fixes unstable WLAN seen in many setups

• Build fix: a race condition causing parallel builds to fail has been fixed

• Build fix: the Gluon tree could get into a state in which all commands fail with “Too many levels of symbolic links”

• Build fix: allow building Gluon on systems with certain versions of dash as /bin/sh

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Expert Mode is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Unwritable flash on some Ubiquiti PicoStations (#687)

  Gluon v2016.1.1 added support for Ubiquiti AirMAX devices with AirOS 5.6.x without downgrading AirOS first before flashing Gluon. It was discovered that on Ubiquiti PicoStations, this downgrade is still necessary, as the flash is not correctly unlocked, leaving the device unable to leave Config Mode and making regular sysupgrades impossible.

  TFTP recovery can be used in this state to flash a new firmware.

Gluon 2016.1.3

Added hardware support

ar71xx-generic

• ALFA Hornet UB / AP121 / AP121U
• TP-Link TL-WA7510N

Bugfixes

• The nondeterministic boot hang (#669) that was thought to be fixed in Gluon v2016.1.2 has resurfaced on other hardware. We believe it is now fixed properly.
• Sysupgrades on the Xen DomU have been fixed.
• Gluon can now be built on systems that use LibreSSL instead of OpenSSL.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Expert Mode is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Unwritable flash on some Ubiquiti PicoStations (#687)

  Gluon v2016.1.1 added support for Ubiquiti AirMAX devices with AirOS 5.6.x without downgrading AirOS first before flashing Gluon. It was discovered that on Ubiquiti PicoStations, this downgrade is still necessary, as the flash is not correctly unlocked, leaving the device unable to leave Config Mode and making regular sysupgrades impossible.

  TFTP recovery can be used in this state to flash a new firmware.

Gluon 2016.1.2

Added hardware support

The x86-generic images now contain the ATIIXP PATA driver, adding support for FUTRO Thin Clients.

Bugfixes

A nondeterministic boot hang (#669) has been fixed. The TL-WR841N v5 seems to be affected in particular, but the kernel bug is not hardware-specific per se.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Expert Mode is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

Gluon 2016.1.1

Added hardware support

ar71xx-generic

• Onion Omega
• TP-Link TL-MR13U v1

Bugfixes

Build

Don’t overwrite the opkg repository key on each build.

AirOS 5.6.x compatibility

Downgrading to AirOS 5.5.x before flashing Gluon on Airmax M XM/XW devices (NanoStation, Bullet, …) is not necessary anymore.

Status page

• Fix purging of disappeared neighbours from the list
• Don’t clear the signal graphs when scrolling in mobile browsers
• Improve browser compatibility (don’t assume the Internationalization API is available, fixes the display of numbers in Firefox for Android)

Config mode

• Strip trailing whitespace from number input fields (LuCI’s validator doesn’t catch this)
• Don’t allow negative bandwidth limits

Failsafe mode

• Fix entering the failsafe mode on the TL-WDR4900.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Expert Mode is recommended.

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd/announced API (#522)

  The current API is inconsistent and will be replaced eventually. The old API will still be supported for a while.

• Nondeterministic production of broken images for some (very old) hardware (#669)

  At the moment it seems like only the TL-WR841N v5 is affected.

Gluon 2016.1

Added hardware support

ar71xx-generic

• Buffalo
  • WZR-HP-G300NH
• D-Link
  • DIR-505 (A1)
• TP-Link
  • CPE210/220/510/520 v1.1
  • TL-WA901N/ND v1
  • TL-WR710N v2
  • TL-WR801N/ND v1, v2
  • TL-WR841N/ND v10
  • TL-WR843N/ND v1
  • TL-WR940N v1, v2, v3
  • TL-WR941ND v6
  • TL-WR1043N/ND v3
• Ubiquiti
  • airGateway
  • airRouter
  • UniFi AP Outdoor+
• Western Digital
  • My Net N600
  • My Net N750

x86-xen_domu

New target containing the necessary drivers for use in Xen.

x86-64

64bit version of x86-generic. The generic image can also be used in KVM with VirtIO.

New features

Kernel module opkg repository

We’ve not been able to keep ABI compatibility with the kernel of the official OpenWrt images. Therefore, Gluon now generates an opkg repository with modules itself.

The repository can be found at output/modules/ by default, the image output directory has been moved from images/ to output/images/. See the updated Getting Started guide for information on the handling of the signing keys for this repository.

The opkg_repo site.conf option has been replaced to allow specifying this and other additional repositories.

New status page

The new status page provides a visually pleasing experience, and displays all important information on a node in a clear manner. It also contains a real-time signal strength graph for all neighbouring nodes to aid with the alignment of antennas.

802.11s mesh support

Gluon now supports using 802.11s for its mesh links instead of IBSS (Adhoc). This will allow supporting more WLAN hardware in the future (like Ralink/Mediatek, which don’t support AP and IBSS mode simultaneously).

Note that batman-adv is still used on top of 802.11s (and 802.11s forwarding is disabled), the mesh routing protocol provided by 802.11s is not used.

Multicast filter extension

The gluon-ebtables-filter-multicast package has been extended to filter out multicast ICMP and ICMPv6 Echo Requests (ping) and Node Information Queries (RFC4620). This prevents pings to multicast addresses like ff02::1 to cause traffic peaks (as all nodes and clients would answer such a ping).

French translation

A French translation for the Config Mode/Expert Mode has been added.

Bugfixes

• Update kernel code for the QCA953x

  Might improve stability of the TP-Link TL-WR841N/ND v9.

• Fix model detection on some Netgear WNDR3700v2

  The broken devices will identify as “NETGEAR “. This also breaks the autoupdater, making a manual upgrade necessary.

• Ensure that odhcp6c doesn’t spawn multiple instances of dhcpv6.script

• Fix support for Buffalo WZR-600DHP

  A flashable factory image is generated now. The sysupgrade image is still shared with the WZR-HP-AG300H.

Site changes

• site.conf

  • New WLAN configuration

    wifi24 and wifi5 need to be updated to a new more flexible format. A configuration using the old format

    {
      channel = 1,
      htmode = 'HT20'
      ssid = 'entenhausen.freifunk.net',
      mesh_ssid = 'xe:xx:xx:xx:xx:xx',
      mesh_bssid = 'xe:xx:xx:xx:xx:xx',
      mesh_mcast_rate = 12000,
    }
    

    would look like this in the new format:

    {
      channel = 1,
      ap = {
        ssid = 'entenhausen.freifunk.net',
      },
      ibss = {
        ssid = 'xe:xx:xx:xx:xx:xx',
        bssid = 'xe:xx:xx:xx:xx:xx',
        mcast_rate = 12000,
      },
    }
    

    The htmode option has been dropped, the channel width is now always set to 20MHz (see https://github.com/freifunk-gluon/gluon/issues/487 for a discussion of this change).

    In addition to the old IBSS (Adhoc) based meshing, 802.11s-based meshing can be configured using the mesh section. Example:

    {
      channel = 1,
      ap = {
        ssid = 'entenhausen.freifunk.net',
      },
      mesh = {
        id = 'mesh.entenhausen.freifunk.net', -- can by any string, human-readable or random
        mcast_rate = 12000,
      },
    }
    

    While using ibss and mesh at the same time is possible, is causes high load in very active meshes, so it is advisable to avoid such configurations.

  • Bandwidth limitation defaults

    The old section simple_tc.mesh_vpn has been moved to fastd_mesh_vpn.bandwidth_limit and the ifname field isn’t used anymore. What looked like this before

    simple_tc = {
      mesh_vpn = {
        ifname = 'mesh-vpn',
        enabled = false,
        limit_egress = 200,
        limit_ingress = 3000,
      },
    }
    

    needs to be changed to

    fastd_mesh_vpn = {
      -- ...
    
      bandwidth_limit = {
        enabled = false,
        egress = 200,
        ingress = 3000,
      },
    }
    

  • opkg repository configuration

    The opkg configuration has been changed to be more flexible and allow specifying custom repositories. Example:

    opkg = {
      openwrt = 'http://opkg.services.ffeh/openwrt/%n/%v/%S/packages',
      extra = {
        modules = 'http://opkg.services.ffeh/modules/gluon-%GS-%GR/%S',
      },
    }
    

    The keys of the extra table (like modules in this example) can be chosen arbitrarily.

    Instead of explicitly specifying the whole URL, using patterns is recommended. The following patterns are understood:

    • %n is replaced by the OpenWrt version codename (e.g. “chaos_calmer”)
    • %v is replaced by the OpenWrt version number (e.g. “15.05”)
    • %S is replaced by the target architecture (e.g. “ar71xx/generic”)
    • %GS is replaced by the Gluon site code (as specified in site.conf)
    • %GV is replaced by the Gluon version
    • %GR is replaced by the Gluon release (as specified in site.mk)

• site.mk

  • The packages gluon-announce and gluon-announced were merged into the package gluon-respondd. If you had any of them (probably gluon-announced) in your package list, you have to replace them.

• i18n/

  • The translations of gluon-config-mode:pubkey now have to show the fastd public key themselves if desired, making the formatting of the key and whether it is shown at all configurable. To retain the old format, add <p> to the beginning of your translations and append:

    "</p>"
    "<div class=\"the-key\">"
    " # <%= hostname %>"
    " <br/>"
    "<%= pubkey %>"
    "</div>"
    

Internals

• OpenWrt has been updated to Chaos Calmer

• mac80211 has been backported from OpenWrt trunk r47249 (wireless-testing 2015-07-21)

  This allows us to support the TL-WR940N v3/TL-WR941ND v6, which uses a TP9343 (QCA956x) SoC.

• Several packages have been moved from the Gluon repo to the packages repo, removing references to Gluon:

  • gluon-cron -> micrond (the crontabs are now read from /usr/lib/micron.d instead of /lib/gluon/cron)
  • gluon-radvd -> uradvd
  • gluon-simple-tc -> simple-tc (the config file has been renamed as well)

• Some of the Gluon-specific i18n support code in the build system has been removed, as LuCI now provides similar facilities

• The C-based luci-lib-jsonc library is now used for JSON encoding/decoding instead of the pure Lua luci-lib-json

• The site config is now stored as JSON on the node. The Lua interface gluon.site_config is still available, and a C interface was added as part of the new package libgluonutil.

• The respondd daemon now uses C modules instead of Lua snippets, which greatly enhances response speed and reduces memory usage. The Gluon integration package has been renamed from gluon-announced to gluon-respondd.

Known Issues

• Default TX power on many Ubiquiti devices is too high, correct offsets are unknown (#94)

  Reducing the TX power in the Expert Mode is recommended.

• batman-adv causes stability issues for both alfred and respondd/announced (#177)

• The MAC address of the WAN interface is modified even when Mesh-on-WAN is disabled (#496)

  This may lead to issues in environments where a fixed MAC address is expected (like VMware when promiscuous mode is disallowed).

• Inconsistent respondd/announced API (#522)

  The current API is inconsistent and will be replaced in the next release. The old API will still be supported for a while.

Gluon 2015.1.2

Added hardware support

ar71xx-generic

• TP-Link
  • TL-WA701N/ND (v2)
  • TL-WA801N/ND (v1)
  • TL-WA830RE (v2)
  • TL-WR740N / TL-WR741ND (v5)

New features

• Ubiquiti Loco M, Picostation M and Rocket M now get their own images (which are just copies of the Bullet M image) so it’s more obvious for users which image to use
• The x86-generic images now contain the e1000e ethernet driver by default

Bugfixes

• Fix download of OpenSSL during build because of broken OpenSSL download servers (again…)

• Fix another ABI incompatibility with the upstream kernel modules which prevented loading some filesystem-related modules

• Fix potential MAC address conflicts on x86 target when using mesh-on-wan/lan

• Fix signal strength indicators on TP-LINK CPE210/510

• Fix the model name string on some NETGEAR WNDR3700v2

• Fix 5GHz WLAN switching channels and losing connectivity when other WLANs using the same channel are detected (including other Gluon nodes…); see https://github.com/freifunk-gluon/gluon/issues/386

• Fix DNS resolution for mesh VPN on IPv6-only WAN; see https://github.com/freifunk-gluon/gluon/issues/397

• gluon-mesh-batman-adv-15: update batman-adv to 2015.0 with additional bugfixes (fixes various minor bugs)

• gluon-mesh-batman-adv-15: fix forwarding of fragmented frames over multiple links with different MTUs

  batman-adv compat 15 doesn’t re-fragment frames that are fragmented already. In particular, this breaks transmission of large packets which are first fragmented for mesh-on-lan/wan and are then sent over the mesh VPN, which has an even smaller MTU. Work around this limitation by decreasing the maximum fragment size to 1280, so they can always be forwarded as long there’s no link with a MTU smaller than 1280.

  See https://github.com/freifunk-gluon/gluon/issues/435

Gluon 2015.1.1

Added hardware support

ar71xx-generic

• TP-Link
  • TL-WA830RE (v1)

New features

The x86-generic and x86-kvm_guest images now support two ethernet interfaces by default. If two interfaces exist during the first boot, eth0 will be used as LAN and eth1 as WAN.

Bugfixes

• Fix German “Expert Mode” label (was “Export Mode”)
• Fix download of OpenSSL during build (because of broken OpenSSL download servers…)
• Fix ABI break causing kernel panics when trying to use network-related modules from the official OpenWrt repository (like kmod-pppoe)
• Fix race conditions breaking parallel build occasionally
• A broken network configuration would be generated when an older Gluon version was updated to 2015.1 with mesh_on_lan enabled in site.conf
• Minor announced/alfred JSON format fixes (don’t output empty lists where empty objects would be expected)

Gluon 2015.1

Added hardware support

Gluon v2015.1 is the first release to officially support hardware that is not handled by the ar71xx-generic OpenWrt target. This also means that ar71xx-generic isn’t the default target anymore, the GLUON_TARGET variable must be set for all runs of make and make clean now.

ar71xx-generic

• Allnet
  • ALL0315N
• D-Link
  • DIR-615 (C1)
• GL-Inet
  • 6408A (v1)
  • 6416A (v1)
  • WRT160NL
• Netgear
  • WNDR3700 (v1, v2)
  • WNDR3800
  • WNDRMAC (v2)
• TP-Link
  • TL-MR3220 (v2)
  • TL-WA701N/ND (v1)
  • TL-WA860RE (v1)
  • TL-WA901N/ND (v2, v3)
  • TL-WR743N/ND (v1, v2)
  • TL-WR941N/ND (v5)
  • TL-WR2543N/ND (v1)
• Ubiquiti
  • Nanostation M XW
  • Loco M XW
  • UniFi AP Pro

ar71xx-nand

• Netgear
  • WNDR3700 (v4)
  • WNDR4300 (v1)

mpc85xx-generic

• TP-Link
  • TL-WDR4900 (v1)

x86-generic

• x86-generic
• x86-virtualbox
• x86-vmware

x86-kvm_guest

• x86-kvm

New features

Multilingual config mode

All config and expert mode modules contain both English and German texts now. The English locale should always be enabled in site.mk (as English is the fallback language), German can be enabled in addition using the GLUON_LANGS setting.

The language shown is automatically determined from the headers sent by the user’s browser.

Mesh-on-LAN

Gluon now supports meshing using a node’s LAN ports. It can be enabled by default in site.conf, and configured by the user using the gluon-luci-portconfig expert mode package.

Please note that nodes without the mesh-on-lan feature enabled must never be connected via their LAN ports.

Extended WLAN configuration

The new client_disabled and mesh_disabled keys in the wifi24 and wifi5 sections allow to disable the client and mesh networks by default, which may make sense for images for special installations.

The new package gluon-luci-wifi-config allows the user to change these settings; in addition, the WLAN adapters’ transmission power can be changed in this package.

fastd “performance mode”

The new package gluon-luci-mesh-vpn-fastd allows the user to switch between the security and performance VPN sections. In performance mode, the method null will be prepended to the method list.

The new option configurable in the fastd_mesh_vpn section of site.conf must be set to true so firmware upgrades don’t overwrite the method list completely (non-null methods will still be overwritten). Adding the gluon-luci-mesh-vpn-fastd package enforces this setting.

Altitude setting in gluon-config-mode-geo-location

The gluon-config-mode-geo-location config mode module now contains an optional altitude field.

gluon-announced rework

The gluon-announced package has been reworked to allow querying it from anywhere in the mesh. In contrast to gluon-alfred, it is based on a query-response model (the master multicasts a query, the nodes respond), while gluon-alfred uses periodic announcements.

For now, we recommend including both gluon-alfred and gluon-announced in Gluon-based firmwares, until gluon-announced is ready to replace gluon-alfred completely, and software like the ffmap backend has been adjusted accordingly.

Nested peer groups

Nested peer groups for the fastd-mesh-vpn-fastd package can now be configured in site.conf, each with its own peer limit. This allows to add additional constraints, for example to connect to 2 peers altogether, but only 1 peer in each data center.

Autoupdater manual branch override

When running the updater manually on the command line, the branch to use can now be overridden using the -b option.

Bugfixes

Accidental factory reset fix

Pressing a node’s reset button for more than 5 seconds would completely reset a node’s configuration under certain conditions.

WAN IPv6 issues

The WAN port would stop to respond to IPv6 packets sometimes, also breaking IPv6 VPN connectivity.

WDR4900 WAN MAC address

The MAC address on the WAN port of the WDR4900 was broken, making this device unusable for mesh-on-wan configurations.

Site changes

• site.conf

  • hostname_prefix is now optional, and is concatenated directly with the generated node ID, in particular no hyphen is inserted anymore. If you want to keep the old behaviour, you have to append the hyphen to the hostname_prefix field of your site.conf.

  • mesh_vpn_fastd: The default peer group name backbone isn’t hardcoded anymore, any group name can be used. Instead, the fastd_mesh_vpn table must now contain an element groups, for example:

    fastd_mesh_vpn = {
        methods = {'salsa2012+umac'},
        mtu = 1426,
        groups = {
            backbone = {
                limit = 2,
                peers = {
                    -- ...
                }
            }
        }
    }
    

  • config_mode: The config mode messages aren’t configured in site.conf anymore. Instead, they are defined language-specific gettext files in the i18n subdirectory of the site configuration (see Config mode texts).

  • roles: The display strings for the node roles aren’t configured in the site.conf anymore, but in the site i18n files. The site.conf section becomes:

    roles = {
        default = 'foo',
        list = {
            'foo',
            'bar',
        }
    }
    

    The display string use i18n message IDs like gluon-luci-node-role:role:foo and gluon-luci-node-role:role:bar.

• site.mk

  • gluon-mesh-batman-adv-15 is now the recommended batman-adv version for new Gluon deployments.
  • The packages gluon-setup-mode and gluon-config-mode-core must now be added to GLUON_SITE_PACKAGES explicitly (to allow replacing them with community-specific implementations).
  • The new GLUON_LANGS variable selects the config mode languages to include. It defaults to en, setting it to en de will select both the English and German locales. en must always be included.

Internals

New upgrade script directory

The distinction between initial and invariant scripts has been removed, all scripts are now run on each upgrade. Instead of having one script directory per package, all upgrade scripts lie in /lib/gluon/upgrade now, so it is possible to define the run order across packages.

Merged package repository

The Gluon-specific packages have been moved to the package directory of the Gluon main repository. The packages repository now only contains packages that will be submitted to the OpenWrt upstream eventually.

Known Issues

Alfred/respondd crashes

https://github.com/freifunk-gluon/gluon/issues/177

Occasional alfred crashes may still occur. As this is caused by a kernel issue, we suspect that respondd, which gluon-announced is based on, is affected in the same way.

Ignored TX power offset on Ubiquiti AirMax devices

https://github.com/freifunk-gluon/gluon/issues/94

The default transmission power setting on many of these devices is too high. It may be necessary to make manual adjustments, for example using the gluon-luci-wifi-config package. The values shown by gluon-luci-wifi-config generally include the TX power offset (amplifier and antenna gain) where available, but on many devices the offset is inaccurate or unavailable.

Gluon 2014.4

Added (and removed) hardware support

• Buffalo
  • WZR-HP-AG300H / WZR-600DHP
  • WZR-HP-G450H
• D-Link
  • DIR-615 (E1) support had to be dropped
• TP-LINK
  • CPE210/220/510/520 (v1)
  • TL-MR3040 (v2
  • TL-WA750RE (v1)
  • TL-WA801N/ND (v2)
  • TL-WA850RE (v1)
  • TL-WR703N (v1)
  • TL-WR710N (v1)
  • TL-WR1043N/ND (v2)

New features

OpenWrt Barrier Breaker

Switching to the new OpenWrt release 14.09 (“Barrier Breaker”) has yielded lots of updates for both the kernel and most packages. Besides better performance, this has also greatly improved stability (far less out-of-memory issues!).

Modular config mode

The old gluon-config-mode package has been split into five small packages, each providing a single section of the config mode form. This simplifies removing or replacing parts of the wizard.

See the Site changes section for details.

Experimental support for batman-adv compat 15

As batman-adv has broken compatibility starting with batman-adv 2014.0 (bumping the “compat level” to 15), Gluon users must decide which batman-adv version to use. The package for the old batman-adv version gluon-mesh-batman-adv has been renamed to gluon-mesh-batman-adv-14, the new version can be used with gluon-mesh-batman-adv-15.

Please note that batman-adv compat 15 still isn’t tested very well (and there are known bugs in the current release 2014.3), so for now we still recommend using compat 14 in “production” environments.

fastd v16

Besides other new features and bugfixes, fastd v16 support the new authentication method “UMAC”. We recommend switching from the old salsa2012+gmac and null+salsa2012+gmac methods to the new salsa2012+umac and null+salsa2012+umac as UMAC is much faster and even more secure than GMAC.

Private WLAN

The new package gluon-luci-private-wifi allows to configure a private WLAN with WPA-PSK in the expert mode which is bridged with the WAN uplink.

Embedding SSH keys

Using gluon-authorized-keys it is possible to embed predefined SSH public keys to firmware images. If gluon-config-mode-* is left out images will be ready to mesh after the first boot with SSH running for further configuration.

Status page resolves nodenames

The tools gluon-announced and gluon-neighbour-info are now available. Using them enables the status page to resolve hostnames and IPs of a nodes’ neighbours.

This will also work on devices with multiple wireless interfaces.

Bugfixes

• Expert Mode: Fixed all SSH keys being removed when a password was set
• gluon-mesh-vpn-fastd: Fixed VPN peers removed from the site.conf not being removed from /etc/config/fastd
• TL-LINK TL-WDR3600/4300: Added workaround for reboot issues
• Improved stability (due to switch to OpenWrt Barrier Breaker)

Site changes

• site.mk
  • Obsolete packages:
    • gluon-config-mode
    • gluon-mesh-batman-adv
  • Recommended new packages:
    • gluon-config-mode-autoupdater
    • gluon-config-mode-hostname
    • gluon-config-mode-mesh-vpn
    • gluon-config-mode-geo-location
    • gluon-config-mode-contact-info
    • gluon-mesh-batman-adv-14 (specify this before all other packages in the site.mk!)

Internals

The switch to Barrier Breaker has led to a multitude of changes all over Gluon:

• The config mode/setup mode is now started by an own set of init scripts in /lib/gluon/setup-mode/rc.d run by procd
• Many tools and services used by Gluon have been replaced by our own implementations to reduce the size of the images:
  • ethtool has been replaced by our minimal Lua library lua-ethtool-stats
  • tc has been replaced by our minimal implementation gluon-simple-tc
  • radvd has been replaced by our minimal implementation gluon-radvd

Known Issues

Alfred crashes

https://github.com/freifunk-gluon/gluon/issues/177

Alfred may still crash unconditionally. Some measures have been taken to aid but the core problem hasn’t been analyzed yet.

Out of memory / batman-adv memory leaks

https://github.com/freifunk-gluon/gluon/issues/216

In some (hopefully rare!) cases batman-adv may still leak memory associated with global TT entries. This may result in kernel panics or out-of-memory conditions.

Ignored tx-power offset on Ubiquiti AirMax devices

https://github.com/freifunk-gluon/gluon/issues/94

There is still no OpenWRT support for determining the transmission power offsets on Ubiquiti AirMax devices (Bullet M2, Picostation M2, Nanostation (loco) M2, …). Use Gluon with caution on these devices! Manual adjustment may be required.

Gluon 2014.3.1

This is a bugfix release.

Bugfixes

• gluon-announced zombie process bug

  gluon-announced was creating zombie processes when answering requests, causing issues with the new status page which is currently in development.

• fastd peers removed from site.conf weren’t removed correctly from the fastd configuration on firmware upgrades

• Expert Mode: setting a password will not remove SSH keys anymore

• alfred has been updated to 2014.3.0

  We hope this solves the alfred stability issues noted by several people.

• gluon-ebtables-filter-ra-dhcp and gluon-ebtables-filter-multicast have been fixed to allow DHCPv6 to work

• Another ath9k patch has been added, which might further improve WLAN stability and performance

New features

• Support for static WAN setups instead of (DHCP/Router Advertisement) has been added; configuration is possible on the port config page of the Expert Mode.

Site changes

• site.conf
  • The new boolean option fastd_mesh_vpn.enabled allows enabling the mesh VPN by default. This value is optional; if it isn’t specified, the mesh VPN will be disabled.

Gluon 2014.3

New hardware support

• Linksys WRT160NL

New features

New autoupdater

The autoupdater has been rewritten.

Two new fields have been added to the manifest:

DATE

Specifies the time and date the update was released. make manifest will take care of setting it to the correct value.

PRIORITY

Specifies the maximum number of days until the update should be attempted (thus lower numbers mean the priority is higher). It must be set either in site.mk or on the make manifest command line.

Updates will be attempted at night, between 04:00 and 5:00, with a specific probability. When less than PRIORITY days have passed (calculated using DATE and the current time), the probability will proportional to the time passed. I.e. the update probability will start at 0 and slowly increase to 1 until PRIORITY days have passed. From then, the probability will be fixed at 1.

Note: For the new update logic to work, a valid NTP server reachable over the mesh (using IPv6) must be configured in site.conf. If the autoupdater is unable to determine the correct time, it will fall back to a behavior similar to the old implementation (i.e. hourly update attempts).

Separation of announced data

The data announced by alfred has been split into two data types:

• nodeinfo (type 158) contains all static information about a node
• statistics (type 159) contains all dynamic information about a node

Both types also contain a new field node_id which contains an arbitrary unique ID (currently the primary MAC address, sans colons) which can be used to match the nodeinfo with statistics information.

gluon-announced

A new daemon has been added in a new package gluon-announced. This daemon can be used for querying the nodeinfo data of a node via link-local multicast on the ad-hoc interfaces.

At the moment, this daemon is not used, but we recommend including it in site.mk nevertheless as we plan to implement a new status page showing some information about neighbor nodes in the next version of Gluon.

VPN over IPv6

It is now possible to use fastd in IPv6 WAN networks. This still needs testing, but it should work well.

Please note that the MTU of 1426 used by many communities for VPN over IPv4 is too big for IPv6 as the IPv6 header is 20 bytes longer (fastd over IPv4 has an overhead of 66 bytes, fastd over IPv6 has an overhead of 86 bytes).

More modular Config Mode

The package gluon-config-mode has been split into multiple packages to simplify the development of extensions. The low-level logic (handling of the button, starting the services for the config mode) has been moved into a new package gluon-setup-mode, while gluon-config-mode only contains the frontend now.

Extended Expert Mode

The Expert Mode now has a nice info page. In addition, the new package gluon-luci-portconfig has been added which allows simple configuration of batman-adv on the WAN interface.

Site validators

The content of the site.conf is now validated when the images are built to make it less likely to accidentally build broken images.

gluon-firewall

The package gluon-firewall has been removed. Its features are now part of the packages gluon-core and gluon-mesh-batman-adv.

gluon-ath9k-workaround

This package installs a cron job which tries to recognize ath9k hangs and restart the WLAN while recording some information. It is very rudimentary and we can’t really recommend using it on “production” nodes.

Bugfixes

Improved ath9k stability

Multiple bugs in the WLAN driver ath9k have been fixed upstream. This should greatly improve the WLAN stability.

odhcp6c 50 day bug

An important update for odhcp6c fixes a bug which caused Gluon nodes to lose their IPv6 addresses on br-client after an uptime of 50 days, making the nodes unable perform automated updates (besides other issues).

IPv6 preference

Commands like wget now prefer IPv6 for domains with both AAAA and A records, allowing to use such domains for the autoupdater URLs and as NTP servers in site.conf.

Site changes

• site.conf
  • The probability fields for the autoupdater branches can be dropped as they aren’t used anymore
  • The type of the enabled options of the gluon-simple-tc configuration has been changed to boolean, so true and false must be used instead of 1 and 0 now
• site.mk
  • Obsolete packages:
    • gluon-firewall
  • Recommended new packages:
    • gluon-announced
    • gluon-luci-portconfig
  • GLUON_PRIORITY must be set in site.mk or on the make manifest commandline. Use GLUON_PRIORITY ?= 0 in site.mk to allow overriding from the commandline.

Internals

Some internal changes not mentioned before which are interesting for developers:

• Many more shell scripts have been converted to Lua

• gluon-mesh-vpn-fastd now uses the new package gluon-wan-dnsmasq, which provides a secondary DNS server on port 54 that is only reachable from localhost and uses the DNS servers on the WAN interface for everything. This allowed us to remove some ugly hacks which were making the DNS servers used depend on the domain being resolved.

  For IPv6, the default route is now controlled via packet marks, so the secondary DNS server and fastd set the packet mark so they use the default route provided on the WAN interface instead of the mesh.

License

See LICENCE

Indices and tables

• Search Page