# Gluon builds OpenWrt images for community mesh networks

> Gluon is a firmware framework that produces preconfigured OpenWrt images for public mesh networks, with batman-adv and OLSRv2 on the mesh side, 802.11s, fastd, WireGuard and VXLAN for node-to-node links, an ECDSA signed autoupdater and a per-community site configuration.

**freifunk-gluon/gluon** — a modular framework for creating OpenWrt-based firmwares for wireless mesh nodes

- Repository: https://github.com/freifunk-gluon/gluon
- Website: https://gluon.readthedocs.io
- Stars: 618 · Forks: 328
- Language: Lua
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/freifunk-gluon-gluon

## What Gluon is for

Gluon is a firmware framework to build preconfigured OpenWrt images for public mesh networks, and it is written mostly in Lua, with a C component in the source tree.

The problem it addresses is specific. A public mesh network is a WLAN and sometimes a wired network that anyone nearby can join, which means it cannot rely on a shared password, and it cannot ask every visitor to install a client. Gluon's answer is that common network capable devices, such as smartphones, laptops or desktop PCs, connect to the mesh network and communicate over it without the need of passwords for access and without the need of installing special software.

That is the design constraint that everything else follows from. The node runs OpenWrt, the node's firmware is a Gluon image, and the user's own device behaves like any other client on a wireless network.

Beyond the local mesh, the README notes that internet access and merging mesh clouds can be accomplished over a WAN through VPN connected gateways. That is the mechanism by which separate local meshes, in different buildings or different towns, become one network.

The audience is therefore a community network, a mesh association, a municipal wireless project or a group of people running a neighbourhood network, rather than an individual with a house. The project is maintained under the freifunk-gluon organisation and its documentation lives at gluon.readthedocs.io, with a huge amount of documentation by the project's own description.

## The protocol matrix, and how complete each one is

Gluon lists its supported protocols, and it is unusually honest about the state of each one, which is the most useful thing in the README for a prospective operator.

For the mesh itself there are two. batman-adv is supported with BATMAN IV fully and BATMAN V partially. OLSRv2 is supported partially. The distinction between fully and partially is the kind of detail that matters when a community network has to run for years, because a partially supported protocol is where the support questions come from.

For node-to-node connections there are three layers. On WLAN it is 802.11s with forwarding disabled. Over a WAN it is VPNs via fastd and WireGuard. On a LAN it is via VXLAN.

The other features in the list describe what a node does once it is up. There is a decentral mesh network, an easy configuration mode for less techy users, community-specific technical settings and customizations through a common site.conf and site.mk, an ecdsa signature-based autoupdater, a node status web page, and publication of node information and statistics through respondd.

The node status page and the respondd publication are worth noting for a different reason. They are how a community network operator finds out what is happening on the network, and they are the difference between a mesh that is running and a mesh that a user complains about. Gluon treats observability as part of the product rather than an add-on.

## The Makefile is the interface, and site.mk is mandatory

Gluon is driven by a Makefile, and the first thing it does is refuse to run without a site configuration. The directory variable defaults to site, and the check is explicit:

```make
ifeq ($(realpath $(GLUON_SITEDIR)/site.mk),)
$(error No site configuration was found. Please check out a site configuration to $(GLUON_SITEDIR))
endif
```

The site configuration is then included, and the release identifier is required as well, either from site.mk or from the command line.

The Makefile also documents the project's own history in its deprecation warnings, which is more useful than a changelog for understanding the current configuration surface. GLUON_BRANCH has been deprecated in favour of GLUON_AUTOUPDATER_BRANCH and GLUON_AUTOUPDATER_ENABLED, which are set for you when the old variable is used. GLUON_FEATURES and GLUON_SITE_PACKAGES are declared obsolete outright, with the error message telling you to use the image-customization.lua file instead, and the same applies to the standard and tiny variants of both.

So the current configuration model is a site.mk and site.conf for community settings, plus a Lua file for image customisation, and the older feature and package list variables have been removed from the build rather than merely discouraged. The output layout is also fixed by the Makefile, with separate directories for images, packages, debug artefacts and metadata, and for the patches and targets trees.

A build that used to be driven by a list of features is now driven by a configuration file and a Lua script, which is a meaningful change in the shape of the project.

## The autoupdater, and the rule about using releases

The autoupdater is one of the headline features, described as ecdsa signature-based, and the security model is worth understanding.

A node checks for updates, and an update is only accepted if it carries a valid ECDSA signature. That means an operator cannot silently push arbitrary firmware to a network of devices, and it means the signing key is part of the trust model of the whole community network.

The README then gives a warning that is unusually direct for a project README. Please refrain from using the main branch for anything else but development purposes. Use the most recent release instead, and it gives the commands: list all releases with git tag, and switch to one with git checkout v2025.1.3 && make update.

The reason is stated too. If you are using the autoupdater, do not autoupdate nodes with anything but releases, and if you upgrade using random main commits the nodes might break eventually. A development commit is a work in progress, and an autoupdater that distributes it to every node in a community network is a mechanism for breaking that network.

