os-speedtest — OPNsense selectable-interface speed test plugin

Run an on-demand speed test through a user-selectable WAN or VPN interface on OPNsense, and keep a result history (ping, jitter, download, upload).

Egress is forced out the chosen interface by binding the test to that interface's IPv4 source address via speedtest-go --source=<wan_ip>.

Why speedtest-go, not speedtest-cli or the Ookla binary: speedtest-cli is unmaintained and its server list is broken (it returns only a tiny/outdated pool — e.g. no local servers). The official Ookla CLI can't bind to an interface/source IP on FreeBSD (its --interface/--ip binding fails). speedtest-go (github.com/showwin/speedtest-go) is actively maintained, uses the current speedtest.net server API (so local servers like Bangalore are found), supports --source binding on FreeBSD, and gives --json output.

Features

• Run page — pick any IPv4 WAN/VPN gateway, optionally pin a speedtest server ID, run, and watch a live speedometer (download + upload gauges, peak + elapsed) update every second.
• History page — last 100 results (ping, jitter, download, upload, server, egress IP), refresh and clear.
• Settings page — speedtest-go binary path, timeout, auto-FIB (no-op/legacy).
• API — run/status/history/interfaces/servers/clear.

Dependencies / prerequisites

• speedtest-go binary at /usr/local/bin/speedtest-go (prebuilt FreeBSD x86_64 from github.com/showwin/speedtest-go/releases; sha-verified install).
• The interfaces to be selectable must have an IPv4 address (static, DHCP or PPPoE all work; v6-only tunnels are excluded).

speedtest-go is not an OPNsense-repo package, so it is installed separately (manual binary), not via PLUGIN_DEPENDS.

How interface selection works

• Each gateway/interface is assigned the source IPv4 of its physical interface (e.g. opt13 → vlan05 → 43.224.128.241).
• The runner launches speedtest-go --json --source=<that ip>, so all sockets egress via the interface owning that address.
• Dynamic interfaces (DHCP/PPPoE) resolve their live address via ifconfig.
• Unresolvable (down/v6-only) interfaces report a clear error.

Data

• Live marker / last result: /var/db/speedtest/current.json
• History (append-only JSON lines): /var/db/speedtest/history.json
• speeds stored in bits per second (speedtest-go reports bytes/s; ×8), latency/jitter in ms (speedtest-go reports ns; /1e6).

API endpoints

Method	Endpoint	Action
GET	/api/speedtest/service/searchInterfaces	gateways + resolved source IP
POST	/api/speedtest/service/run	start a test (gateway,interface,server?)
GET	/api/speedtest/service/status	live marker / last result
GET	/api/speedtest/service/traffic	live bps while running
GET	/api/speedtest/service/history?limit=N	history (newest first)
POST	/api/speedtest/service/clearHistory	wipe history
GET	/api/speedtest/service/servers	nearest speedtest servers
GET/POST	/api/speedtest/settings/get /set	general settings

Start a test from the shell:

sudo php /usr/local/opnsense/scripts/OPNsense/Speedtest/speedtest_run.php \
  --gateway gw --interface opt13 --srcip 43.224.128.241 --binary /usr/local/bin/speedtest-go

Layout

Makefile                        # os-speedtest port (speedtest-go installed separately)
pkg-descr
+POST_INSTALL.post              # mkdir /var/db/speedtest
+PRE_DEINSTALL.pre
docs/DESIGN.md                  # original architecture (retained for history)
docs/DEPLOY_ROLLBACK.md         # live deployment, backups, rollback
packaging/build-txz.sh          # DIY .txz builder
packaging/HOSTING_README.md     # self-hosted repo
packaging/PR_SUBMISSION.md      # official opnsense/plugins submission
src/opnsense/
  mvc/app/{controllers,models,library}/OPNsense/Speedtest/
  scripts/OPNsense/Speedtest/speedtest_run.php
  service/conf/actions.d/actions_speedtest.conf   # configd: speedtest servers
  www/js/Speedtest/speedtest.js

License

BSD-2-Clause.