Armbian for GL-MT2500 / Brume 2 (USB boot with OpenWrt fallback)

shi05275 · September 2, 2026, 1:54am

Hi everyone,

I have been working on Armbian support for the GL.iNet GL-MT2500 (Brume 2), and the source code is now available here:

The goal is to let the GL-MT2500 run a standard Debian/Armbian userspace while keeping the original OpenWrt installation available as a fallback.

Current status

The complete build and installation procedure below has been tested on GL-MT2500 v1 (MaxLinear 2.5G PHY).

Debian Trixie CLI image
Linux 6.16.12-edge-filogic
U-Boot 2025.04
Armbian root filesystem on a USB drive
No case opening or serial connection required for the normal installation
Automatic fallback to the original OpenWrt system on eMMC if USB boot fails
The original eMMC OpenWrt system, BL2, environment and RF calibration data remain in place
USB storage drivers are included in initramfs

The source tree also contains a gl-mt2500-v2 board configuration and Airoha EN8811H firmware handling. However, the installation procedure and reference image documented here are for v1. Do not use a v1 image on v2 hardware.

This is an unofficial community port. It is not an official GL.iNet or Armbian release.

What you need

A GL-MT2500 v1
A stable, independent 5V/3A USB-C power supply
An 8 GB or larger USB drive that can be completely erased
A Linux build machine with at least 25 GB of free disk space
An Ethernet cable and SSH access to the original OpenWrt system
Optional for recovery and debugging: a 3.3V USB-to-TTL adapter configured for 115200 8N1

Power warning: do not power the router from a computer USB port. Insufficient power can cause cold resets during BL2 or Linux startup. If a TTL adapter is needed for recovery, connect only GND, TX and RX, with TX/RX crossed. Do not connect the TTL VCC pin.

Build the image

On Debian/Ubuntu, install the required tools:

sudo apt update
sudo apt install -y \
ca-certificates curl git xz-utils zstd \
util-linux parted e2fsprogs dosfstools \
openssh-client

Clone the correct branch:

git clone https://github.com/JiaY-shi/armbian.git
cd armbian

Build a Debian Trixie CLI image for v1:

./compile.sh build \
BOARD=gl-mt2500 \
BRANCH=edge \
RELEASE=trixie \
BUILD_DESKTOP=no \
BUILD_MINIMAL=no \
KERNEL_CONFIGURE=no \
KERNEL_GIT=shallow \
KERNELSOURCE=https://mirrors.tuna.tsinghua.edu.cn/git/linux-stable.git \
KERNELBRANCH=branch:linux-6.16.y \
DOWNLOAD_MIRROR=china \
PESTER_TERMINAL=no

The first build requires Internet access. The generated image will be under output/images/, and the U-Boot package will be under output/debs/. Always verify the checksum generated by your own build; image UUIDs and hashes change between builds.

Write Armbian to the USB drive

First identify the USB drive carefully:

lsblk -d -o NAME,SIZE,MODEL,SERIAL,TRAN,TYPE
lsblk -o NAME,SIZE,FSTYPE,LABEL,PARTLABEL,MOUNTPOINTS

Replace /dev/sdX with the whole USB device, not a partition. This destroys all data on that USB drive:

IMG=$(find output/images -maxdepth 1 -type f -name '*Gl-mt2500*.img' | head -n 1)
sudo umount /dev/sdX?* 2>/dev/null || true
sudo dd if="$IMG" of=/dev/sdX bs=4M status=progress conv=fsync
sync

The image uses five GPT partitions. The fifth partition contains the Armbian root filesystem. On first boot, Armbian expands it to use the remaining USB capacity.

Back up the device before changing U-Boot

Boot the original OpenWrt system first. Assuming its address is 192.168.8.1:

