Flashing OPNsense onto a Mono Gateway Router

Not sure which port on your unit is the console port, or what the board looks like in general? Mono's own Getting Started guide and hardware description cover the physical layout in detail.

It downloads as a compressed .img.bz2 file. You don't need to decompress it yourself, that is done later automatically.

shasum -a 256 OPNsense-202610081133-arm-aarch64-GATEWAY.img.bz2

sha256sum OPNsense-202610081133-arm-aarch64-GATEWAY.img.bz2

Get-FileHash OPNsense-202610081133-arm-aarch64-GATEWAY.img.bz2 -Algorithm SHA256

screen /dev/cu.usbserial-XXXXXXXX 115200

The exact device name (the XXXXXXXX part) will be different on your machine — if you're not sure what it's called, this command lists every matching device your computer can currently see:

ls /dev/cu.usbserial-*

First, find which COM port the router is using: open Device Manager → expand Ports (COM & LPT) → look for an entry like USB Serial Port (COM5). Note the number, then connect using PowerShell's built-in serial support:

$port = new-Object System.IO.Ports.SerialPort COM5,115200,None,8,one
$port.Open()
while ($true) { Write-Host -NoNewline $port.ReadExisting() }

Now power-cycle the router (unplug and replug it, or use its power switch). Watch the text scroll by, and the moment you see a line like Hit any key to stop autoboot: — press any key. You have only a few seconds, so keep a finger on the keyboard as it boots. This drops you into a special typing prompt that looks like this:

=> 

That little => is called the U-Boot prompt. Think of it as the router's control room — before any operating system has even started, this is where you tell it what to do. Everything below happens either here or one level "deeper," inside something called Recovery Linux. From the => prompt, type:

run recovery

A bunch of text will scroll by as it starts up a small, temporary version of Linux whose only job is helping you install things. You'll know you're there when you see:

recovery login: 

Type root and press Enter — no password needed.

This whole process — entering Recovery Mode, what it's for — is also covered from Mono's side in their own flashing firmware guide and boot process overview, if you'd like the fuller picture of what's happening under the hood.

ip link set eth2 up
ip addr add 10.0.0.69/24 dev eth2

Now switch to your computer. Find the Ethernet adapter you plugged in and give it a fixed address by hand:

ip link show eth2

If the output includes LOWER_UP, the cable is on eth2 and you're set. If it doesn't, your firmware uses eth0 for port 3. Move the address over and check again:

ip addr del 10.0.0.69/24 dev eth2
ip link set eth0 up
ip addr add 10.0.0.69/24 dev eth0
ip link show eth0

If neither shows LOWER_UP, make sure the cable is in port 3 and fully clicked in on both ends.

python3 -m http.server 8000

No need to install anything — PowerShell can serve the file on its own. Adjust the $dir line below if you saved the file somewhere other than your Desktop, then paste the whole block in:

# folder containing the downloaded file
$dir = "$env:USERPROFILE\Desktop"

$listener = New-Object System.Net.HttpListener
$listener.Prefixes.Add("http://10.0.0.1:8000/")
$listener.Start()
Write-Host "Serving $dir on port 8000 -- leave this window open"

while ($listener.IsListening) {
  $context = $listener.GetContext()
  $name = $context.Request.Url.LocalPath.TrimStart('/')
  $filePath = Join-Path $dir $name
  if (Test-Path $filePath) {
    Write-Host "Sending $name ..."
    $bytes = [System.IO.File]::ReadAllBytes($filePath)
    $context.Response.ContentLength64 = $bytes.Length
    $context.Response.OutputStream.Write($bytes, 0, $bytes.Length)
  } else {
    $context.Response.StatusCode = 404
  }
  $context.Response.Close()
}

Leave that running — the little activity you see scroll by in a moment is a good sign, it means the router successfully connected.

7a · Save the startup firmware data

The first 32MB of the router's storage is reserved for its startup software (firmware). On a router that has had a Mono firmware update, that's where the firmware lives. The OPNsense image doesn't use this area, but writing the image to storage overwrites it with zeros. So we first need to save a copy of it to the router's memory:

dd if=/dev/mmcblk0 of=/tmp/emmc-first32mb.bin bs=1M count=32

It finishes in a second or two with 32+0 records in / 32+0 records out.

7b · Write OPNsense

This command does the actual work: it pulls the file from your computer, decompresses it on the fly, and writes it directly onto the router's internal storage chip.

curl http://10.0.0.1:8000/<image-filename>.img.bz2 | bzip2 -dc | dd of=/dev/mmcblk0 bs=1M

Swap <image-filename> for the real name of the file you downloaded in step 2 — for example, OPNsense-202610081133-arm-aarch64-GATEWAY.img.bz2. If you're not sure you've typed it exactly right, switch to the terminal window from step 6 and check its output: every successful request the router makes shows up there, filename included. This takes a few minutes — you'll see a progress readout climbing toward 100%, followed by two lines ending in records in / records out, which is the router's way of saying "the whole file arrived and I wrote every byte of it."

7c · Put the startup firmware data back

Now write the saved copy back. skip=1 seek=1 leaves the first 4KB alone, so the new OPNsense partition table you just wrote stays in place. This is the same form of command Mono uses in its own firmware instructions.

dd if=/tmp/emmc-first32mb.bin of=/dev/mmcblk0 bs=4096 skip=1 seek=1
sync

7d · Check it went back correctly

Run both of these. The two long codes they print must be identical:

dd if=/dev/mmcblk0 bs=4096 skip=1 count=8191 | sha256sum
dd if=/tmp/emmc-first32mb.bin bs=4096 skip=1 | sha256sum

If they differ, run the two commands from 7c again, then check again.

Reboot the router and this time, interrupt it — the moment you see Hit any key to stop autoboot:, press a key, same as you did to reach Recovery Mode earlier. You should land back at the => prompt.

reset

From the => prompt, type these four lines, pressing Enter after each one:

setenv opnsense "load mmc 0:1 ${kernel_addr_r} kernel.img; load mmc 0:1 ${fdt_addr_r} dtb/mono-gateway-dk.dtb; booti 0x82000000 - 0x88000000"
setenv bootcmd_bak ${bootcmd}
setenv bootcmd "run opnsense || run recovery"
saveenv

The first line teaches the router how to start OPNsense. The second keeps a copy of the router's original startup behavior, safely tucked away, in case you ever want it back. The third makes OPNsense the new default, falling back to Recovery Mode only if something's missing. saveenv writes all of that down permanently, so it survives power-offs and reboots — not just this one session.

reboot

Don't press anything during the countdown this time. Just watch — it should boot straight into OPNsense on its own.

*** OPNsense.internal: OPNsense 26.7.2_24 (aarch64) ***

 LAN (dtsec0)    -> v4: 192.168.1.1/24
 WAN (dtsec1)    ->

login: 

That's it. That's a real, complete, running copy of OPNsense, started entirely on its own. Log in with root and the password opnsense — the standard default for a freshly flashed image — to reach the console menu, or connect a computer to the router's LAN port and visit https://192.168.1.1 in a web browser to see the full graphical dashboard.