secubox-openwrt/luci-app-traffic-shaper

Traffic Shaper - Advanced QoS Control

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

LuCI application for advanced traffic shaping and Quality of Service (QoS) management using Linux Traffic Control (TC) and CAKE qdisc.

Features

• Traffic Class Management: Create and manage bandwidth allocation classes with guaranteed (rate) and maximum (ceil) limits
• Priority-Based Scheduling: 8-level priority system for fine-grained traffic prioritization
• Classification Rules: Flexible rule system to classify traffic by:
  • Port numbers (source/destination)
  • IP addresses (source/destination)
  • DSCP markings
  • Protocol type
• Real-Time Statistics: Monitor per-class packet counts, byte counts, and drop statistics
• Quick Presets: One-click application of optimized configurations:
  • Gaming & Low-Latency
  • Video Streaming
  • Work From Home
  • Balanced (Default)
• Visual Dashboard: Traffic flow diagram with priority color coding
• Multi-Interface Support: Configure QoS on WAN, LAN, or any network interface

Installation

opkg update
opkg install luci-app-traffic-shaper
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart

Dependencies

• luci-base: LuCI web interface framework
• rpcd: RPC daemon for backend communication
• tc: Linux traffic control utility
• kmod-sched-core: Kernel traffic scheduling modules
• kmod-sched-cake: CAKE qdisc kernel module

Usage

Access the Interface

Navigate to: Network → Traffic Shaper

The interface provides 5 main views:

1. Overview: Dashboard with status cards and traffic flow visualization
2. Traffic Classes: CRUD interface for bandwidth classes
3. Classification Rules: CRUD interface for traffic matching rules
4. Statistics: Real-time statistics for all traffic classes
5. Presets: Quick-apply optimized configurations

Creating Traffic Classes

1. Go to Network → Traffic Shaper → Traffic Classes
2. Click Add to create a new class
3. Configure:
   • Name: Descriptive name (e.g., "Video Streaming")
   • Priority: 1 (highest) to 8 (lowest)
   • Guaranteed Rate: Minimum bandwidth (e.g., "5mbit")
   • Maximum Rate (Ceil): Maximum allowed bandwidth (e.g., "50mbit")
   • Interface: Network interface (wan, lan, etc.)
   • Enable: Activate the class
4. Click Save & Apply

Priority Guidelines

• Priority 1-2: Critical traffic (VoIP, gaming, real-time applications)
• Priority 3-4: Important traffic (video streaming, VPN)
• Priority 5-6: Normal traffic (web browsing, email)
• Priority 7-8: Bulk traffic (downloads, backups)

Creating Classification Rules

1. Go to Network → Traffic Shaper → Classification Rules
2. Click Add to create a new rule
3. Configure:
   • Traffic Class: Select destination class
   • Match Type: Port, IP, DSCP, or Protocol
   • Match Value: Value to match
   • Enable: Activate the rule
4. Click Save & Apply

Example Rules

Match Type	Match Value	Description
Destination Port	80,443	HTTP/HTTPS web traffic
Destination Port	22	SSH connections
Destination Port	53	DNS queries
Source IP	192.168.1.0/24	All traffic from LAN subnet
Destination IP	8.8.8.8	Traffic to Google DNS
DSCP	EF	Expedited Forwarding (VoIP)
Protocol	udp	All UDP traffic

Using Presets

1. Go to Network → Traffic Shaper → Presets
2. Review available presets and their configurations
3. Click Apply This Preset on your desired profile
4. Confirm the action (this will replace existing configuration)

Configuration

UCI Configuration

Configuration is stored in /etc/config/traffic-shaper:

config class 'gaming'
	option name 'Gaming Traffic'
	option priority '1'
	option rate '10mbit'
	option ceil '50mbit'
	option interface 'wan'
	option enabled '1'

config rule 'gaming_ports'
	option class 'gaming'
	option match_type 'dport'
	option match_value '3074,27015,25565'
	option enabled '1'

Traffic Class Options

• name: Display name for the class
• priority: Priority level (1-8)
• rate: Guaranteed minimum bandwidth (format: <number>[kmg]bit)
• ceil: Maximum allowed bandwidth (format: <number>[kmg]bit)
• interface: Network interface name
• enabled: Enable/disable the class (0/1)

Classification Rule Options

• class: Traffic class ID (UCI section name)
• match_type: Type of matching (dport, sport, dst, src, dscp, protocol)
• match_value: Value to match against
• enabled: Enable/disable the rule (0/1)

Backend API

The RPCD backend (luci.traffic-shaper) provides these methods:

Status Methods

• status(): Get current QoS system status
• list_classes(): List all traffic classes
• list_rules(): List all classification rules
• get_stats(): Get per-class statistics from TC

Management Methods

• add_class(name, priority, rate, ceil, interface): Create new class
• update_class(id, name, priority, rate, ceil, interface, enabled): Update class
• delete_class(id): Delete class
• add_rule(class, match_type, match_value): Create classification rule
• delete_rule(id): Delete rule

