secubox-openwrt/luci-app-bandwidth-manager/README.md

Bandwidth Manager - QoS & Traffic Control

Version: 0.4.0
Last Updated: 2025-12-28
Status: Active

Advanced bandwidth management for OpenWrt with QoS rules, client quotas, and SQM/CAKE integration.

Features

QoS Traffic Shaping

• Rule-based traffic control by application, port, IP, or MAC
• Per-rule download/upload limits
• 8-level priority system (1=highest, 8=lowest)
• Time-based scheduling support
• Real-time rule enable/disable

Client Quotas

• Monthly data quotas per MAC address
• Usage tracking with iptables counters
• Configurable actions: throttle, block, or notify
• Automatic monthly reset (configurable day)
• Real-time quota usage monitoring

SQM/CAKE Integration

• Smart Queue Management with CAKE qdisc
• Automatic bandwidth shaping
• NAT-aware configuration
• Link overhead compensation (Ethernet, PPPoE, VLAN)
• Alternative FQ_CoDel and HTB support

Real-time Monitoring

• Live client bandwidth usage (auto-refresh every 5s)
• Per-client RX/TX statistics
• Quota progress visualization
• Historical usage tracking

Installation

opkg update
opkg install luci-app-bandwidth-manager
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart

Dependencies

• tc: Traffic control utility
• kmod-sched-core: Kernel traffic scheduler
• kmod-sched-cake: CAKE qdisc module
• kmod-ifb: Intermediate Functional Block device
• sqm-scripts: SQM scripts
• iptables: For traffic tracking
• iptables-mod-conntrack-extra: Connection tracking extensions

Configuration

UCI Configuration

Edit /etc/config/bandwidth:

config global 'global'
	option enabled '1'
	option interface 'br-lan'
	option sqm_enabled '1'

config sqm 'sqm'
	option download_speed '100000'    # kbit/s
	option upload_speed '50000'       # kbit/s
	option qdisc 'cake'
	option nat '1'
	option overhead '22'              # PPPoE overhead

config rule 'rule_youtube'
	option name 'Limit YouTube'
	option type 'application'
	option target 'youtube'
	option limit_down '5000'          # kbit/s
	option limit_up '1000'            # kbit/s
	option priority '6'
	option enabled '1'

config quota 'quota_phone'
	option mac 'AA:BB:CC:DD:EE:FF'
	option name 'iPhone Jean'
	option limit_mb '10240'           # 10 GB
	option action 'throttle'
	option reset_day '1'
	option enabled '1'

Configuration Options

Global Section

• enabled: Enable/disable bandwidth manager
• interface: Network interface to manage (default: br-lan)
• sqm_enabled: Enable SQM/CAKE

SQM Section

• download_speed: Download speed in kbit/s
• upload_speed: Upload speed in kbit/s
• qdisc: Queue discipline (cake, fq_codel, htb)
• nat: NAT mode (1=enabled, 0=disabled)
• overhead: Link overhead in bytes (0, 18, 22, 40)

Rule Section

• name: Rule name
• type: Rule type (application, port, ip, mac)
• target: Target value (app name, port number, IP, or MAC)
• limit_down: Download limit in kbit/s (0=unlimited)
• limit_up: Upload limit in kbit/s (0=unlimited)
• priority: Priority level (1-8)
• schedule: Optional time schedule (e.g., "Mon-Fri 08:00-18:00")
• enabled: Enable/disable rule

Quota Section

• mac: Client MAC address
• name: Friendly name
• limit_mb: Monthly limit in MB
• action: Action when exceeded (throttle, block, notify)
• reset_day: Day of month to reset (1-28)
• enabled: Enable/disable quota

Usage

Web Interface

Navigate to Network → Bandwidth Manager in LuCI.

Overview Tab

• System status (QoS active, interface, SQM)
• Traffic statistics (RX/TX bytes and packets)
• Active rules summary
• Client quotas with progress bars

QoS Rules Tab

• Create/edit/delete traffic shaping rules
• Configure type, target, limits, and priority
• Enable/disable rules individually
• Set time-based schedules

Client Quotas Tab

• Manage monthly data quotas per MAC
• Set limits and actions
• Reset quota counters
• View current usage

Real-time Usage Tab

• Live bandwidth usage per client
• Auto-refresh every 5 seconds
• Download/upload breakdown
• Quota progress for monitored clients

Settings Tab

• Global enable/disable
• Interface selection
• SQM/CAKE configuration
• Traffic tracking settings
• Alert configuration

Command Line

Get Status

ubus call luci.bandwidth-manager status

List QoS Rules

ubus call luci.bandwidth-manager list_rules

Add QoS Rule

ubus call luci.bandwidth-manager add_rule '{
  "name": "Limit Torrent",
  "type": "port",
  "target": "6881-6889",
  "limit_down": 3000,
  "limit_up": 500,
  "priority": 7
}'

Delete Rule

ubus call luci.bandwidth-manager delete_rule '{
  "rule_id": "rule_1234567890"
}'

List Client Quotas

ubus call luci.bandwidth-manager list_quotas

Set Quota

ubus call luci.bandwidth-manager set_quota '{
  "mac": "AA:BB:CC:DD:EE:FF",
  "name": "iPhone John",
  "limit_mb": 10240,
  "action": "throttle",
  "reset_day": 1
}'

Get Quota Details

ubus call luci.bandwidth-manager get_quota '{
  "mac": "AA:BB:CC:DD:EE:FF"
}'

Reset Quota Counter

ubus call luci.bandwidth-manager reset_quota '{
  "mac": "AA:BB:CC:DD:EE:FF"
}'

Get Real-time Usage

ubus call luci.bandwidth-manager get_usage_realtime

