Files
feedc0de 5bb6e0fe55
Check source / check (push) Successful in 16s
Initial version (not finished, work in progress)
2026-11-18 10:10:39 +01:00

8.4 KiB

mikrotik-olsr

Build RouterOS packages with signing keys you control, and develop OLSRv1 support for MikroTik hardware.

Source · Prebuilt downloads · Build instructions · OLSR status

Experimental. Own-key installation, OLSRv1 neighbor discovery, hundreds of active native dynamic routes, and enable/disable cleanup have been tested on a hAP ac2. The embedded Winbox/WebFig configuration UI is still under development. A successfully signed NPK is not evidence that its service works on a device. See the release notes for the exact hardware and behavior tested in each build.

How it works

RouterOS packages are NPK files containing metadata, filesystems, and signatures. Changing a package invalidates its signature. Installing a new package therefore requires more than changing files and putting them back into an NPK.

There are two stages:

  1. Patch Netinstall. Its temporary installer runs on the router and must trust the public key corresponding to our modified NPKs. Linux Netinstall also checks packages on the host PC, so that verification key must be replaced too. This repository patches both Linux and Windows installers.
  2. Patch RouterOS itself. The system package contains the installed kernel and userspace package-verification code. Replace their verification key, then sign the resulting NPK. Re-sign the add-on packages with the same keyset. Once this system is installed, compatible modified or newly created packages signed with that keyset can be installed through its normal package mechanism.

We replace the trusted public key; we do not simply disable signature checks. The matching private signing keys stay on your build machine or in CI secrets. They are never included in firmware, the website, or public build artifacts.

The Ethernet/VLAN package set consists of routeros, option for open-source runtime utilities, and olsr for the daemon and service integration. Add a Wi-Fi package only if you need wireless interfaces and the complete set fits. Package contents and versions must fit the target device. For example, a hAP ac2 has only 16 MB of flash; the complete set may not fit without reducing the system/runtime payload. Do not assume netinstall -f fixes this.

High-level procedure

  1. Choose a supported RouterOS version and the correct hardware architecture.
  2. Either download one complete prebuilt release, or generate your own keys and build the installer and packages yourself.
  3. Connect the device for Netinstall, enter Etherboot mode, and install the matching patched system and selected add-on NPKs.
  4. Confirm RouterOS boots and management access works.
  5. Install additional compatible packages signed by the same publisher, or build and sign your own packages if you own that installation's private keys.

Switching publishers means changing the trusted key. A package signed with your new key is not automatically accepted by a device using someone else's patched firmware. Plan a coherent migration of the system and installed packages; this project's documented recovery/install route is Netinstall.

Changing signing keys also does not automatically provide a shell, startup hooks, a new Winbox menu, or a valid RouterOS license. Those are separate mechanisms. This project keeps official cloud endpoints and licensing code intact; it does not import the upstream project's private loader patch or license generator.

Build it yourself

The build scripts run on Linux (including an appropriate Linux VM). They produce both Linux and Windows Netinstall binaries. You do not need Windows to patch the Windows executable.

Install prerequisites on Debian/Ubuntu:

sudo apt-get update
sudo apt-get install python3-venv squashfs-tools curl tar unzip git make flex bison m4 gcc g++ bzip2
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Generate your own keys once and keep a backup:

python tools/routeros.py keygen --output .keys/local.json
python tools/routeros.py public-key --keys .keys/local.json --output public-key.json

The private key file is created with mode 0600, excluded from Git, and never overwritten by keygen. public-key.json is safe to share. Reuse the private keyset for future builds intended for the same installed devices.

Patch Netinstall

Download and extract the official installers for your version from download.mikrotik.com. Keep the originals for recovery. For example, after extracting version 7.25.1:

python tools/routeros.py netinstall netinstall-cli \
  --keys .keys/local.json --output netinstall-cli-custom
python tools/routeros.py netinstall netinstall.exe \
  --keys .keys/local.json --output netinstall-custom.exe

The patch command needs only public keys: --keys public-key.json works here too. The currently tested installer layout is the 32-bit Linux ELF / Windows PE layout used by 7.25.1. Unsupported inputs should fail rather than silently produce an unpatched installer.

Patch RouterOS and re-sign add-ons

Start from official, unmodified NPKs. The tool verifies their modern signature before modifying them.

mkdir -p dist
python tools/routeros.py npk routeros-7.25.1-arm.npk \
  --arch arm --patch-system --keys .keys/local.json \
  --output dist/routeros-7.25.1-arm.npk
python tools/routeros.py npk wifi-qcom-ac-7.25.1-arm.npk \
  --arch arm --keys .keys/local.json \
  --output dist/wifi-qcom-ac-7.25.1-arm.npk

--patch-system changes the installed verification keys. Merely re-signing the system NPK is insufficient, and the tool rejects that mistake. Add-on packages are re-signed without changing their functionality. All output NPKs are verified after signing.

Create a new package

Use an official add-on such as gps from the matching all_packages-arm archive as the metadata/dependency template. Supply a directory containing the new package's filesystem:

python tools/routeros.py create \
  --template gps-7.25.1-arm.npk \
  --root build/olsr-root --name olsr --description 'OLSRv1 routing service' \
  --keys .keys/local.json --output dist/olsr-7.25.1-arm.npk

This constructs and signs the package; it does not invent a startup registration or GUI backend. OLSR implementation status describes what still needs to be validated before this package is ready for normal installation.

For the complete download/build sequence and custom payload handling, see building.md. For CI configuration, see ci.md.

Prebuilt packages

Download published bundles from the Gitea releases page. If no release is listed, no prebuilt bundle has been published yet.

Use the installer, system NPK, and add-ons from the same release/keyset. Each bundle includes a public-key fingerprint, SHA-256 checksums, and a build manifest. These identify the release's publisher and exact files; they do not substitute for hardware testing. Locally built packages with your own keys require a system that trusts your keys.

The static download-page source is in site/. Its links are generated from release metadata rather than fictional or hard-coded download artifacts.

Development

python -m unittest discover -s tests -v
python tools/check_text.py

The repository uses English text. CI rejects CJK characters in tracked source, documentation, and configuration. Dependencies and their copyright notices are credited in THIRD_PARTY.md.

Updating only OLSR

After the initial own-key installation, upload the new matching olsr NPK to RouterOS Files (the root, not flash/) and reboot. Netinstall is not needed for each service change. Keep the same architecture, RouterOS version, and signing keyset. Update option only when its runtime utilities change. On the tested hAP ac2, same-version replacement of our OLSR NPK worked and retained the router configuration. Reserve flash headroom and check /log and /system/package after reboot.

The current service can be enabled or disabled using the OLSR entry under System → Scheduler, once configured. Its two-second heartbeat keeps a supervisor alive; disabling it withdraws native routes and clears the reserved kernel tables within approximately eight seconds in the measured test. See hardware results for limitations.