Repository navigation
Releases
ApmonD 2.0.0
apmond 2.0.0 — release notes
Released Tue, 03 Nov 2026. Tag v2.0.0 in openNDS/apmond.
Overview
apmond monitors several OpenWrt access points on one LAN, however they are linked: cabled (the most common
setup), mesh, point-to-point, fibre or anything else. The link type does not matter to apmond.
Every access point runs the same daemon. It collects its radios, Wi-Fi clients and wired clients and reports
them, encrypted with AES-256-GCM, to one collector, where the data of every access point is available on
ubus, the apmond command line and LuCI. The other access points are senders.
2.0 is a rewrite in C: a shared library (libapmon) and the apmond daemon. It uses a new wire protocol
(protocol 2, docs/PROTOCOL.md: configurable port, PBKDF2 passphrase stretching, no compression).
It is not wire compatible with 1.x: all access points must run 2.x. The 1.x shell version stays in
openNDS/apmond.
New in 2.0
Collector / sender model and automatic election
- With
option role 'auto'(the default) an access point is a collector candidate only when it has an
upstream gateway (router) on its WAN: netifdwanorwan6up with a default route, not bridged into
another device, and not a bridge with several ports or a Wi-Fi port (r18).role 'collector'or
'sender'can be set instead. - Candidates elect the collector by claiming the collector ULA
<prefix>:<subnet>::1with duplicate address
detection: first come wins, after a random 0..claim_delay_max(10 s) delay. A candidate that finds::1
answering backs off and works as a sender. - The holder re-runs DAD on
::1everycollector_recheck(10) cycles and gives way if another access point
holds it. - A candidate checks that it can open the collector listener before it claims
::1, and gives::1up if the
listener fails later (r25, r26). The listener is bound to the LAN device only.
Failover and handback
- A backed-off candidate takes over
::1afterrouter_takeover_misses(3) checks without an answer. - When the old collector comes back it finds
::1in use and stays a sender: there is no automatic
handback; the new collector keeps the role until it fails. Two holders were never seen in testing. - Senders that lose the collector alternate between the collector ULA and the LAN IPv4 gateway and return to
the ULA by themselves once a collector answers.
Identity: factory MAC and node ULA
- An access point is identified by its factory (label) MAC,
node_mac, from a six-step chain (device tree
label-mac-device, board.json, ucilabel_macaddr, WAN permanent MAC, eth1/eth0/lan0/lan1,
lowest-ifindex ethernet) (r15, r29). Only permanent MACs are used, so a MAC changed at runtime by other
software never becomes the id. If nothing fits, apmond does not start. - Each access point adds its own node ULA (EUI-64 from its id); the prefix is derived from
apmon_seed. - Under the newer ujail that hides
/sys/firmware, the init script copies the device tree label MAC files to
/tmp/apmond/devicetreebefore starting the jail (r30).
Security: ujail, user apmond, CAP_NET_ADMIN only
- apmond runs as user
apmond(468) with onlyCAP_NET_ADMINand no_new_privs: under procd ujail where the
kernel supports it, otherwise by dropping privileges itself (eg ramips/mt76x8) (r14). - Fail closed when user apmond is missing; the init script recreates it (r25, r26).
/etc/config/apmondis root:apmond 0640. Reports are encrypted and authenticated; stale, replayed and
tampered messages are rejected.
Crypto variants
apmond(mbedTLS, default and recommended, especially on 16 MB flash devices) andapmond-openssl
(OpenSSL 3 libcrypto). Wire compatible, can be mixed on one LAN, same test vectors; they conflict with each
other and share the config (r21).ubus call apmond statusshowscrypto.
Command line and status
apmond status|nodes|node|clients|forget|block|debuglevel|read_log|bench|run, JSON (jq style) or-t
tables.- Build identity on every access point:
package_version,build_commit,running_sha256,
installed_sha256,restart_needed(r13). The package restarts apmond on upgrade (r12). - Sender summary line, always present:
reports sent N failed N time sync failed N last HTTP status N last error E, plus a pointer tolost_reportson the collector (r31, r33). - Status fields
time_sync_failedandlast_error(no connection,key rejected,
time or replay rejected,bad reply,HTTP NNN, empty after success) (r33). - The collector logs authentication failures at notice level, rate limited (r33).
- Extension blocks: other programs can attach JSON to an access point's reports (
ubus call apmond add_block). - VLAN of APs and clients from the bridge port PVID; optional VXLAN details where a bridge has a VXLAN port.
Wi-Fi data from nl80211 (no iwinfo) (r6, r19). - TIME_REQ and 409-rejected sequence numbers count as used, not lost (r27).
Collector address: ULA first, LAN-only IPv4 fallback
- Senders send to the collector ULA. At start a sender waits up to 30 s for its own node ULA to pass DAD
before choosing (r32). - If the ULA is still not ready, or a ULA send fails, it uses the LAN-side IPv4 gateway only (netifd
lan: its DHCP server, else its default-route nexthop) and retries the ULA after 10 IPv4 reports or a failed
IPv4 send. The WAN / kernel default route is never used as the collector; with no LAN gateway the sender
stays on the ULA (r34).
Collector-candidate wait
- A collector candidate (an access point with an upstream gateway) that does not hold
::1never falls back
to IPv4: it waits for its node ULA however long DAD takes and keeps trying to claim each cycle (r34). Logged
asportal candidate: waiting for node ULA ... (no IPv4 fallback).
luci-app-apmond 2.0
- Rewritten for apmond 2.x over ubus (rpcd), no ucode, CGI or rpcd plugin: Status, Access points
(ok/late/lost, restart needed, radios, VLAN/VXLAN, Forget), new Clients page, Settings for 2.x options, Log
with Follow. 2.0.0_beta-r2 adds wired link speed; r3 easier-to-read Access points and Clients. - 2.0.0_beta-r4: on a sender, Status, Access points and Clients show "This node reports to the collector at
" with a Go to collector button (opens the collector's Access points page in a new tab);
the collector shows a small "This node is the collector." note. - Getting the data: open LuCI on any access point (eg the address you already use, often the upstream
router's) and follow the collector link. The collector can move after a failover and there is no automatic
handback, so the link always follows the access point that holds the collector ULA now.
Upgrade notes
- From 1.x: upgrade every access point; 1.x and 2.x do not talk to each other.
apk addof the 2.0
package over 1.0.1 was tested and keeps/etc/config/apmond. Upgrade the collector last. - Config handling:
/etc/config/apmondis a conffile. If it was edited, apk keeps it and installs the new
default as/etc/config/apmond.apk-new; this is normal. Compare and remove it after upgrading. - Id change from early betas: upgrading from 2.0 beta r28 or older can change the id on boards that used
an interface MAC; the access point appears once as new (apmond forget <old node_mac>). - ULAs change on a downgrade to 1.x: 1.0.1 derives the node ULA differently (eg
...:9683:c4ff:fe52:6873
under 2.x became...:9483:c4ff:fe52:6873under 1.0.1). Anything that reaches access points by ULA (SSH,
monitoring) must use the new address. Upgrading back to 2.x restores the 2.x ULA. - If a new
apmon_seedis set, set it on every access point together (andkey_epochif used). - With mesh11sd, see also "Using apmond with mesh11sd" below.
Compatibility
- OpenWrt 25.12 or later, apk packages only (also tested on OpenWrt snapshot/master).
- Kernel 5.7+ for the jailed listener (all 25.12 targets run 6.x).
- Dependencies: libubox, libubus, libuci, libblobmsg-json, libmicrohttpd-no-ssl, plus libmbedtls or libopenssl.
- Any way of linking the access points into one LAN works: apmond only needs the LAN between them.
- Tested targets: aarch64_cortex-a53 (25.12 and snapshot), mips_24kc, mipsel_24kc.
Using apmond with mesh11sd
mesh11sd is one optional, supported setup; apmond does not need it.
- Optional in both directions: apmond is an optional extra to mesh11sd, never a dependency, and mesh11sd
does not depend on apmond. apmond 2.x does not conflict with mesh11sd. - Turn off mesh11sd's built-in apmond:
uci set mesh11sd.setup.apmond_enable='0', so only one monitoring
system runs (mesh11sd's built-in one speaks the 1.x protocol). - 1.x conflicts with mesh11sd: apmond 1.0.1 has
CONFLICTS:=mesh11sd, so a downgrade to 1.x is only
possible on access points without mesh11sd. - Node id: the factory MAC chain is the same one mesh11sd 8.0.0 will use (
mesh11sd_factory_mac()), kept
in agreement by shared test vectors. MACs rewritten by mesh11sd are never used as the id. - VXLAN: where mesh11sd builds its trunk as a VXLAN (
vxlan<tun_id>inbr-tun<tun_id>), APs and clients
on that bridge carry"vxlan": {"vni": N, "device": ...}. - LuCI on mesh11sd 7.x portals: with mesh11sd auto configuration, LuCI is disabled on a portal until
mesh11sd commit_all commitis run there (revert withmesh11sd revert_all revert). Until then the
Go to collector link lands on the mesh11sd status page instead of the collector's Access points page. - Known mesh11sd behaviour seen in testing (not apmond issues):
- With two portals, peers can switch their active portal. On a switch mesh11sd 7.3.1's
DHCP renew starts a second udhcpc with the busybox default script, which can flush the peer's br-lan IPv4
address or leave a different one than netifd rep...
- With two portals, peers can switch their active portal. On a switch mesh11sd 7.3.1's
ApmonD 1.0.1
ApmonD 1.0.1
A security and readability update to ApmonD 1.0.0. Upgrading is recommended on every node.
Security
- The collector's reply to a report is no longer sourced as shell. Each value is sanitised when it is written to
last_send, andapmond statusparses the file instead of running it, so a rogue collector reply cannot run commands on an access point. The old 1.0.0last_sendformat is still read.
New
node_statusin each report now carries the node's apmond ULA (node_ula) and its IPv4 addresses (ipv4_addresses), afterdevice_mac. Both are optional: the protocol stays at 1, and 1.0.0 collectors and mesh11sd accept and show the new report unchanged.-vand--versionprint the version, as mesh11sd does, andservice apmond startandrestartprint it too.
Readability
- The script was reworked for human readability: one statement per line, multi-line
if/for/case, blank lines between steps, short comments, ajson_field()helper for the status JSON, and a cleareripv6_canon()andjson_array(). There is no change in behaviour.
Tested on two GL-MT300N-V2 running OpenWrt 25.12.5, and with the mock end to end tests (238 pass, including a 1.0.0 collector receiving a 1.0.1 report).
Install: build the package with the feed template linux_openwrt/apmond/Makefile (OpenWrt 25.12 or later, apk), or use the OpenWrt packages feed once it lands there (openwrt/packages#30935).
LuCI support: luci-app-apmond 1.0.1.
Full list of changes: ChangeLog
ApmonD 1.0.0
ApmonD 1.0.0
First release of ApmonD, the access point monitoring daemon for OpenWrt: a standalone port of the apmond functionality of mesh11sd, for networks that do not use mesh11sd. Every node runs the same daemon and the same /etc/config/apmond; the router detects itself and becomes the collector, and every node sends it a signed report.
Highlights
- One passphrase (
apmon_seed) gives the shared IPv6 ULA prefix and the report signing secret - Router/collector auto detection, first come wins, with back off and failover
- Signed reports, protocol v1, same chunked HTTPS transport as mesh11sd; stale, replayed and tampered reports are rejected
- Wireless and wired clients, optional
vlankey per client, vlan_filtering bridges, wired byte counts labelled"stats_scope": "port" apmon.cgigenerated at daemon startup as mesh11sd does,cgi_diroption for web servers other than uhttpd, removed with the package- CLI:
status(JSON, with running and installed checksums),show_ap_data,get_ap_data,send,cleanup,read_log,debuglevel - Logging as mesh11sd, optional
log_mountpoint - Works out of the box with a built-in default passphrase, with a notice at start and every 6 hours until you set your own
- Log hints to check that
apmon_seedis the same on every node when the collector is unreachable or rejects the signature - Conflicts with mesh11sd (opkg
CONFLICTS, apk!mesh11sd)
Tested on two GL-MT300N-V2 running OpenWrt 25.12.5 (VLAN over 802.11s), and with the mock end to end tests (218 pass).
Install: build the package with the feed template linux_openwrt/apmond/Makefile (OpenWrt 25.12 or later, apk) and install it on every node. Submission to the OpenWrt packages feed is to follow.
LuCI support: luci-app-apmond 1.0.0.
Full list of changes: ChangeLog
Downloads
apmond-1.0.0-r1.apk: noarch apk for OpenWrt 25.12 and later, works on every target. Checksum inapmond-1.0.0-r1.apk.sha256.- It is not signed by an OpenWrt feed key, so install it with
apk add --allow-untrusted ./apmond-1.0.0-r1.apk - For LuCI, also install luci-app-apmond-1.0.0-r1.apk after apmond.