Network visibility and traffic policy engine for OpenWrt — from clients and applications to flows, destinations, and traffic control.
English · 简体中文
NetQmon is a self-hosted network observability and traffic policy platform built for OpenWrt. It gives you complete visibility into what is using your network, where traffic is going, and how that activity changes over time — while providing granular, application-aware traffic control and bandwidth shaping directly on the gateway.
A lightweight Agent runs on the gateway, leveraging TC eBPF for zero-overhead flow telemetry and wire-speed policy enforcement. The Controller handles high-performance storage, classification, real-time analytics, visual policy management, and simulation.
NetQmon combines deep network observability with application-aware traffic policies (rate limiting, blocking, and scheduling via eBPF & TC). It brings actionable traffic governance to home and edge networks alongside your existing firewall without turning your router into a heavy analytics appliance.
| Clients | Realtime upload/download, traffic history, IP/MAC/hostname correlation, and device identity signals. |
| Applications | Classify traffic by organization, application, category, domain, protocol, IP/ASN metadata, and bounded DPI signals. |
| Traffic Policies | Application- and client-aware policy engine: blocking, upload/download bandwidth shaping (TC/eBPF), and schedules. |
| Flows | Explore IPv4/IPv6 flows with source, destination, protocol, ports, bytes, and classification context. |
| Destinations | Understand where traffic goes with domain, country/region, ASN/ISP, and geographic views. |
| Realtime + history | Follow current activity and query historical ranges from the same interface. |
| Simulation & Tracking | Dry-run policy evaluation against sample traffic before deployment, with real-time 4-stage synchronization tracking. |
| OpenWrt-native | TC eBPF data plane, native procd service, UCI configuration, emergency CLI controls, and optional LuCI app. |
| Self-hosted Controller | Docker deployment with SQLite by default and optional ClickHouse for larger datasets. |
flowchart LR
subgraph Gateway["OpenWrt Gateway"]
direction TB
BPF["TC eBPF (Flow Telemetry & Fast Drop)"]
TC["Linux TC / Qdisc (Bandwidth Shaping)"]
Agent["NetQmon Agent"]
BPF <--> Agent
Agent --> TC
end
Agent -->|" Flow / DNS / Device Telemetry "| Collector["Collector & Policy Engine"]
Collector -->|" Policy Push (WebSocket) "| Agent
Collector --> Classifier["Classifier"]
Collector --> Storage[("SQLite / ClickHouse")]
Collector <--> UI["Next.js Web UI (Dashboard & Policies)"]
Cloud["NetQmon Cloud (Rule & update services)"] -. " optional " .-> Classifier
The Agent stays focused on capture, lightweight enrichment, and kernel-level policy enforcement. Heavy computational work — application classification, policy compilation and evaluation, aggregation, historical queries, and visualization — belongs on the Controller.
NetQmon includes a declarative traffic policy engine that bridges high-level application classification with kernel-level traffic control:
-
Targeted Selection:
- Clients: Apply rules to specific devices by MAC address, IP, or hostname, or apply global gateway-wide limits.
- Applications & Categories: Target identified services (e.g., video streaming, gaming, P2P/downloads, social media) or entire application categories.
- Confidence Threshold: Set a minimum application identification confidence (
min_application_confidence) to prevent false positives on early or ambiguous flows.
-
Granular Actions:
- Block: Fast-path packet dropping via TC eBPF maps (
flow_verdict_mapand dynamicendpoint_blockswith DNS lease correlation). Drops unwanted traffic at wire speed with minimal gateway CPU usage. - Limit (Traffic Shaping): Independent upload and download bandwidth caps (in bps/Mbps) implemented through Linux Traffic Control (
tc/ HTB / CAKE / FQ-CoDel / IFB). Supports both per-client total bandwidth limits and fine-grained per-application shaping. - Allow / Priority: Whitelist mission-critical traffic or assign policy priorities (0–1000) to override broader restrictions.
- Block: Fast-path packet dropping via TC eBPF maps (
-
Time Windows & Scheduling:
- Define timezone-aware schedules with recurring active windows (e.g., limit streaming bandwidth during work hours 09:00–18:00, block gaming on school nights).
-
Visual Management & Simulation:
- Dual Editor: Seamlessly switch between the intuitive visual form editor and the declarative YAML specification editor with real-time validation.
- Policy Verdict Preview: Interactive dry-run simulator to test and verify how policies evaluate a sample client MAC, application, and category before applying changes to the network.
-
A0D5
4-Stage Deployment Tracking: Full visibility into the sync lifecycle:
Desired(Controller) →Delivered(WebSocket) →Acknowledged(Agent received) →Applied(Active on kernel/interfaces), with transparent reporting of degraded or unsupported states.
-
Reliability & Fail-Safe Protection:
- Hardware & Link Probing: Automatically negotiates physical interface speeds (including multi-gigabit links) or accepts explicit interface capacity overrides.
- Zero-Disruption Fallback: Non-disruptive rollbacks and capability checks ensure your router never hangs.
- Local Emergency Unlock: If a misconfiguration occurs, run
netqmon-agent policies unlockdirectly on the router CLI to instantly tear down active policy rules and qdiscs without needing Controller connectivity.
git clone https://github.com/jarvis2f/netqmon.git
cd netqmon
docker compose up -d- Open
http://localhost:3000after the Controller becomes healthy to complete the initial administrator setup. - Navigate to Settings and click Update GeoIP & ASN Database to enable geographic location and ASN enrichment for destination traffic.
- Note or configure the Enrollment Token (default or via environment variable) to authenticate your OpenWrt Agent.
SQLite is the default storage backend. ClickHouse can be enabled when you need higher ingest volume or longer retention. See Controller Configuration for environment variables, ports, and storage options.
NetQmon currently targets OpenWrt 24.10+ on x86_64 and aarch64. Linux 6.6+ is recommended; kernels 5.15+ may work when the required eBPF/TC capabilities are available. See the Platform Support Matrix for details.
Install the required kernel modules first:
opkg update
opkg install kmod-sched-core kmod-sched-bpfThen install the NetQmon Agent package and, if wanted, the LuCI app from a release. Configure the Controller address and verify the router with:
netqmon-agent doctorCheck policy synchronization status or manage emergency unlock directly on the router:
netqmon-agent policies status
netqmon-agent policies unlock # Instantly remove all NetQmon policy rules and qdiscs
netqmon-agent policies resume # Restore policy enforcementSee Agent CLI Reference for command-line options, policy management, diagnostics, UCI configuration, and environment variables.
NetQmon Community and Pro use the same monitoring engine, policy framework, and web interface. The difference is the classification data available to them.
| Edition | Classification data |
|---|---|
| Community | Community rule dataset suitable for common applications and services. |
| Pro | A larger, continuously maintained dataset delivered through NetQmon Cloud for broader application and organization coverage. |
Pro extends recognition coverage; it does not unlock a different capture engine or a separate set of monitoring features.
More information is available at netqmon.com.
NetQmon is designed for traffic metadata and network observability, not content inspection. Protocol identification may use small, bounded samples from the beginning of a flow when needed. NetQmon does not decrypt TLS.
The standard deployment keeps the Controller and traffic database on infrastructure you operate.
See Privacy for the implementation details and probe limits.
bpf/ TC eBPF data plane & fast-path policy enforcement maps
crates/agent/ OpenWrt userspace Agent (telemetry & policy executor)
crates/collector/ Ingestion, DPI, policy engine, realtime and query pipeline
crates/classifier-client/ Classification client
crates/classifier-manager/ Rule lifecycle and updates
crates/storage/ SQLite / ClickHouse storage
apps/controller-ui/ Next.js Controller UI & Policy dashboard
packaging/openwrt/ OpenWrt packages and LuCI app
deploy/docker/ Controller container build
docs/ Architecture, deployment, CLI and protocol docs
Backend:
cargo test --workspaceController UI:
pnpm install
pnpm lint
pnpm typecheck
pnpm build
pnpm e2eNetQmon is licensed under the Apache License 2.0.