How We Fixed Broken OpenWrt Package Management — A Real World Story

🤖

AI-assisted content. This post documents a real troubleshooting session on a Rocket Plus router. All commands shown were run on actual hardware and produced the results shown. Written with AI assistance.

Contents

The problem — what broke and why
The hardware — Rocket Plus and what is inside it
The .ipk to .apk transition explained
Getting into the router via SSH
Diagnosing the broken package manager
Finding the right files for the right chip
The SSL problem — the real blocker
The fix — bootstrapping SSL with curl
Pointing the router at the right archive
Verifying everything works
Summary — the complete fix in order

1. The problem — what broke and why

We were setting up a Rocket Plus router and wanted to install some additional packages — specifically a browser-based terminal so we could access the command line without needing a separate SSH client. Simple enough. We opened an SSH connection to the router, typed the standard install command, and got this:

Unknown package 'luci-app-ttyd'.
Collected errors:
 * opkg_install_cmd: Cannot install package luci-app-ttyd.

The package manager did not know the package existed. We tried updating the package list first — the standard first step — and got something much worse:

Downloading https://downloads.openwrt.org/releases/21.02-SNAPSHOT/packages/aarch64_cortex-a53/base/Packages.gz
wget: SSL support not available, please install one of the libustream-.*[ssl|tls] packages
*** Failed to download the package list
 * opkg_download: Failed to download ...Packages.gz, wget returned 1.

Two separate problems hiding inside one error message. The router could not make HTTPS connections because it had no SSL library installed. And even if it could, the URL it was trying to reach — releases/21.02-SNAPSHOT/ — no longer exists on the OpenWrt download server.

This is what a fully broken package manager looks like. The router is working fine as a router — internet, WiFi, 5G all functioning perfectly. But installing anything new is impossible until the package manager is fixed.

2. The hardware — Rocket Plus and what is inside it

Before we get into the fix, it is worth understanding the hardware. Knowing exactly what chip your router uses is essential for finding the right packages — download the wrong architecture and nothing will install.

The Rocket Plus is built on a ZBT Z8803BE platform. Here are the details that matter for package management:

Component	Detail	Why it matters
Router chip	MediaTek MT7988A	Determines the target directory on OpenWrt servers
CPU architecture	aarch64_cortex-a53	This is the critical string — every package filename ends with this
5G modem	Quectel RM500U-EA	Uses cdc_ncm driver — different to QMI-based modems
OpenWrt version	21.02-SNAPSHOT	Old snapshot build — this is why packages are broken
Package format needed	.ipk (old format)	Current OpenWrt uses .apk — incompatible with this firmware

The Quectel RM500U-EA is a 5G Sub-6GHz modem supporting both NSA (Non-Standalone) and SA (Standalone) 5G networks. It supports bands including N1, N3, N28, N41, N78 and N79 — covering all major UK 5G networks. On this router it runs via the cdc_ncm driver, presenting as a standard network interface rather than a QMI device.

You can check your own router's exact details by running this command via SSH:

# Check your router's exact hardware and firmware details
ubus call system board

# Output will look like this:
{
  "kernel": "5.4.271",
  "hostname": "OpenWrt",
  "model": "Zbtlink Z8803BE",
  "board_name": "zbtlink,zbt-z8803be,mt7988a-nand",
  "release": {
    "version": "21.02-SNAPSHOT",
    "target": "mediatek/mt7988",
    "description": "OpenWrt 21.02-SNAPSHOT r16881"
  }
}

# The critical line is the architecture in distfeeds.conf
cat /etc/opkg/distfeeds.conf
# Look for "aarch64_cortex-a53" in the URLs — that is your architecture

3. The .ipk to .apk transition explained

OpenWrt has traditionally used a package format called .ipk — managed by a tool called opkg. If you have used OpenWrt for any length of time, opkg is what you type when you want to install something.

OpenWrt is now transitioning to .apk — Alpine Package Keeper — the same package format used by Alpine Linux. The new format is faster, uses less memory, and has better dependency resolution. But it is incompatible with the old opkg system.

Fig 1. The old firmware shipped pointing at 21.02-SNAPSHOT repos which were later deleted. The current snapshot server now serves .apk files that the old opkg tool cannot install.

The practical consequence for anyone running an older OpenWrt snapshot build is a perfect storm of failure. The URLs the router knows about no longer exist. The files that do exist on the server are in a format the router cannot use. And the router has no SSL library installed, so it cannot even reach HTTPS servers to find out any of this.

The solution is to find the correct archived .ipk packages for your specific architecture — in our case aarch64_cortex-a53 — use a tool that does have SSL to download them, and point the package manager at the right archive going forward.

4. Getting into the router via SSH

Everything from here requires SSH — a way of typing commands directly into the router from your computer. If you have never used SSH before, the Bash and SSH section of our OpenWrt guide covers it in detail. Here is the short version.

On Windows, open PowerShell (press the Windows key, type PowerShell, press Enter). On Mac, open Terminal. Then type:

