539 lines
10 KiB
Markdown
539 lines
10 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
ubus call luci.bandwidth-manager status
|
|
```
|
|
|
|
#### List QoS Rules
|
|
|
|
```bash
|
|
ubus call luci.bandwidth-manager list_rules
|
|
```
|
|
|
|
#### Add QoS Rule
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
ubus call luci.bandwidth-manager delete_rule '{
|
|
"rule_id": "rule_1234567890"
|
|
}'
|
|
```
|
|
|
|
#### List Client Quotas
|
|
|
|
```bash
|
|
ubus call luci.bandwidth-manager list_quotas
|
|
```
|
|
|
|
#### Set Quota
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
ubus call luci.bandwidth-manager get_quota '{
|
|
"mac": "AA:BB:CC:DD:EE:FF"
|
|
}'
|
|
```
|
|
|
|
#### Reset Quota Counter
|
|
|
|
```bash
|
|
ubus call luci.bandwidth-manager reset_quota '{
|
|
"mac": "AA:BB:CC:DD:EE:FF"
|
|
}'
|
|
```
|
|
|
|
#### Get Real-time Usage
|
|
|
|
```bash
|
|
ubus call luci.bandwidth-manager get_usage_realtime
|
|
```
|
|
|
|
#### Get Usage History
|
|
|
|
```bash
|
|
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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"rule_id": "rule_1234567890",
|
|
"message": "Rule created successfully"
|
|
}
|
|
```
|
|
|
|
### delete_rule(rule_id)
|
|
|
|
Delete a QoS rule.
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Rule deleted successfully"
|
|
}
|
|
```
|
|
|
|
### list_quotas()
|
|
|
|
List all client quotas with current usage.
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"quota_id": "quota_1234567890",
|
|
"message": "Quota created successfully"
|
|
}
|
|
```
|
|
|
|
### reset_quota(mac)
|
|
|
|
Reset quota counter for a client.
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
tc qdisc show dev br-lan
|
|
```
|
|
|
|
Check iptables rules:
|
|
```bash
|
|
iptables -L BW_TRACKING -n -v
|
|
```
|
|
|
|
### Quota Tracking Not Accurate
|
|
|
|
Reset iptables counters:
|
|
```bash
|
|
iptables -Z BW_TRACKING
|
|
```
|
|
|
|
Check usage database:
|
|
```bash
|
|
cat /tmp/bandwidth_usage.db
|
|
```
|
|
|
|
### High CPU Usage
|
|
|
|
Reduce tracking frequency or use hardware flow offloading if available:
|
|
```bash
|
|
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
|