Get Usage History

ubus call luci.bandwidth-manager get_usage_history '{
  "timeframe": "24h",
  "mac": "AA:BB:CC:DD:EE:FF"
}'

Timeframe options: 1h, 6h, 24h, 7d, 30d

ubus API Reference

status()

Get system status and global statistics.

Returns:

{
  "enabled": true,
  "interface": "br-lan",
  "sqm_enabled": true,
  "qos_active": true,
  "stats": {
    "rx_bytes": 1234567890,
    "tx_bytes": 987654321,
    "rx_packets": 1234567,
    "tx_packets": 987654
  },
  "rule_count": 5,
  "quota_count": 3
}

list_rules()

List all QoS rules.

Returns:

{
  "rules": [
    {
      "id": "rule_youtube",
      "name": "Limit YouTube",
      "type": "application",
      "target": "youtube",
      "limit_down": 5000,
      "limit_up": 1000,
      "priority": 6,
      "enabled": true,
      "schedule": ""
    }
  ]
}

add_rule(name, type, target, limit_down, limit_up, priority)

Add a new QoS rule.

Returns:

{
  "success": true,
  "rule_id": "rule_1234567890",
  "message": "Rule created successfully"
}

delete_rule(rule_id)

Delete a QoS rule.

Returns:

{
  "success": true,
  "message": "Rule deleted successfully"
}

list_quotas()

List all client quotas with current usage.

Returns:

{
  "quotas": [
    {
      "id": "quota_phone",
      "mac": "AA:BB:CC:DD:EE:FF",
      "name": "iPhone Jean",
      "limit_mb": 10240,
      "used_mb": 7850,
      "percent": 76,
      "action": "throttle",
      "reset_day": 1,
      "enabled": true
    }
  ]
}

get_quota(mac)

Get detailed quota information for a specific MAC.

Returns:

{
  "success": true,
  "quota_id": "quota_phone",
  "mac": "AA:BB:CC:DD:EE:FF",
  "name": "iPhone Jean",
  "limit_mb": 10240,
  "used_mb": 7850,
  "remaining_mb": 2390,
  "percent": 76,
  "action": "throttle",
  "reset_day": 1
}

set_quota(mac, name, limit_mb, action, reset_day)

Create or update a client quota.

Returns:

{
  "success": true,
  "quota_id": "quota_1234567890",
  "message": "Quota created successfully"
}

reset_quota(mac)

Reset quota counter for a client.

Returns:

{
  "success": true,
  "message": "Quota counter reset for AA:BB:CC:DD:EE:FF"
}

get_usage_realtime()

Get real-time bandwidth usage for all active clients.

Returns:

{
  "clients": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "ip": "192.168.1.100",
      "hostname": "iPhone",
      "rx_bytes": 1234567,
      "tx_bytes": 987654,
      "has_quota": true,
      "limit_mb": 10240,
      "used_mb": 7850
    }
  ]
}

get_usage_history(timeframe, mac)

Get historical usage data.

Parameters:

• timeframe: "1h", "6h", "24h", "7d", "30d"
• mac: MAC address (optional, empty for all clients)

Returns:

{
  "history": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "timestamp": 1640000000,
      "rx_bytes": 1234567,
      "tx_bytes": 987654
    }
  ]
}

Traffic Tracking

Bandwidth Manager uses iptables for per-client traffic accounting:

# Create tracking chain
iptables -N BW_TRACKING

# Add rules for each MAC
iptables -A BW_TRACKING -m mac --mac-source AA:BB:CC:DD:EE:FF
iptables -A BW_TRACKING -m mac --mac-source BB:CC:DD:EE:FF:00

# Insert into FORWARD chain
iptables -I FORWARD -j BW_TRACKING

# View counters
iptables -L BW_TRACKING -n -v -x

Usage data is stored in /tmp/bandwidth_usage.db in pipe-delimited format:

MAC|Timestamp|RX_Bytes|TX_Bytes

QoS Implementation

CAKE (Recommended)

tc qdisc add dev br-lan root cake bandwidth 100000kbit

Benefits:

• Active Queue Management (AQM)
• Flow-based fair queuing
• NAT-aware
• Low latency

HTB (Manual Control)

tc qdisc add dev br-lan root handle 1: htb default 10
tc class add dev br-lan parent 1: classid 1:1 htb rate 100mbit
tc class add dev br-lan parent 1:1 classid 1:10 htb rate 50mbit ceil 100mbit prio 5

Troubleshooting

QoS Not Working

Check if QoS is active:

tc qdisc show dev br-lan

Check iptables rules:

iptables -L BW_TRACKING -n -v

Quota Tracking Not Accurate

Reset iptables counters:

iptables -Z BW_TRACKING

Check usage database:

cat /tmp/bandwidth_usage.db

High CPU Usage

Reduce tracking frequency or use hardware flow offloading if available:

echo 1 > /sys/class/net/br-lan/offload/tx_offload

Best Practices

1. Set Realistic Limits: Configure download/upload speeds to 85-95% of your actual connection speed
2. Use CAKE: Prefer CAKE qdisc for best performance and lowest latency
3. Monitor First: Use real-time usage view to understand traffic patterns before setting quotas
4. Regular Resets: Configure monthly resets on quota day 1 to align with ISP billing
5. Priority Wisely: Reserve priority 1-2 for VoIP/gaming, use 5 (normal) for most traffic

Security Considerations

• MAC addresses can be spoofed - use in conjunction with other security measures
• Quota tracking requires iptables access - secure your router
• Alert emails may contain sensitive information - use encrypted connections
• Traffic shaping rules are visible to network administrator only

License

Apache-2.0

Maintainer

SecuBox Project support@secubox.com

Version

1.0.0