Preset Methods

• list_presets(): Get available presets
• apply_preset(preset_id): Apply preset configuration

Technical Details

Traffic Control Implementation

The module uses Linux Traffic Control (TC) with the following hierarchy:

1. Root qdisc: CAKE (Common Applications Kept Enhanced)
2. Class hierarchy: HTB (Hierarchical Token Bucket) for bandwidth allocation
3. Filters: U32 filters for traffic classification based on rules

CAKE Features

• Smart queuing: Automatically manages queue sizes
• Flow isolation: Prevents single flows from monopolizing bandwidth
• Latency reduction: Minimizes bufferbloat
• Per-host fairness: Ensures fair bandwidth distribution

Statistics Collection

Statistics are collected using tc -s class show and parsed to provide:

• Packet counts per class
• Byte counts per class
• Drop counts (packets dropped due to rate limiting)

Data is refreshed every 5 seconds in the Statistics view.

Architecture

Directory Structure

luci-app-traffic-shaper/
├── Makefile                              # OpenWrt package definition
├── README.md                             # This file
├── htdocs/luci-static/resources/
│   ├── view/traffic-shaper/              # JavaScript views
│   │   ├── overview.js                   # Dashboard view
│   │   ├── classes.js                    # Class management
│   │   ├── rules.js                      # Rule management
│   │   ├── stats.js                      # Statistics view
│   │   └── presets.js                    # Preset selection
│   └── traffic-shaper/
│       ├── api.js                        # RPC API client
│       └── dashboard.css                 # UI styles
└── root/
    ├── etc/config/
    │   └── traffic-shaper                # UCI configuration
    └── usr/
        ├── libexec/rpcd/
        │   └── luci.traffic-shaper       # RPCD backend
        └── share/
            ├── luci/menu.d/              # Menu definition
            │   └── luci-app-traffic-shaper.json
            └── rpcd/acl.d/               # ACL permissions
                └── luci-app-traffic-shaper.json

Frontend Components

• Views: LuCI views using form.Map and custom DOM rendering
• API Client: Wrapper for RPC calls with utility functions
• Polling: Auto-refresh for statistics (5-second interval)
• Styling: Custom CSS with priority color coding

Backend Components

• RPCD Script: Shell script using jshn for JSON handling
• UCI Integration: Configuration stored in UCI format
• TC Integration: Direct TC commands for qdisc/class/filter management

Troubleshooting

Traffic Shaping Not Working

1. Verify CAKE module is loaded:

   lsmod | grep sch_cake
   

2. Check TC configuration:

   tc qdisc show
   tc class show dev wan
   tc filter show dev wan
   

3. Verify interface name:

   ip link show
   

Classes Not Appearing

1. Restart RPCD:

   /etc/init.d/rpcd restart
   

2. Check UCI configuration:

   uci show traffic-shaper
   

3. Verify class is enabled:

   uci get traffic-shaper.<class_id>.enabled
   

Statistics Not Updating

1. Check TC statistics:

   tc -s class show dev wan
   

2. Verify polling is active (check browser console)

3. Ensure classes are enabled and interface is correct

Permission Errors

1. Verify ACL file is installed:

   ls -la /usr/share/rpcd/acl.d/luci-app-traffic-shaper.json
   

2. Check user permissions:

   ubus -v list luci.traffic-shaper
   

Examples

Example 1: Home Office Setup

Classes:

• Video Calls: Priority 1, 8mbit guaranteed, 50mbit max
• VPN Traffic: Priority 2, 10mbit guaranteed, 60mbit max
• Web Browsing: Priority 4, 5mbit guaranteed, 40mbit max

Rules:

• Zoom ports (8801-8810) → Video Calls
• Port 443 with VPN IP range → VPN Traffic
• Ports 80,443 → Web Browsing

Example 2: Gaming + Streaming

Classes:

• Gaming: Priority 1, 5mbit guaranteed, 40mbit max
• Streaming: Priority 3, 15mbit guaranteed, 70mbit max
• Downloads: Priority 7, 2mbit guaranteed, 30mbit max

Rules:

• Gaming ports (3074, 27015, etc.) → Gaming
• Port 443 to Netflix/YouTube IPs → Streaming
• Port 80 → Downloads

Example 3: Multi-User Household

Use the Balanced preset or create custom classes:

• High Priority: 10mbit → 60mbit (Priority 2)
• Normal: 15mbit → 80mbit (Priority 5)
• Bulk: 5mbit → 50mbit (Priority 7)

Performance Considerations

• CPU Usage: TC processing uses minimal CPU on modern routers
• Memory: Each class uses ~1-2KB of kernel memory
• Latency: CAKE significantly reduces latency for interactive traffic
• Throughput: Minimal impact on total throughput (<1% overhead)

License

Apache License 2.0

Maintainer

SecuBox Project secubox@example.com

Version

1.0.0

See Also

• Linux TC Documentation
• CAKE qdisc
• OpenWrt Traffic Shaping
• LuCI Development Guide