mkdir -p backups/gl-mt2500
ssh root@192.168.8.1 'dd if=/dev/mmcblk0boot0 bs=512 count=2048 2>/dev/null' > backups/gl-mt2500/mmcblk0boot0-bl2.bin
ssh root@192.168.8.1 'dd if=/dev/mmcblk0p2 bs=512 2>/dev/null' > backups/gl-mt2500/u-boot-env.bin
ssh root@192.168.8.1 'dd if=/dev/mmcblk0p3 bs=512 2>/dev/null' > backups/gl-mt2500/rf.bin
ssh root@192.168.8.1 'dd if=/dev/mmcblk0p4 bs=512 2>/dev/null' > backups/gl-mt2500/fip.bin
sha256sum backups/gl-mt2500/*

Keep these files on another physical disk. The RF and environment partitions contain device-specific data such as MAC addresses and serial information. Never restore them from another unit.

Install the USB-aware U-Boot FIP without opening the case

Extract the FIP from the package produced by the build:

UBOOT_DEB=$(find output/debs -maxdepth 1 -type f \
-name 'linux-u-boot-gl-mt2500-edge*.deb' \
-printf '%T@ %p\n' | sort -nr | head -n 1 | cut -d' ' -f2-)
mkdir -p output/deploy/uboot
dpkg-deb -x "$UBOOT_DEB" output/deploy/uboot
FIP=output/deploy/uboot/usr/lib/linux-u-boot-edge-gl-mt2500/u-boot_sdmmc.fip
stat -c '%n %s bytes' "$FIP"
sha256sum "$FIP"

The FIP must be clearly smaller than the 2 MiB eMMC fip partition. Copy it to the router while the original OpenWrt system is running:

scp "$FIP" root@192.168.8.1:/tmp/u-boot-mt2500.fip

Verify the target partition size and the uploaded file on OpenWrt:

ssh root@192.168.8.1
cat /sys/class/block/mmcblk0p4/size
wc -c /tmp/u-boot-mt2500.fip
sha256sum /tmp/u-boot-mt2500.fip

For the tested v1 partition layout, /sys/class/block/mmcblk0p4/size must report 4096 sectors (2 MiB). The uploaded file size and SHA256 must match the local file. Stop if the partition is missing, has a different size, or the hashes do not match.

With stable power connected, write only the FIP partition, flush it, and hash the exact number of bytes back from eMMC:

FIP=/tmp/u-boot-mt2500.fip
FIP_BYTES=$(wc -c < "$FIP")
dd if="$FIP" of=/dev/mmcblk0p4 bs=512
sync
dd if=/dev/mmcblk0p4 bs=1 count="$FIP_BYTES" 2>/dev/null | sha256sum
sha256sum "$FIP"

The two SHA256 values must match. After successful verification, shut the router down, insert the prepared USB drive and power it on again. No case opening or serial connection is required for the normal installation path.

Do not write BL2. Do not erase u-boot-env or rf. Do not run env erase, saveenv, or env default -a; saveenv.

Boot behavior

With the prepared USB drive connected, U-Boot tries:

usb start; sysboot usb 0:5 any ${scriptaddr} /boot/extlinux/extlinux.conf; run boot_openwrt

It first loads Armbian from USB partition 5. If the USB drive is absent, damaged, or its extlinux configuration cannot be loaded, it automatically boots the original OpenWrt installation from eMMC.

If a serial adapter is connected, OpenWrt can also be started manually by stopping U-Boot with the space bar and running:

run boot_openwrt

The first Armbian boot expands the root filesystem and asks you to set a root password and create a normal user.

Recovery and troubleshooting

Repeated cold resets with USB attached usually indicate inadequate power. Try a proper 5V/3A supply and another USB-C cable first.
With a TTL serial console connected, if U-Boot cannot see the USB drive, try usb stop, usb start, usb tree, and part list usb 0.
If the device stops at the GL-MT2500> prompt, run run bootcmd from the serial console.
If USB boot fails, wait for automatic OpenWrt fallback or run run boot_openwrt.
If OpenWrt still boots, its original FIP can be restored through SSH using the backup from that same device and the same size/hash checks. Serial/TFTP recovery is documented in the repository README.

The repository README contains the full procedure, expected boot logs, integrity checks, WSL2 serial instructions and USB update workflow:

github.com/JiaY-shi/armbian

README.md

gl-mt2500

<h3 align="center">
  <a href=#><img src="https://raw.githubusercontent.com/armbian/.github/master/profile/logosmall.png" alt="Armbian logo"></a>
  <br><br>
</h3>

# GL-MT2500 v1 Armbian

本分支为 GL.iNet GL-MT2500 / Brume 2 v1 提供 Armbian 支持。当前启动策略是：

1. U-Boot 优先从 USB 第 5 分区的 `/boot/extlinux/extlinux.conf` 启动 Armbian。
2. U 盘不存在、损坏或 extlinux 加载失败时，自动启动 eMMC 中原有的 OpenWrt。
3. Armbian 只写入 U 盘；eMMC 的 OpenWrt、BL2、环境和射频数据保持不变。
4. 正常安装可通过原厂 OpenWrt 的 SSH 只更新 FIP，无需拆机或连接串口。

当前 v1 参考产物：

```text
image: output/images/Armbian-unofficial_26.11.0-trunk_Gl-mt2500_trixie_edge_6.16.12.img
size: 2189426688 bytes
SHA256: 76f21287ef086e750ef1079ab830afef86a3ee10785690bc589ecbf860023f4f

此文件已被截断。显示原始文件

Feedback, boot logs and test reports are welcome. Please include the hardware revision (v1 or v2), power supply, USB drive model and relevant serial output when reporting a problem.

大家好，

我最近为 GL.iNet GL-MT2500（Brume 2）做了 Armbian 适配，源码已经公开：

这个项目的目标是在 GL-MT2500 上运行标准的 Debian/Armbian 用户空间，同时保留 eMMC 中的原厂 OpenWrt 作为回退系统。

当前状态

下面的完整编译与安装流程已经在 GL-MT2500 v1（MaxLinear 2.5G PHY）上完成实机验证：

Debian Trixie CLI 镜像
Linux 6.16.12-edge-filogic
U-Boot 2025.04
Armbian 根文件系统运行在 U 盘上
正常安装无需拆机，也无需连接串口
USB 启动失败时自动回退到 eMMC 中的原厂 OpenWrt
保留 eMMC 中原有的 OpenWrt、BL2、环境变量和射频校准数据
initramfs 已包含 USB 存储所需驱动

源码中也包含 gl-mt2500-v2 板级配置和 Airoha EN8811H 固件处理，但本文的安装流程和参考镜像针对 v1。请勿在 v2 设备上使用 v1 镜像。

这是非官方的社区适配，不是 GL.iNet 或 Armbian 官方发布。

所需设备

GL-MT2500 v1
独立、稳定的 5V/3A USB-C 电源
一个允许完全覆盖的 8 GB 或更大 U 盘
至少有 25 GB 可用空间的 Linux 编译机
一根网线，并且能够 SSH 登录设备原有的 OpenWrt
排障和恢复时可选：3.3V USB TTL 串口，参数为 115200 8N1
**供电注意事项：**不要使用电脑 USB 口给路由器供电，供电不足可能导致设备在 BL2 或 Linux 启动阶段冷复位。需要用 TTL 恢复时，只连接 GND、TX 和 RX，TX/RX 交叉连接，不要连接 TTL 的 VCC。

编译镜像

在 Debian/Ubuntu 上安装所需工具：

sudo apt update
sudo apt install -y \
ca-certificates curl git xz-utils zstd \
util-linux parted e2fsprogs dosfstools \
openssh-client

克隆正确的分支：

git clone https://github.com/JiaY-shi/armbian.git
cd armbian

编译 v1 的 Debian Trixie CLI 镜像：

./compile.sh build \
BOARD=gl-mt2500 \
BRANCH=edge \
RELEASE=trixie \
BUILD_DESKTOP=no \
BUILD_MINIMAL=no \
KERNEL_CONFIGURE=no \
KERNEL_GIT=shallow \
KERNELSOURCE=https://mirrors.tuna.tsinghua.edu.cn/git/linux-stable.git \
KERNELBRANCH=branch:linux-6.16.y \
DOWNLOAD_MIRROR=china \
PESTER_TERMINAL=no

首次编译必须联网。生成的镜像位于 output/images/，U-Boot 软件包位于 output/debs/。每次编译得到的 UUID 和哈希可能不同，请始终校验本次编译生成的校验文件。

将 Armbian 写入 U 盘

先仔细确认 U 盘的总线、型号、序列号和容量：

lsblk -d -o NAME,SIZE,MODEL,SERIAL,TRAN,TYPE
lsblk -o NAME,SIZE,FSTYPE,LABEL,PARTLABEL,MOUNTPOINTS

将 /dev/sdX 替换为 U 盘对应的整块设备，而不是某个分区。下面的操作会清空该 U 盘上的全部数据：

IMG=$(find output/images -maxdepth 1 -type f -name '*Gl-mt2500*.img' | head -n 1)
sudo umount /dev/sdX?* 2>/dev/null || true
sudo dd if="$IMG" of=/dev/sdX bs=4M status=progress conv=fsync
sync

镜像使用 5 个 GPT 分区，第 5 分区是 Armbian 根文件系统。首次启动时，Armbian 会自动扩展它以使用 U 盘剩余空间。

修改 U-Boot 前备份设备数据

先启动设备原有的 OpenWrt。下面假设 OpenWrt 地址为 192.168.8.1：

mkdir -p backups/gl-mt2500
ssh root@192.168.8.1 'dd if=/dev/mmcblk0boot0 bs=512 count=2048 2>/dev/null' > backups/gl-mt2500/mmcblk0boot0-bl2.bin
ssh root@192.168.8.1 'dd if=/dev/mmcblk0p2 bs=512 2>/dev/null' > backups/gl-mt2500/u-boot-env.bin
ssh root@192.168.8.1 'dd if=/dev/mmcblk0p3 bs=512 2>/dev/null' > backups/gl-mt2500/rf.bin
ssh root@192.168.8.1 'dd if=/dev/mmcblk0p4 bs=512 2>/dev/null' > backups/gl-mt2500/fip.bin
sha256sum backups/gl-mt2500/*

请确认文件非空，并将备份复制到另一块物理磁盘。rf 和 u-boot-env 包含 MAC 地址、序列号等本机唯一数据，绝不能使用其他设备的备份替代。

不拆机安装支持 USB 启动的 U-Boot FIP

从编译生成的软件包中提取 FIP：

UBOOT_DEB=$(find output/debs -maxdepth 1 -type f \
-name 'linux-u-boot-gl-mt2500-edge*.deb' \
-printf '%T@ %p\n' | sort -nr | head -n 1 | cut -d' ' -f2-)
mkdir -p output/deploy/uboot
dpkg-deb -x "$UBOOT_DEB" output/deploy/uboot
FIP=output/deploy/uboot/usr/lib/linux-u-boot-edge-gl-mt2500/u-boot_sdmmc.fip
stat -c '%n %s bytes' "$FIP"
sha256sum "$FIP"

FIP 必须明显小于 eMMC 上 2 MiB 的 fip 分区。在原厂 OpenWrt 正常运行时，将它复制到路由器：

scp "$FIP" root@192.168.8.1:/tmp/u-boot-mt2500.fip

登录 OpenWrt，核对目标分区大小和上传文件：

ssh root@192.168.8.1
cat /sys/class/block/mmcblk0p4/size
wc -c /tmp/u-boot-mt2500.fip
sha256sum /tmp/u-boot-mt2500.fip

在已测试的 v1 分区布局上，/sys/class/block/mmcblk0p4/size 必须显示 4096 个扇区，即 2 MiB。上传文件的大小和 SHA256 必须与本地文件一致。如果分区不存在、大小不同或哈希不一致，必须停止。

保持稳定供电，只写入 FIP 分区，完成后强制落盘，并从 eMMC 回读相同字节数进行校验：

FIP=/tmp/u-boot-mt2500.fip
FIP_BYTES=$(wc -c < "$FIP")
dd if="$FIP" of=/dev/mmcblk0p4 bs=512
sync
dd if=/dev/mmcblk0p4 bs=1 count="$FIP_BYTES" 2>/dev/null | sha256sum
sha256sum "$FIP"

两次 SHA256 必须完全一致。校验成功后关闭路由器，插入已经写好 Armbian 镜像的 U 盘，再重新上电即可。正常安装流程不需要拆机，也不需要连接串口。

不要写 BL2，不要擦除 u-boot-env 或 rf，不要执行 env erase、saveenv 或 env default -a; saveenv。

启动逻辑

插入准备好的 U 盘后，U-Boot 会执行：

usb start; sysboot usb 0:5 any ${scriptaddr} /boot/extlinux/extlinux.conf; run boot_openwrt

设备会优先从 U 盘第 5 分区启动 Armbian。如果 U 盘不存在、损坏或 extlinux 配置无法加载，则自动启动 eMMC 中原有的 OpenWrt。

如果连接了串口，也可以在 U-Boot 倒计时期间按空格，然后手动启动 OpenWrt：

run boot_openwrt

Armbian 首次启动时会扩展根文件系统，并要求设置 root 密码和创建普通用户。

恢复与排障

插入 U 盘后反复冷复位，通常是供电不足。请先更换合格的 5V/3A 电源和 USB-C 线。
连接 TTL 串口后，如果 U-Boot 无法识别 U 盘，可执行 usb stop、usb start、usb tree 和 part list usb 0。
设备停在 GL-MT2500> 提示符时，可通过串口执行 run bootcmd。
USB 启动失败时，可以等待自动回退，或执行 run boot_openwrt。
如果 OpenWrt 仍可启动，可以通过 SSH 使用该设备自己的 fip.bin 备份恢复，并执行同样的大小和哈希检查；串口/TFTP 恢复方法见仓库 README。

仓库 README 中提供了更完整的操作步骤、预期启动日志、完整性检查、WSL2 串口连接方法和后续 U 盘更新流程：

github.com/JiaY-shi/armbian

README.md

gl-mt2500

<h3 align="center">
  <a href=#><img src="https://raw.githubusercontent.com/armbian/.github/master/profile/logosmall.png" alt="Armbian logo"></a>
  <br><br>
</h3>

# GL-MT2500 v1 Armbian

本分支为 GL.iNet GL-MT2500 / Brume 2 v1 提供 Armbian 支持。当前启动策略是：

1. U-Boot 优先从 USB 第 5 分区的 `/boot/extlinux/extlinux.conf` 启动 Armbian。
2. U 盘不存在、损坏或 extlinux 加载失败时，自动启动 eMMC 中原有的 OpenWrt。
3. Armbian 只写入 U 盘；eMMC 的 OpenWrt、BL2、环境和射频数据保持不变。
4. 正常安装可通过原厂 OpenWrt 的 SSH 只更新 FIP，无需拆机或连接串口。

当前 v1 参考产物：

```text
image: output/images/Armbian-unofficial_26.11.0-trunk_Gl-mt2500_trixie_edge_6.16.12.img
size: 2189426688 bytes
SHA256: 76f21287ef086e750ef1079ab830afef86a3ee10785690bc589ecbf860023f4f

此文件已被截断。显示原始文件

欢迎反馈测试结果和启动日志。报告问题时，请附上硬件版本（v1 或 v2）、电源规格、U 盘型号以及相关串口输出。

will.qiu · September 2, 2026, 10:06am

Hi,

Thanks for your work on this and for sharing it with the community. The detailed instructions and OpenWrt fallback design will be helpful to users interested in running Armbian on the Brume 2.

shi05275 · September 2, 2026, 11:15am

At the moment, only the U‑Boot on the device needs to be adjusted. The Armbian system resides on a USB drive – simply unplug it and the device will boot into OpenWrt. If you ever need to restore the original U‑Boot, you can reflash it from either OpenWrt or Armbian. By the way, I've submitted a PR to the official Armbian repository, which has been approved and is expected to be merged soon.

shi05275 · September 2, 2026, 11:38am

It did take quite a bit of time. I've had this idea for a long time, but never found the right moment to start. Recently I finally managed to set aside some time, and with the help of large language models, I got it done – though I spent a lot of effort on debugging, especially repeatedly flashing the device. Luckily, the outcome turned out pretty well.

Also, as far as I know, GL.iNet has another model called the GL‑MT5000, which also looks like a good candidate for Armbian. I hope that enthusiasts who have access to the device will give it a try – after all, Armbian is a full‑featured Linux distribution and offers much more room for experimentation.