Skip to content

Releases

ApmonD 2.0.0

Choose a tag to compare

@bluewavenet bluewavenet released this 03 Nov 13:07

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: netifd wan or wan6 up 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>::1 with 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 ::1 every collector_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 ::1 up 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 ::1 after router_takeover_misses (3) checks without an answer.
  • When the old collector comes back it finds ::1 in 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, uci label_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/devicetree before starting the jail (r30).

Security: ujail, user apmond, CAP_NET_ADMIN only

  • apmond runs as user apmond (468) with only CAP_NET_ADMIN and 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/apmond is 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) and apmond-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 status shows crypto.

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 to lost_reports on the collector (r31, r33).
  • Status fields time_sync_failed and last_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 ::1 never falls back
    to IPv4: it waits for its node ULA however long DAD takes and keeps trying to claim each cycle (r34). Logged
    as portal 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 add of the 2.0
    package over 1.0.1 was tested and keeps /etc/config/apmond. Upgrade the collector last.
  • Config handling: /etc/config/apmond is 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:6873 under 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_seed is set, set it on every access point together (and key_epoch if 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> in br-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 commit is run there (revert with mesh11sd 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...
Read more

ApmonD 1.0.1

Choose a tag to compare

@bluewavenet bluewavenet released this 27 Oct 21:19
db2bddc

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, and apmond status parses the file instead of running it, so a rogue collector reply cannot run commands on an access point. The old 1.0.0 last_send format is still read.

New

  • node_status in each report now carries the node's apmond ULA (node_ula) and its IPv4 addresses (ipv4_addresses), after device_mac. Both are optional: the protocol stays at 1, and 1.0.0 collectors and mesh11sd accept and show the new report unchanged.
  • -v and --version print the version, as mesh11sd does, and service apmond start and restart print 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, a json_field() helper for the status JSON, and a clearer ipv6_canon() and json_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

Choose a tag to compare

@bluewavenet bluewavenet released this 26 Oct 19:11
8932837

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 vlan key per client, vlan_filtering bridges, wired byte counts labelled "stats_scope": "port"
  • apmon.cgi generated at daemon startup as mesh11sd does, cgi_dir option 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_seed is 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 in apmond-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.