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. v2017.1.8. 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/.
To build Gluon, several packages need to be installed on the system. On a freshly installed Debian Wheezy system the following packages are required:
- git (to get Gluon and other dependencies)
- python (Python 3 doesn’t work)
- libncurses-dev (actually libncurses5-dev)
- libz-dev (actually zlib1g-dev)
Building the images¶
To build Gluon, first check out the repository. Replace RELEASE with the version you’d like to checkout, e.g. v2017.1.8.
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:
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 tools not available yet).
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
You should reserve about 10GB of disk space 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/LEDE-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.
will clean the entire tree, so the toolchain will be rebuilt as well, which will take a while.
Gluon is mostly compatible with LEDE, so the normal LEDE 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 LEDE images. Therefore, Gluon will not only generate images, but also an opkg repository containing all core packages provided by LEDE, including modules for the kernel of the generated images.
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 LEDE keyring (to allow installing userspace packages) and a Gluon-specific key (which is used to sign the generated package repository).
LEDE 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.
Gluon’s build process can be controlled by various variables. They can
usually be set on the command line or in
While Gluon does support some hardware with ath10k-based 5GHz WLAN, these WLAN adapters don’t work well for meshing at the moment, so building images for these models is disabled by default. In addition, ath10k can’t support IBSS and 11s meshing in the same image due to WLAN firmware restrictions.
Setting GLUON_ATH10K_MESH to
ibsswill enable generation of images for ath10k devices and install the firmware for the corresponding WLAN mode.
- Sets the default branch of the autoupdater. If unset, the autoupdater is disabled
by default. For the
make manifestcommand, GLUON_BRANCH defines the branch to generate a manifest for.
- Space-separated list of languages to include for the config mode/advanced settings. Defaults to
enshould always be included, other supported languages are
- Defines the priority of an automatic update in
make manifest. See Autoupdater for a detailed description of this value.
- Some devices (at the moment the TP-Link Archer C7) contain a region code that restricts
firmware installations. Set GLUON_REGION to
usto make the resulting images installable from the respective stock firmwares.
- 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.
- Target architecture to build.
- Working directory during build. Defaults to
- Path where images will be stored. Defaults to
- Path where the opkg package repository will be stored. Defaults to
- Path where output files will be stored. Defaults to
- Path to the site configuration. Defaults to