luci-app-trafficctl

Per-device traffic monitoring and control for OpenWrt routers. Monitor connections, limit bandwidth, shape traffic, block internet access, and manage WiFi MAC filtering -- all from a single LuCI page.

I built this because I wanted a reliable one-click way to cut my kids off the internet — and found that doing it properly on OpenWrt is surprisingly awkward. Most approaches either miss already-established connections (so the device stays online until the session times out on its own), or require navigating across several LuCI pages just to get something done.

Custom shell scripts solved the immediate problem. But once I had something working, I wanted to actually see what was happening on the network — who was online, how much traffic each device was generating, where they were connecting to. So I added a live traffic table.

That opened the door to more: which interface is each device on? What's the TCP state breakdown? What are the top destinations? One thing led to another, and the connection detail view followed.

A hard internet block also felt heavy-handed for everyday use — sometimes slowing a device down is better than cutting it off entirely. So I added rate limiting and traffic shaping via tc/HTB, with persistence across reboots.

After that, the focus shifted to making the whole thing convenient to live with: a recent-devices bar for one-click access, live sparkline graphs with a hover popup, a searchable device picker, configurable columns, activity logging.

The latest addition is Telegram — instant notifications when a new device joins the network, and the ability to block, unblock, or throttle any device directly from my phone without opening a browser.

I hope it turns out as useful for you as it has been for me.

• Screenshots
• Features
• System Requirements
• Compatibility
• Installation
• Quick Start
• Configuration
• Architecture
• Project Layout
• Documentation
• Contributing
• License

Dashboard — live speed graph	Block / Unblock Internet
Rate Limiting & Traffic Shaping	Interactive speed graph popup

More screenshots — light theme, settings, Telegram, activity log…

Overview — light theme	Per-device connections
WiFi blocked	Link / band column
Extended statistics (all devices)	Extended statistics (per device)
Group connections by service	Group connections by hostname
Searchable device picker	Unreachable device indicator
Settings walkthrough	Column toggles
Telegram Bot — configure & toggle	Telegram Bot settings
Logging & Persistence settings	Activity Log panel

• Real-time Per-device Monitoring -- View active connections per device with TCP/UDP counts, TCP state breakdown, destination IPs, and live bandwidth speed (sparkline graphs with rate limit overlay).
• Interactive Speed Graphs -- Hover any sparkline for a full-size popup graph with: download + upload dual lines, gradient area fill, min/max band, crosshair with precise values, rate limit line, nice-value Y axis (multiples of 100/500 Kbit/s). Full history from page load.
• Traffic Shaping (Queue) -- tc/HTB classes on the LAN bridge with fq_codel leaf qdiscs. Queues excess traffic instead of dropping, providing smoother throughput.
• Rate Limiting (Policer) -- nftables or iptables-based packet dropping when a device exceeds the configured rate. Instant enforcement, no queuing.
• Internet Blocking -- Layer 3 drop rules per device. Connections are killed immediately and counter stats are tracked.
• WiFi MAC Filtering -- Block any device from associating with WiFi via hostapd_cli deny ACL. Only the target client is deauthenticated -- no wifi reload, other clients stay connected. Works across all radio interfaces (2.4 GHz, 5 GHz, 6 GHz) automatically.
• Interface Detection -- Shows actual connection interface: WiFi band (2.4G/5G/6G) or LAN port name (lan2/lan3/lan4).
• Live Speed Polling -- Optional polling with configurable interval (default 2s); shows sparkline per device with spike filtering.
• Reverse DNS -- Optional hostname resolution for external destination IPs with in-memory cache (no repeated lookups).
• Searchable Device Picker -- Command palette (search by name, IP, or MAC) with recent devices quick-access bar stored in localStorage.
• Telegram Bot -- Optional bot for remote control: device list, block/unblock, rate limit, shape traffic, new device notifications. Runs on the router via long polling, no external server needed.
• New Device Detection -- Discovers new devices via three sources: ARP table, DHCP leases, Wi-Fi station list. Instant DHCP hotplug trigger for near-realtime alerts.
• Activity Logging -- Configurable logging of all actions (blocks, ratelimits, shapes, config changes) to a local file and/or syslog. Includes source IP, username, and trigger (LuCI/Telegram/CLI).
• Reboot Persistence -- Shaping, block, and rate-limit rules optionally survive reboot via hotplug restore. Configurable per UCI option persist_rules.

