Frequently asked questions
Answers below describe oonfeeWRT v0.1.8 unless a historical release or rollback target is named explicitly.
What is oonfeeWRT?
It is a self-hosted controller for stock OpenWrt. It provides one interface for fleet visibility, site configuration, safe Apply/rollback, topology, clients, radios, events, accounts, diagnostics, and controller backup/restore.
Is oonfeeWRT firmware?
No. It does not build, replace, patch, or upgrade OpenWrt firmware. Managed routers stay on stock OpenWrt and continue to work with LuCI.
The Firmware page checks official same-branch release metadata on request. It does not download, stage, validate image bytes, or flash firmware. A candidate result is not approval to install it.
Does the controller run on a router?
No supported release does. Run the controller on a 64-bit Linux or macOS host, NAS, mini-PC, SBC, server, or Docker host. OpenWrt-hosted operation is not built, packaged, tested, or budgeted.
Is Docker required?
No. The standalone binary and container run the same controller and embedded UI. Release binaries support Linux/macOS on amd64/arm64; the image supports Linux amd64/arm64.
Does it require the cloud?
No. Controller state and accounts are local. Remote sites require an existing routed management network or VPN; oonfeeWRT does not provide cloud relay or NAT traversal.
Internet access is still needed for actions that inherently use it, such as downloading releases/images, reaching OpenWrt package feeds for an explicitly approved optional capability, or running the Cloudflare speed test.
Can it manage non-OpenWrt or UniFi devices?
No. Its transport, capability model, and renderer target OpenWrt. It does not implement vendor inform protocols or proprietary device APIs.
Does adoption install software on my router?
Adoption never installs a package, executable, daemon, service, firmware, or custom controller code. With explicit default-off consent, it creates/replaces one rpcd ACL JSON file and creates one scoped oonfeewrt login. Managed devices receive the managed ACL group. Monitor-only devices receive the distinct read-only oonfeewrt-monitor group for observation.
The optional LLDP capability is a separate workflow. It may install official OpenWrt feed packages only after showing and binding an exact plan to separate acknowledgements.
Since v0.1.6, the controller also provides an optional, manually built and installed rpcd helper for narrow read-only integrations. It is not required for ordinary adoption and is never installed by it. The helper adds no daemon, listener, remote shell, or firmware-write method. See Firmware and Integrations before considering that opt-in.
Why does adoption ask for SSH?
Stock rpcd cannot create its own scoped login or write an ACL file through ubus, even when the ubus caller is root. SSH is therefore used for the approved bootstrap transaction. Normal polling and configuration use scoped ubus.
The device administrator credential is used for the transaction and is not stored.
What does Monitor only mean?
It keeps a reachable OpenWrt router in polling, inventory, telemetry, events, and topology without giving it desired-configuration authority. Monitor-only devices are excluded from Preview, Apply, site configuration, optional LLDP installation/configuration/removal, wireless-neighbor mutation, and other package/config/remove operations. Existing LLDP observation remains available. Their scoped ACL lifecycle and un-adoption remain explicit maintenance actions.
A capable monitor-only radio can still run a separately acknowledged RF scan. That is an active, transient observation, not configuration authority: the serving radio goes off-channel and clients may pause, roam, or disconnect, but the scan has no intended persistent configuration change.
Multiple monitor-only routers may be observed across routed management subnets, but oonfeeWRT neither creates those routes/VPNs nor turns the devices into managed failover gateways. A site still permits only one managed Gateway.
Can I keep using LuCI and SSH?
Yes. oonfeeWRT ordinarily writes only sections it owns and leaves foreign/human-managed sections alone. v0.1.4 has one explicit exception: a non-Router-managed IPv6 policy on the Gateway management LAN may patch only allowlisted IPv6 options on the exact existing LAN interface, its single matching DHCP section, and supported conventional wan/wan6 sections when present. It never creates, claims, renames, or deletes those foreign sections. Missing, ambiguous, wrong-type, or unsafe static-IPv6 targets block Preview. Other foreign conflicts are reported instead of silently taken over.
Avoid editing the same controller-owned section simultaneously through LuCI. For an explicit management-LAN IPv6 change, also avoid editing the named foreign options during Apply. Finish or abandon one change path, then generate a fresh Preview.
Does saving a WLAN or network immediately change routers?
No. Saving changes controller desired state only. Preview computes exact per-device changes; Apply is a separate reviewed action.
The same boundary applies to named policy sets. Creating, renaming, or changing exact-MAC membership changes controller intent only. Referencing firewall rules resolve the current members during a fresh Preview; a router changes only after acknowledged Apply.
MAC intent is accepted only when the exact MAC has a stored This network (local) observation from the currently adopted Managed Gateway. Schema 23 keeps that source-relative evidence in client_observations, keyed by device and MAC. Monitor-only observations can still populate global inventory, but they neither satisfy nor contaminate the managed-Gateway proof, including after un-adoption. Policy-set create/update, direct or set-backed MAC Secure drafts, and blocked/fixed-address intent fail closed without that proof. Active MAC intent blocks Preview until every referenced client is re-observed locally; this commonly matters just after an upgrade or portable restore, before the next successful managed-Gateway client poll. Portable restore deliberately clears all source-relative observations because source-controller evidence is not destination-controller write authority. Source-relative observations also age out at the normal 30-day client-retention cutoff even when desired intent keeps the merged client row; the intent remains stored, but Preview blocks until the Gateway observes the MAC locally again. Existing blocked/fixed-address intent can still be cleared one client at a time. Use network/zone or explicit IPv4 scope for cross-device policy.
What happens if Apply breaks connectivity?
oonfeeWRT stages UCI with OpenWrt rollback enabled. It confirms only after reconnecting and verifying expected runtime state. If connectivity or health verification fails, the router's rollback timer is left active. A subsequent read can prove that OpenWrt reverted; until it does, the outcome is unknown and the changed state may still be live. Do not retry until the first operation is understood.
Keep independent LuCI/SSH access and start with one non-critical device. See the Safety model.
Does it support every OpenWrt device?
No universal claim is possible. Hardware, drivers, switch architecture, rpcd modules, and package sets vary. The controller probes each device and reports unsupported, unavailable, stale, and partial facts.
The full published physical record covers a Linksys WRT3200ACM and TP-Link Archer C6 v2 on OpenWrt 25.12.5. v0.1.3 additionally has reporter-confirmed, read-only inspection evidence for one Cudy M3000 v2/Filogic variant; it does not claim adoption, Apply, VLAN, or broader Filogic validation. Other devices may work with different gaps.
What can I share from Inspect?
Use Export sanitized compatibility report, not the full Inspect response or raw router output. The format-version-1 JSON contains a bounded allowlist of board/firmware, physical-radio, LAN/WAN label, switch-mode, feature-state, and supported-function evidence. It excludes the target address and MAC, site and router identity, credentials, network configuration, clients, live telemetry, timestamps, runtime radio/PHY and bridge-member identifiers, and free-text notes.
The server omits the report when it cannot satisfy strict safety and size bounds. The browser download makes no extra router call, is not stored or uploaded by the controller, and becomes an ordinary local file after download. It helps maintainers compare compatibility evidence; it is not proof that adoption, Apply, VLANs, RF, telemetry, or resource budgets work on that device.
Why are some values “Unavailable” instead of zero?
Zero is a measurement. Unavailable means the controller could not obtain or trust the measurement. Treating a missing driver counter or failed RPC as zero would produce confident but false charts and health claims.
The Statistics workspace introduced in v0.1.6 applies the same rule across its complete requested time window. An absent bucket breaks the line and lowers its observed/expected coverage; it is not converted to zero or joined to the next known value. See Statistics and historical telemetry.
How does oonfeeWRT choose the WAN interface?
The selector introduced in v0.1.3 reads the installed IPv4 route table and netifd logical interfaces in one topology poll. The controller selects the unique usable lowest-metric default in the kernel main table, then maps its kernel device to exactly one active logical interface that also reports a default. This is why logical wan over runtime pppoe-wan can use pppoe-wan traffic counters while a modem management interface no longer wins by list order.
It does not choose between distinct equal-metric defaults, ECMP/multipath, policy-routing tables, mwan3, unmappable devices, or bond members. Missing, malformed, ambiguous, or inconsistent evidence stays unavailable, and an exact matching RX/TX series must exist before WAN throughput is shown. Collection is on a baseline 15-minute topology cycle, not a rapid failover monitor.
Can oonfeeWRT disable IPv6?
v0.1.4 adds a per-network IPv6 policy. Router managed preserves the router's existing IPv6 settings, Prefix delegation renders a /48–/64 LAN assignment, and Disabled stops controller-managed RA, DHCPv6, NDP, and delegated assignment. Existing networks migrate to Router managed, so upgrading alone does not change a router.
The change still requires Preview and Apply. On a controller-owned VLAN it manages that VLAN's IPv6 interface/service/firewall state. On the management LAN, it patches the exact existing LAN/DHCP sections and also coordinates supported conventional upstream sections: Disable sets network.wan.ipv6=0 and a DHCPv6 network.wan6.auto=0; Prefix delegation can enable a supported PPP parent and DHCPv6 client. Missing wan/wan6 sections are accepted and remain absent; custom/static wan6 protocols remain router-managed.
Static ip6addr, ip6prefix, or ip6gw values on the management LAN or a conventional WAN target block Disable instead of being deleted. Prefix delegation also depends on a working ISP/upstream delegation; oonfeeWRT does not invent an IPv6 default route.
The option patches do not transfer section ownership and are excluded from normal prune/drift ownership. Switching back to Router managed or un-adopting does not reconstruct earlier values; use a router backup when an exact reversal matters.
Why does one IPv6 warning show many occurrences?
Exact repeat compaction shipped in v0.1.1. The odhcpd router-advertisement/no-usable-default-route message uses one condition row per router-log producer epoch; repeats increment its count while retaining first/latest evidence. Startup converts matching legacy raw rows to the same bounded form. This only bounds controller SQLite rows; it does not suppress or delete the router's own logd output.
v0.1.4 adds the card above Logs → General. It is current status, not a view of every retained row: independently of table filters and pagination, it names affected routers, totals occurrences, links to Review IPv6 and Apply, and appears only for recent evidence with a fresh router-log cursor. Fresh quiet clears the banner while an old compact row can remain; stale or gapped collection is unknown, not proof that IPv6 recovered. Fix upstream delegation or apply Disabled, then verify fresh coverage stays quiet.
Why is router clock status unavailable after upgrading?
v0.1.4 can read router UTC through luci.getUnixtime, with luci.getLocaltime as a compatibility fallback. Existing adopted routers keep their older scoped ACL, so ordinary management continues but this new read is unavailable until an Administrator separately reviews and applies the updated controller-access payload. Re-adoption is not required, and the read does not set the router clock. The General Logs notice uses only a fresh successful comparison and appears when the absolute offset is at least five minutes; existing event timestamps are not rewritten.
Why is an online device “Unplaced” in Topology?
Online proves controller reachability. It does not prove a current physical parent. Dynamic FDB or neighbor evidence can expire, and some stock BusyBox sources omit VLAN/port identity. The graph refuses to invent a link.
v0.1.4 also treats some FDB rows as possible transit evidence. When fresh direct evidence proves a multi-hop managed path, the current view hides the redundant upstream candidate rather than drawing several direct parents. The raw interval remains in history and can reappear if the direct proof becomes stale, fails, is ambiguous, or closes. A clean FDB-only link is labelled inferred; missing BusyBox VLAN provenance alone is neutral unavailable metadata, not proof that the link is wrong.
Optional LLDP can provide stronger managed adjacency, at the cost of an explicit official-package/service workflow.
Does RF scanning run automatically?
No. A serving-radio scan can disrupt clients, so it requires an explicit acknowledgement and is never scheduled. Capability refresh/re-probe does not run a scan.
Where does the speed test run?
From the controller host or container through Cloudflare. It does not call or modify a router, but its traffic follows the normal WAN path. The test uses about 15 MiB, is bounded to 30 seconds, and can temporarily saturate the WAN.
Gateway-run testing, loaded latency, and loaded jitter are unavailable in v0.1.8.
Does the controller have HTTPS?
Not natively in v0.1.8. Bind it to loopback or a trusted isolated management LAN and use a trusted reverse proxy for TLS. Do not expose port 8080 directly to the Internet.
What account roles are available?
Owner, Administrator, Operator, and Read-only. Owners manage accounts and portable backup/restore; Administrators manage devices/configuration and diagnostics; Operators run approved operational tests; Read-only users view state. See Permissions.
Where are credentials stored?
Router and Wi-Fi credentials are sealed in SQLite using a random data key from keyring.json. The runtime passphrase unwraps that key. The device administrator credential supplied for bootstrap/cleanup is not stored.
Authenticated WLAN/mesh reads report only whether a key exists; there is no reveal endpoint.
What must I back up?
For filesystem recovery:
- a consistent
oonfeewrt.dbsnapshot; - its exact sibling
keyring.json; and - the runtime passphrase/passphrase file, kept separately.
The database, keyring, and passphrase cannot recreate one another. Do not copy only a live WAL-mode database main file.
Alternatively, an Owner can export encrypted .oowrtbak controller state with a separate export passphrase. See Data and retention.
Does portable restore change routers?
No router is contacted or automatically configured during restore. Successful restore restarts the controller, revokes sessions, creates a pre-restore safety artifact, and suppresses router writes until an Owner reviews state and types RESUME ROUTER WRITES after reauthentication.
What is in a diagnostics bundle?
Bounded stored controller evidence: controller health/version/schema, stored device model/firmware/capability facts, coverage state, bounded events, and a redacted controller-log tail. Generation makes zero live router management calls.
It excludes passwords, password hashes, sessions/CSRF tokens, router credentials, Wi-Fi keys, private keys/certificates, raw database/keyring, client notes, and fixed-address assignments.
How long is history kept?
Defaults include five-minute metrics for 14 days, hourly metrics for 396 days, OpenWrt logs for 24 hours, closed topology intervals for 31 days, 100,000 controller/audit events, and the newest three terminal speed tests. See the complete retention table.
The Statistics page offers 6h, 24h, and 7d views at the server-selected five-minute resolution and a 30d view at hourly resolution. It reads completed stored rollups only; opening the page does not focus devices or preserve raw samples.
Can I downgrade from v0.1.8?
Yes, using a verified matching recovery unit. v0.1.8 retains schema 25 from v0.1.6 and v0.1.7, so returning to either version crosses no schema boundary. Still preserve the exact target binary/image, matching database, keyring, and runtime passphrase and follow the controlled recovery procedure.
Returning to v0.1.5 or earlier is different: v0.1.5 uses schema 23 and cannot open the newer database. Stop v0.1.8, retain its current recovery unit separately, and restore the schema-23 database, keyring, runtime passphrase, and v0.1.5 binary/image together. Replacing only the executable or image tag is not a rollback. A pre-upgrade v0.1.5 portable backup can instead be restored through a clean v0.1.5 instance.
For an even older target, use its own supported schema and matching recovery unit—not a v0.1.5 backup. The historical boundaries below still apply.
Historical v0.1.5 to v0.1.4 rollback
v0.1.5 migrates the controller database from schema 20 through schemas 21 and 22 to schema 23. The steps add management mode, reusable policy sets, source-relative client provenance, and a rebuilt one-managed-Gateway uniqueness guard. Schema 23 also adds bounded observation/global-client MAC indexes. The v0.1.4 binary cannot open schema-23 state. To roll back, stop the controller and restore the matching pre-upgrade schema-20 database, keyring.json, runtime passphrase, and v0.1.4 binary/image together. Replacing only the executable or image tag is not a valid rollback.
If you retained only the pre-upgrade portable .oowrtbak, start v0.1.4 against a separate empty data directory or volume and restore that artifact through its Backup & Restore screen. Do not reuse the schema-23 live volume; no public CLI extracts the portable artifact in place.
Preserve the current pair before any restore as well. Migration or rollback does not revert configuration that was already Applied to routers.
Historical v0.1.0-rc.1 uses schema 17. Rolling back that far requires the untouched pre-upgrade schema-17 database, matching keyring, prior passphrase, and old binary/image together. Do not open schema-19, schema-20, schema-23, or schema-25 data with the RC daemon.
What is deliberately out of scope?
- required controller-authored router daemons, general remote-command services, and automatic helper installation;
- custom firmware, forks, or package feeds;
- non-OpenWrt device adoption;
- cloud remote access, SSO brokering, multi-site, and automatic NAT traversal;
- native mobile apps;
- continuous proprietary spectrum analysis, paid threat feeds, and branded AI features; and
- DPI/application flow history on constrained routers in v0.1.8. The Phase 5 feasibility page does not install or ship a flow package.
What changed in v0.1.8?
The Devices page now handles a null or omitted LLDP package list and displays an empty controller-added list as none recorded. This rendering fix needs no LLDP reinstall, reset, or re-adoption and does not claim to solve every LLDP installation failure.
Shared-PHY devices now preserve each configured UCI wifi-device section key instead of deriving target identity from the PHY. If an affected device was previously probed, inspect any earlier Apply outcome, re-probe it, and review a fresh Preview for distinct targets before separately authorizing Apply. Do not edit the database, clear ownership, or re-adopt as recovery.
What is new in the v0.1.7 interface?
The Precision shell uses a slim collapsible sidebar, a compact profile shortcut, and the attributed Lucide orbit project mark. Operational screens sit under Workspace; Statistics, Reports, and Alerts sit under Insights. Firmware and Integrations are now Settings tabs, with bookmarkable query URLs and working legacy links. Accounts remains a separate bottom navigation item. The Dashboard uses one compact responsive fleet strip, with evidence notes left and values right; missing data is not hidden.
Reports now blocks the previous result and CSV while a changed period or refresh is loading. Router permissions, collection behavior, and schema 25 are unchanged from v0.1.6.
Capabilities introduced in v0.1.6 are retained: Statistics, Reports, Alerts, editable topology, device Cards/List, firmware metadata checks, integrations, and mobile/installed-app presentation are described in their guides. Try the isolated demo for a populated fictional network without controller or router access. It is not a hardware test and accepts no real credentials.
Do Reports measure total usage or guaranteed uptime?
No. They summarize valid stored samples and disclose observed/expected buckets. The reachability measurement concerns the configured fixed ICMP target, not every Internet service. Missing history is not a successful probe or downtime. Rate averages are not billing-grade transferred-byte counters or per-client application accounting.
Can the controller send notifications?
An Owner can create sustained-condition alert rules and explicitly configure generic webhook delivery. Nothing is sent to a third party until delivery is configured and enabled. Rules cover device-offline and WAN latency/loss conditions; CPU-load rules are not included. This is not built-in Telegram-specific delivery, Web Push, or automatic network repair. See the Alerts guide for freshness, hold-window, cooldown, and retry boundaries.
Does restoring a backup replay notifications?
No. v0.1.8 portable restore pauses external alert delivery, cancels its pending outbox, and resets pending evaluation continuity. It preserves rules, incident history, cooldowns, and the encrypted destination without claiming recovery. An Owner must review the restored environment and explicitly re-enable delivery; cancelled history is not replayed. Router-write suppression remains a separate control. See Upgrade and roll back.
Does a movable topology map discover virtual machines?
No. A saved arrangement changes coordinates only. Measured, inferred, ambiguous, unknown, and expired evidence stay distinct. The map does not infer VM nesting, device manufacturers, or new cables from an icon or its location. SNMP, firmware execution, Web Push, Telegram-specific integration, full localization, and VM nesting remain pending, not completed parity features.
Where should I start?
Read Requirements, follow INSTALL.md, and adopt one non-critical router. For a failure, use Troubleshooting before changing the router manually.