# Connect to your router — replace 192.168.1.1 if your router uses a different IP
ssh root@192.168.1.1

# If you get a "WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED" error:
ssh-keygen -R 192.168.1.1
# Then try ssh again — this clears the old remembered key

# Type your router password when asked
# You should see: root@OpenWrt:~#
# That hash symbol means you are logged in as administrator

5. Diagnosing the broken package manager

Once in via SSH, the first step is to understand exactly what is broken and why. Do not try to fix things before you understand them — you will make it worse.

# Step 1 — Check what repos the router is trying to use
cat /etc/opkg/distfeeds.conf

# On a broken router this will show something like:
src/gz openwrt_base https://downloads.openwrt.org/releases/21.02-SNAPSHOT/packages/aarch64_cortex-a53/base
# These URLs return 404 — the files were deleted from the server

# Step 2 — Check the opkg config for signature checking
cat /etc/opkg.conf
# Look for "option check_signature" — this causes problems without SSL

# Step 3 — Check if curl is available (this is important)
curl --version 2>/dev/null | head -2 || echo 'no curl'
# If curl shows OpenSSL in the output, we have a way forward

# Step 4 — Check if wget has SSL (it usually does not on old builds)
ls /usr/lib/libustream* 2>/dev/null || echo 'no SSL library'

What we found on our router: curl was installed and had OpenSSL support. wget had no SSL support at all. The distfeeds.conf was pointing at dead URLs. This told us exactly what to do.

Why this matters — the chicken and egg problem

To install the SSL library you need to download it. To download it you need SSL. The router's wget cannot make HTTPS connections without the SSL library — but the SSL library is only available over HTTPS. This is a genuine circular dependency. The solution is that curl — which already has SSL built in — can download the file that wget needs, breaking the loop.

6. Finding the right files for the right chip

This is the step most guides skip and most beginners get wrong. Installing packages built for the wrong architecture simply does not work — and there is no error message that tells you the architecture was wrong. The package just refuses to install.

Your router's architecture string is the most important thing to know. Ours is aarch64_cortex-a53. Every package file for our router ends with this string — for example libustream-openssl20201210_2022-01-16-868fd881-2_aarch64_cortex-a53.ipk.

Fig 2. Every OpenWrt package filename tells you exactly what it is, what version it is, and crucially — which CPU architecture it was compiled for. The architecture must match your router's chip exactly.

The archive for old .ipk packages is at archive.openwrt.org. The path structure is:

# The archive URL structure for 21.02.3 stable packages:
https://archive.openwrt.org/releases/21.02.3/packages/[ARCHITECTURE]/[FEED]/

# For our router (aarch64_cortex-a53) the four main feeds are:
https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/
https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/luci/
https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/packages/
https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/routing/

# You can browse these URLs in a normal web browser to see what is available

We chose 21.02.3 specifically because it is the last stable release of the 21.02 branch — the same era as the firmware on our router. Using packages from a very different version can cause compatibility problems.

7. The SSL problem — the real blocker

Even after finding the right archive URLs, we hit another wall. The archive server only serves over HTTPS. The router's wget has no SSL support. Changing the URLs from https to http just caused the server to redirect back to https — and wget, without SSL, could not follow that redirect.

The error looked like this:

wget: SSL support not available, please install one of the libustream-.*[ssl|tls] packages
*** Failed to download the package list from https://archive.openwrt.org/...

We needed to install the SSL library to fix wget — but we needed wget to download the SSL library. Classic circular dependency.

The solution was curl. Unlike wget, curl on this firmware was compiled with OpenSSL support built in. It could make HTTPS connections already. We used curl to download the SSL library directly — bypassing wget entirely — and then installed it manually.

8. The fix — bootstrapping SSL with curl

Here is the exact process. Every command is explained.

1 Find the exact filename of the SSL package in the archive. We use curl to fetch the Packages list and search it with grep — the text search tool.

# curl fetches the Packages list over HTTPS (curl has SSL, wget does not)
# grep searches through it for the line starting with "Package: libustream-openssl"
# -A3 means show 3 lines After the match — this gives us the version number
curl -sL https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/Packages | grep -A3 "^Package: libustream-openssl"

# Output:
Package: libustream-openssl20201210
Version: 2022-01-16-868fd881-2
Depends: libc, libubox20210516, libopenssl1.1
# Now we know the exact package name and version

2 Download the SSL package using curl with the -L flag. The -L flag tells curl to follow redirects — without it, curl stops at the first redirect and downloads a tiny HTML page instead of the actual file.

# -L means follow redirects
# -o means save the output to this filename in /tmp (temporary storage)
curl -L -o /tmp/libustream-openssl.ipk "https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/libustream-openssl20201210_2022-01-16-868fd881-2_aarch64_cortex-a53.ipk"

# You should see a progress bar showing the actual file size downloading
# The file should be around 5-6KB — if it is only 146 bytes, -L is missing
  % Total    % Received  ...