Runs on all architectures (no compiled code, pure shell + LuCI JavaScript).

CI-tested on 52 combinations — every push is verified against real OpenWrt rootfs containers:

Each test builds the .ipk, runs opkg install --force-depends inside the real OpenWrt rootfs container for that version/arch, then verifies all files are present and all scripts pass ash -n syntax check.

Which file do I need?

• Recommended: v1.6.5+ (earlier releases are broken — missing status.css, invalid APK format)
• OpenWrt 21.02 — 24.10 → download .ipk (opkg)
• OpenWrt 25.12+ and snapshot → download .apk (apk)

Each release includes multiple filenames for the same package:

The "stable URL" links below always download from the latest release — the filename stays constant across versions.

Option A — LuCI web UI:

1. Download luci-app-trafficctl.apk to your computer
2. In LuCI: System → Software → Upload Package...
3. Select the downloaded file and click OK

Option B — SSH (with signature verification):

# Add the signing key (one-time):
wget -O /etc/apk/keys/luci-app-trafficctl.pub https://raw.githubusercontent.com/YusDyr/luci-app-trafficctl/main/keys/apk-signing.pub
# Install:
cd /tmp && wget https://github.com/YusDyr/luci-app-trafficctl/releases/latest/download/luci-app-trafficctl.apk && apk add luci-app-trafficctl.apk
# If you get "modified conffile" on upgrade, add `--force-maintainer` to override

Option C — SSH (without key, quick install):

cd /tmp && wget https://github.com/YusDyr/luci-app-trafficctl/releases/latest/download/luci-app-trafficctl.apk && apk add --allow-untrusted luci-app-trafficctl.apk

Option A — LuCI web UI:

1. Download luci-app-trafficctl.ipk to your computer
2. In LuCI: System → Software → Upload Package...
3. Select the downloaded file and click OK

Option B — SSH (requires HTTPS support — libustream-wolfssl or libustream-openssl):

opkg install https://github.com/YusDyr/luci-app-trafficctl/releases/latest/download/luci-app-trafficctl.ipk

Option C — SSH from your machine:

ssh root@router 'opkg install https://github.com/YusDyr/luci-app-trafficctl/releases/latest/download/luci-app-trafficctl.ipk'

# Add to your feeds.conf (the package depends on luci, so make sure
# luci is also configured — it is by default in feeds.conf.default):
echo "src-git trafficctl https://github.com/YusDyr/luci-app-trafficctl.git" >> feeds.conf

# Update both feeds (luci must be updated before trafficctl is scanned):
./scripts/feeds update luci trafficctl
./scripts/feeds install -p trafficctl luci-app-trafficctl

# Enable and build:
echo 'CONFIG_PACKAGE_luci-app-trafficctl=m' >> .config
make defconfig
make package/luci-app-trafficctl/compile V=s

Copy the luci-app-trafficctl/root/ tree to the router's filesystem, then restart rpcd:

scp -r luci-app-trafficctl/root/* root@router:/
scp -r luci-app-trafficctl/htdocs/luci-static root@router:/www/
ssh root@router 'chmod +x /usr/local/bin/trafficctl-*.sh /usr/libexec/rpcd/luci.trafficctl && /etc/init.d/rpcd restart'

# Core (always required)
apk add conntrack luci-base rpcd

# For traffic shaping
apk add tc-full kmod-sched-core kmod-sched-htb

# For interface detection (WiFi band + LAN port)
apk add iw-full bridge-utils

# rpcd-mod-rrdns is included with rpcd (no extra install needed)

# For Telegram bot (optional)
apk add curl

# Core (always required)
opkg install conntrack luci-base rpcd

# For traffic shaping
opkg install tc-full kmod-sched-core kmod-sched-htb

# For interface detection (WiFi band + LAN port)
opkg install iw-full bridge-utils

# rpcd-mod-rrdns is included with rpcd (no extra install needed)

# For Telegram bot (optional)
opkg install curl

1. Install the package (see above).
2. Navigate to Status > Traffic Control in LuCI.
3. The summary table shows all active devices with connection counts, traffic, speed limits, and connection interface.
4. Use the search bar to find a device by name, IP, or MAC.
5. Select a device to see its per-connection detail table.
6. Use the action buttons to pause internet, block WiFi, or set a speed limit.

1. Create a bot via @BotFather and copy the token.
2. Send any message to your bot and find your chat ID via https://api.telegram.org/bot<TOKEN>/getUpdates.
3. In LuCI, expand Settings > Telegram Bot, enter token and chat ID, click Test, then Save.
4. In Telegram, send /devices to see the device list with action buttons.

Note: As of v1.6.5+, the runtime data directory is /etc/trafficctl/ (previously /etc/trafficmon/).

• Shaping rules are always saved to /etc/trafficctl/shapes.json and restored on boot.
• Block and rate-limit rules are optionally persistent when persist_rules is enabled in Settings > Logging & Persistence (saved to /etc/trafficctl/rules.json).
• On reboot, the hotplug script at /etc/hotplug.d/iface/99-trafficctl-shapes restores all saved rules (shapes, blocks, ratelimits) when the LAN interface comes up.

• All mutable actions are logged with timestamp, source IP, username, trigger (luci/telegram/cli), and target.
• Log file: /tmp/trafficctl/activity.log (volatile; survives until reboot). Path and max lines are configurable via UCI.
• Optionally duplicates to syslog (logger -t trafficctl) for remote log collection.
• Per-category toggles: blocks, ratelimits, shapes, telegram, config changes.

When a device is WiFi-blocked:

• Its MAC is added to the deny list on all wifi-iface sections via UCI.
• macfilter=deny is set on each interface.
• At runtime, hostapd_cli deny_acl ADD_MAC adds the MAC to the deny ACL and deauthenticate disconnects only that client. No wifi reload -- other clients stay connected.

flowchart LR
    A((LuCI\nBrowser)) -->|JSON-RPC| B[rpcd backend]
    T((Telegram)) -->|Bot API| TG[telegram bot]

    B --> C{Query or\nAction?}
    TG --> C

    C -->|query| D[/Monitoring/]
    C -->|action| E[/Control/]

    D --> F[(conntrack)]
    D --> G[(iw / brctl)]
    D --> N[(ARP / DHCP)]

    E --> H[Firewall\nabstraction]
    E --> I[tc / HTB]
    E --> J[hostapd]

    H --> K[(nftables)]
    H --> L[(iptables)]

    I --> M[(shapes.json)]
    H --> R[(rules.json)]
    M -.->|boot restore| I
    R -.->|boot restore| H

    E --> LOG[Activity Log]
    LOG --> S[(file)]
    LOG --> SL[(syslog)]

The frontend talks to a thin rpcd dispatcher over ubus. The Telegram bot provides parallel remote control via long polling. Backend shell scripts split into two groups: monitoring (read-only, pulls data from conntrack, ARP, DHCP leases, and wireless subsystems) and control (writes firewall rules, tc classes, or WiFi MAC filters). A firewall abstraction layer auto-detects nft vs iptables at runtime. All mutable actions are logged to a local file and optionally syslog. Rules optionally persist across reboots via hotplug scripts.

Contributions are welcome. Please:

1. Fork the repository and create a feature branch.
2. Test on at least one real OpenWrt device.
3. Ensure both nftables and iptables code paths work if your change touches firewall logic.
4. Keep the single-file JavaScript approach -- no bundlers, no npm, no transpilation.
5. Shell scripts must be POSIX sh compatible (BusyBox ash/dash).
6. All scripts emit JSON to stdout.

• JavaScript: ES5 syntax (LuCI compatibility), 'use strict', no external dependencies.
• Shell: POSIX /bin/sh, validate all IP input, output JSON only.

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Copyright 2024-2026 Denis Iusupov.