That gives a clear operational rule. The main branch is where development happens and where a new site configuration is tested, and the release tags are what a deployed network should run.

## Community configuration and the people who run it

A community network is a local thing, and Gluon's configuration model reflects that. Community-specific technical settings and customisations live in a common site.conf and site.mk, so two adjacent towns can run the same framework with different parameters and still behave as one mesh when they meet over a WAN.

The easy configuration mode for less techy users is the other half of that idea. A node owner who does not know what a subnet or a routing protocol is still has to do something, and the project treats that as a first-class requirement rather than an afterthought.

The people who run these networks are also part of the project. The developers frequent an IRC chatroom at #gluon on hackint, there is a webchat for access from a browser, and the same channel is bridged to Matrix as #gluon:hackint.org. There is a mailing list, and the README gives the subscribe and unsubscribe addresses:

```text
    gluon+subscribe@luebeck.freifunk.net
    gluon+unsubscribe@luebeck.freifunk.net
```

For contributions there is a CONTRIBUTING.md, a roadmap in the project wiki, and a policy of discussing a new feature on IRC or the mailing list before opening an issue, plus a request to check whether an existing issue, open or closed, already matches.

The repository layout matches a firmware build: a modules directory, a packages directory, a patches directory for OpenWrt patches, scripts, targets, contrib for contributed pieces, tests and docs. There is a .luacheckrc for the Lua code and an .editorconfig-checker.json, so the tree is linted on both languages.

## Releases, licence and the shape of the project

The releases are versioned by year and sequence, and the recent ones are v2025.1.3 on 2026-08-18, v2025.1.2 on 2026-08-11 and v2025.1.1 on 2026-05-04. The last push to the repository was on 2026-10-21, and the repository is not archived, so the framework itself is being worked on even between those release points.

The licence badge in the README says BSD 2-Clause, while the licence recorded for the repository itself is a custom licence that GitHub cannot classify, with a pointer to the LICENSE file. A two-clause BSD is permissive, with attribution and no warranty, and a file-based licence in the repository is the thing to read rather than the metadata field.

The build and test story is visible in the CI badge, which points at a Build Gluon workflow on GitHub, and the Makefile's own structure shows that a build is a multi-stage process with intermediate directories for temporary work, images, packages, debug artefacts and metadata.

For a community network, the operational commitment is the thing to weigh. Gluon gives you a mesh that people can join without a password and nodes that update themselves with signed firmware, and in exchange it asks for a firmware build, a site configuration and someone who reads the IRC channel. That is a reasonable trade for a neighbourhood network and a poor one for a small office.

## Conclusion

Gluon fits a community network operator, a mesh association or a municipality running a decentralised WLAN, who want nodes that join the network without a password and without the user installing anything, and who are prepared to maintain a site configuration and a firmware build. It is the wrong tool for a home router, for an indoor mesh where a consumer access point is enough, and it is the wrong tool if you need a supported commercial firmware, because a community network is a different problem with a different cost structure. Before adopting it, read the Getting Started guide, decide whether you will build your own image or take a release, and note the rule in the README that the main branch is for development only and that autoupdating nodes should only ever receive releases.

## FAQ

### What is Gluon and what is it used for?

Gluon is a firmware framework to build preconfigured OpenWrt images for public mesh networks. It provides a decentralised mesh network where common devices such as phones and laptops connect without a password and without installing special software, and where internet access and merging mesh clouds happen over a WAN through VPN connected gateways.

### Which mesh and VPN protocols does Gluon support?

For the mesh, batman-adv with BATMAN IV fully and BATMAN V partially, and OLSRv2 partially. For node-to-node connections, 802.11s on WLAN with forwarding disabled, VPNs via fastd and WireGuard over a WAN, and VXLAN on a LAN.

### Why does the Gluon build fail with no site configuration found?

The Makefile requires a site configuration, and GLUON_SITEDIR defaults to site. The error message tells you to check out a site configuration to that directory, and the configuration is then included from site.mk, with GLUON_RELEASE also needing to be set in site.mk or on the command line.

### Can I run the Gluon autoupdater from the main branch?

No. The README asks you to use the most recent release rather than the main branch, to switch with git checkout v2025.1.3 && make update, and warns that if you upgrade using random main commits the nodes might break eventually. Autoupdating nodes should only ever receive releases.

### What licence is Gluon released under?

The README badge states BSD 2-Clause. The repository's own licence classification is a custom licence that GitHub cannot classify, so the LICENSE file in the repository is the document to read.

## Sources

- [freifunk-gluon/gluon on GitHub](https://github.com/freifunk-gluon/gluon)
- [Issues](https://github.com/freifunk-gluon/gluon/issues)
- [Project website](https://gluon.readthedocs.io)
- [README](https://github.com/freifunk-gluon/gluon/blob/main/README.md)
- [Releases](https://github.com/freifunk-gluon/gluon/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/freifunk-gluon-gluon