100  5655  100  5655    0     0  12707  ...  12707
# 5655 bytes — that is the real file

3 Install the SSL package. The --nodeps flag tells opkg to install it without checking dependencies — necessary because the dependencies cannot be verified yet without a working package list.

# --nodeps skips dependency checking
# We know the dependencies are already on the router from the base install
opkg install --nodeps /tmp/libustream-openssl.ipk

# Should output:
Installing libustream-openssl20201210 (2022-01-16-868fd881-2) to root...
Configuring libustream-openssl20201210.

4 Install the CA certificate bundle the same way. This is the list of trusted certificate authorities that SSL uses to verify servers are who they claim to be.

# Find the exact ca-bundle filename
curl -sL https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/Packages | grep -A3 "^Package: ca-bundle"
# Returns: Version: 20211016-1

# Download and install it
curl -L -o /tmp/ca-bundle.ipk "https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/ca-bundle_20211016-1_all.ipk"
opkg install --nodeps /tmp/ca-bundle.ipk

9. Pointing the router at the right archive

With SSL working, we now needed to point the package manager at URLs that actually exist and contain the right format files.

# This command completely rewrites distfeeds.conf with the correct archive URLs
# cat > means "write the following to this file, overwriting what was there"
# << 'EOF' means everything until EOF is the content to write
cat > /etc/opkg/distfeeds.conf << 'EOF'
src/gz openwrt_base https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base
src/gz openwrt_luci https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/luci
src/gz openwrt_packages https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/packages
src/gz openwrt_routing https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/routing
EOF

# Also remove the check_signature line from opkg.conf
# This line requires SSL signature verification — which was failing
# Edit via LuCI: System > Software > Configure OPKG > /etc/opkg.conf
# Remove the line that says: option check_signature

10. Verifying everything works

# The moment of truth — update the package lists
opkg update

# If everything worked you will see:
Downloading https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/Packages.gz
Updated list of available packages in /var/opkg-lists/openwrt_base
Downloading https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/luci/Packages.gz
Updated list of available packages in /var/opkg-lists/openwrt_luci
Downloading https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/packages/Packages.gz
Updated list of available packages in /var/opkg-lists/openwrt_packages
Downloading https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/routing/Packages.gz
Updated list of available packages in /var/opkg-lists/openwrt_routing

# No errors. Four feeds updated. Package manager fully working.
# Now install packages normally:
opkg install luci-app-ttyd htop picocom

Why 21.02.3 specifically?

We used the 21.02.3 stable release archive rather than trying to use the current snapshot server for two reasons. First, current snapshot packages are .apk format — incompatible with the old opkg on this firmware. Second, 21.02.3 is the same era as the firmware on our router — using packages from a very different version can cause library version mismatches. The archive at archive.openwrt.org preserves old releases permanently, so these URLs will keep working.

11. Summary — the complete fix in order

Here is the entire fix condensed into the minimum number of commands, in the right order:

## COMPLETE FIX FOR BROKEN OPKG ON OPENWRT 21.02-SNAPSHOT (aarch64_cortex-a53)
## Run these commands via SSH in order

# 1 — Download SSL library using curl (which has SSL built in)
curl -L -o /tmp/libustream-openssl.ipk "https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/libustream-openssl20201210_2022-01-16-868fd881-2_aarch64_cortex-a53.ipk"

# 2 — Install SSL library
opkg install --nodeps /tmp/libustream-openssl.ipk

# 3 — Download CA bundle
curl -L -o /tmp/ca-bundle.ipk "https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base/ca-bundle_20211016-1_all.ipk"

# 4 — Install CA bundle
opkg install --nodeps /tmp/ca-bundle.ipk

# 5 — Point package manager at the correct archive
cat > /etc/opkg/distfeeds.conf << 'EOF'
src/gz openwrt_base https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/base
src/gz openwrt_luci https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/luci
src/gz openwrt_packages https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/packages
src/gz openwrt_routing https://archive.openwrt.org/releases/21.02.3/packages/aarch64_cortex-a53/routing
EOF

# 6 — Remove signature checking from opkg.conf
# Edit via LuCI: System > Software > Configure OPKG > /etc/opkg.conf
# Delete the line: option check_signature

# 7 — Update package lists — should work cleanly now
opkg update

# 8 — Install whatever you need
opkg install luci-app-ttyd htop picocom

This fix is specific to this hardware and firmware

The exact package filenames, architecture string, and version numbers in this guide apply specifically to the Rocket Plus running OpenWrt 21.02-SNAPSHOT on aarch64_cortex-a53 hardware. If your router uses a different architecture — mipsel_24kc, arm_cortex-a7, x86_64 etc — you need to substitute your own architecture string throughout. Check your router's architecture by running cat /etc/opkg/distfeeds.conf and reading the architecture from the existing URLs.

This guide is provided for information only. Rocket Routers is not responsible for any issues arising from following these instructions on your hardware. Always back up your router configuration before making changes.