Lab 02 — ImageBuilder Firmware

Duration: 75 minutes

You met the Mango on stock GL.iNet firmware in Lab 01. This lab replaces that firmware with a custom build: a sysupgrade .bin produced from OpenWrt’s ImageBuilder and pinned to 23.05.3 / ramips / mt76x8.

The engineering exercise is package selection under a hard 16 MB NOR flash ceiling. Tailscale, cloudflared, and python3 do not fit in NOR alongside a kernel and bootloader. You confirm that by reading the package list, build the image, and verify the resulting .bin against the size constraint. Lab 03 will move those heavy packages onto a USB ExtRoot.

Reproducibility. The build sets SOURCE_DATE_EPOCH=1714694400 to strip squashfs timestamps. Two students building from the same commit on the same day produce identical SHA256 sums. “Is your firmware identical to mine?” becomes a one-line check.

Where each step runs

This lab runs entirely from the operator console (Codespace, local Dev Container, or Minimal local; any path with Docker available). Flashing the produced .bin to the Mango is Lab 03, not here. Lab 02 ends with a verified artifact on disk.

Learning objectives

• Understand the ImageBuilder model: pre-compiled packages assembled into a firmware image without a full source build.
• Read the PACKAGES list in build-drop-mango.sh as the engineering document. Each addition or removal has a NOR-flash cost.
• Use SOURCE_DATE_EPOCH to produce bit-identical artifacts across hosts.
• Read build-manifest.json as a reproducibility audit trail.
• Verify a squashfs size constraint programmatically. Know what to cut when it fails.

Pre-state

Before starting this lab confirm:

# Lab 01 is complete: SSH to the Mango works.
# (Skip this check if you are running Lab 02 ahead of bench access; the
# build itself does not need the Mango to be reachable.)
ssh -o ConnectTimeout=5 root@192.168.8.1 'echo ok'   # stock GL.iNet; use 192.168.1.1 for pure-OpenWrt

# Docker is reachable from your operator console (this is the inner DinD
# daemon in Codespace / Local Dev Container, or your host docker for
# Minimal local).
docker info | grep 'Server Version'

# Pull the OpenWrt 23.05.3 ImageBuilder image (~800 MB; first run only).
docker pull openwrt/imagebuilder:ramips-mt76x8-23.05.3

# The lab's build inputs are checked into the repo. Confirm they exist.
ls courses/engagement-platform-labs/labs/Makefile
ls courses/engagement-platform-labs/labs/lab02-imagebuilder-firmware/build-drop-mango.sh
ls courses/engagement-platform-labs/labs/shared/files-mango/etc/banner
ls courses/engagement-platform-labs/labs/shared/build-manifest.schema.json

If any of these are missing, run git status. Restore with git checkout HEAD -- <path>.

Walkthrough

# All commands run from the course root:
# cd courses/engagement-platform-labs

# The build script. The PACKAGES variable is the engineering document.
cat labs/lab02-imagebuilder-firmware/build-drop-mango.sh

# The shared files overlay baked into the squashfs:
cat labs/shared/files-mango/etc/banner
cat labs/shared/files-mango/etc/uci-defaults/99-enroll.sh.template
# Note: template placeholders ({{WORKER_URL}} etc.) are NOT substituted
# here. Lab 12 substitutes real secrets and rebuilds.

# The Makefile glue. `drop-mango` is the target you run in Step 2.
cat labs/Makefile

cd courses/engagement-platform-labs/labs

# The canonical entry point. Idempotent.
make drop-mango

docker compose run --rm imagebuilder \
    /labs/lab02-imagebuilder-firmware/build-drop-mango.sh

>>> drop-mango build
    PROFILE=glinet_gl-mt300n-v2
    FILES_DIR=/labs/shared/files-mango
    SOURCE_DATE_EPOCH=1714694400
    OUTPUT_DIR=/labs/output
...
>>> built: bin/targets/ramips/mt76x8/openwrt-23.05.3-ramips-mt76x8-glinet_gl-mt300n-v2-squashfs-sysupgrade.bin
    size: <N> bytes
    sha256: <...>
    squashfs rootfs: <M> bytes
>>> artifacts in /labs/output/

ERROR: squashfs rootfs N bytes exceeds ceiling 13631488
       trim the PACKAGES list or move heavy packages to ExtRoot (Lab 03)

# Confirm the artifact exists.
ls -lh labs/output/
# Expected:
#   build-manifest.json
#   openwrt-23.05.3-ramips-mt76x8-glinet_gl-mt300n-v2-squashfs-sysupgrade.bin
#   ... and possibly the matching factory.bin and .manifest from ImageBuilder

# Locate the sysupgrade .bin and report its size in MB.
BIN=$(ls labs/output/*glinet_gl-mt300n-v2*sysupgrade.bin 2>/dev/null | head -1)
echo "$BIN"
wc -c < "$BIN" | awk '{printf "%.2f MB\n", $1/1024/1024}'
# Should be well under 16 MB. A typical clean build lands around 5–7 MB.

# Read the build manifest. Required fields: role, openwrt_version, created_at.
# Optional but useful: openwrt_target, openwrt_profile, package_list_sha256,
# image_sha256, source_date_epoch.
cat labs/output/build-manifest.json

sha256sum labs/output/*sysupgrade.bin

# 1) Read the package manifest ImageBuilder produced. Sorted, line-delimited:
ls labs/output/*glinet_gl-mt300n-v2*.manifest
cat labs/output/*glinet_gl-mt300n-v2*.manifest | sort

# 2) Count it.
wc -l labs/output/*glinet_gl-mt300n-v2*.manifest
# A clean drop-mango build lands around 90 packages (verified 2026-05-04
# at 93 lines). The PACKAGES list is small (~30 named entries), but opkg's
# dependency resolution pulls in libc, libgcc, mbedtls, kernel modules,
# wireless-regdb, and similar transitive deps, so the resolved manifest is
# roughly 3x the named-package count.

# 3) From inside the OpenWrt rootfs sibling (Lab 01 Step 4b), get its
#    package count for comparison:
docker exec ep-devcontainer opkg list-installed | wc -l
# ~127 packages on the upstream x86_64 rootfs.

Post-state

When this lab is complete you should be able to answer yes to all of the following:

• labs/output/ contains a *-glinet_gl-mt300n-v2-squashfs-sysupgrade.bin file produced by the latest build.
• wc -c on that file reports a size below the 16 MB NOR ceiling (16,777,216 bytes).
• labs/output/build-manifest.json exists with role: "drop-mango", openwrt_version: "23.05.3", and a recent created_at timestamp.
• validate.sh exits 0.
• You can name three packages that are present in the Mango image and explain what each enables (canonical answer: block-mount for ExtRoot, dropbear for SSH, ca-bundle for outbound TLS).
• You can name three packages that are deliberately absent from the Mango image and explain why (canonical answer: luci because no web UI is needed in the drop role; dnsmasq because the Mango is not a router; tailscale because it doesn’t fit in NOR and lives on ExtRoot in Lab 03).

Validation

Three validation paths. Pick whichever matches your setup. All three call the same validate.sh and post the result to the same backend; only the delivery channel differs.

Path 1: epl CLI (recommended from the operator console).

epl validate lab02-imagebuilder-firmware

The validator reads labs/output/build-manifest.json and the *-sysupgrade.bin file; no Mango access required. Re-run as many times as you like; only the most recent result is recorded.

Path 2: direct script.

bash courses/engagement-platform-labs/labs/lab02-imagebuilder-firmware/validate.sh

Or via the Makefile:

cd courses/engagement-platform-labs/labs
make validate-lab02-imagebuilder-firmware

Path 3: paste output into the widget.

Run validate.sh anywhere, copy the full output, paste it into the widget below.

What the script checks:

1. labs/output/build-manifest.json exists.
2. The manifest contains the required fields (role, openwrt_version, created_at).
3. The manifest validates against labs/shared/build-manifest.schema.json when python3 is available. (Skipped with a [SKIP] note otherwise.)
4. A *glinet_gl-mt300n-v2*sysupgrade.bin file exists in labs/output/.
5. That .bin is smaller than 16 MB (the NOR chip size).

Take-home extension

See take-home/lab02-mt3000-build/ for the parallel exercise on the cancelled MT3000 hardware (mediatek/filogic, glinet_gl-mt3000). The MT3000 carries eMMC, so its “drop firmware” has no 16 MB constraint. The contrast becomes a different question: what does the MT3000 carry that the Mango cannot, and what mission profile would use both?

The take-home directory is a stub during the May 2026 cohort and will be expanded post-workshop.

Primitives and drop-in substitutes

OpenWrt’s ImageBuilder is one implementation of a wider primitive: declarative firmware assembly. You name a target, a profile, a package list, and a file overlay; the toolchain produces a flashable artifact with a known size and a reproducible hash. The package selection is the engineering exercise; the toolchain that performs the assembly is interchangeable.

The table below maps that primitive to its closest equivalents across the embedded and systems-Linux landscape. Each tool accepts a declarative description of what should be in an image and outputs a bootable artifact. The variables are: what the “declaration” looks like, how the output is constrained, and who the upstream maintainer is.

package feed / sources
        │
        ▼
assembly tool (ImageBuilder / Yocto / Buildroot / mkosi / debootstrap)
        │
        ├── size constraint applied (NOR ceiling, eMMC budget, container layer limit)
        │
        ▼
image artifact  ──►  SHA256 hash  ──►  reproducibility check

Take-home prompt. Pick a target on your shelf (RPi 4, an old PC with a 32 GB SSD, a dev board) and rebuild the equivalent of the drop-mango package list using one of the tools above. Compare the resulting artifact size, the hash-reproducibility properties, and the wall-clock time to first usable byte.

Further reading

ImageBuilder and reproducibility:

• OpenWrt ImageBuilder. Official documentation for the build system this lab wraps.
• Reproducible builds in OpenWrt. The SOURCE_DATE_EPOCH discipline and what it enforces.
• opkg package management. How packages are resolved from feeds; useful when the manifest hash differs between students.

Hardware-specific:

• GL-MT300N-V2 (Mango) device page. Flash layout, supported releases, partition table.
• ramips/mt76x8 target. The MediaTek MT76x8 SoC family. The Mango is one of dozens of devices on this target.

Workshop-internal:

• Lab 03: Overlay Deployment. Flashes the .bin you built here onto the Mango, mounts a USB drive as ExtRoot, and installs Tailscale on the overlay.
• Lab 12: Drop Device. Re-runs this build with enrollment secrets baked into the firmware so the device self-registers on first boot.

View this page’s source: labs/lab02-imagebuilder-firmware/README.mdx

Troubleshooting

ls courses/engagement-platform-labs/labs/docker-compose.yml
docker compose -f courses/engagement-platform-labs/labs/docker-compose.yml config

make drop-mango

docker compose run --rm imagebuilder \
    find /home/buildbot/openwrt-imagebuilder-23.05.3-ramips-mt76x8.Linux-x86_64/bin/targets \
         -name '*.ipk' | xargs ls -lS 2>/dev/null | head -20

bash courses/engagement-platform-labs/labs/lab02-imagebuilder-firmware/validate.sh