History

CyberMind-FR e67df835e2 fix: remove UCI dependencies from menu definitions Removes mandatory UCI config dependencies from dashboard modules to allow LuCI menus to display even when backend services are not installed. This fixes 'Permission denied' errors when accessing dashboards for services that haven't been installed yet (crowdsec, netdata, netifyd, etc.). Changes: - Remove uci dependency: crowdsec-dashboard, netdata-dashboard - Remove uci dependency: netifyd-dashboard, wireguard-dashboard - Remove uci dependency: client-guardian, media-flow - Remove uci dependency: network-modes, traffic-shaper Dashboards will now gracefully handle missing backend services and can guide users to install required packages. Related: SecuBox menu organization (v0.1.2-alpha)		2025-12-25 16:23:30 +01:00
..
htdocs/luci-static/resources	fix: resolve validation issues across all modules	2025-12-25 09:01:06 +01:00
root	fix: remove UCI dependencies from menu definitions	2025-12-25 16:23:30 +01:00
Makefile	fix: resolve validation issues across all modules	2025-12-25 09:01:06 +01:00
README.md	fix: resolve validation issues across all modules	2025-12-25 09:01:06 +01:00

README.md

Traffic Shaper - Advanced QoS Control

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:

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

Creating Traffic Classes

Go to Network → Traffic Shaper → Traffic Classes
Click Add to create a new class
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
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

Go to Network → Traffic Shaper → Classification Rules
Click Add to create a new rule
Configure:
- Traffic Class: Select destination class
- Match Type: Port, IP, DSCP, or Protocol
- Match Value: Value to match
- Enable: Activate the rule
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

Go to Network → Traffic Shaper → Presets
Review available presets and their configurations
Click Apply This Preset on your desired profile
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:

Root qdisc: CAKE (Common Applications Kept Enhanced)
Class hierarchy: HTB (Hierarchical Token Bucket) for bandwidth allocation
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

Verify CAKE module is loaded:
```
lsmod | grep sch_cake
```

Check TC configuration:

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

Verify interface name:
```
ip link show
```

Classes Not Appearing

Restart RPCD:
```
/etc/init.d/rpcd restart
```
Check UCI configuration:
```
uci show traffic-shaper
```

Verify class is enabled:

uci get traffic-shaper.<class_id>.enabled

Statistics Not Updating

Check TC statistics:
```
tc -s class show dev wan
```
Verify polling is active (check browser console)
Ensure classes are enabled and interface is correct

Permission Errors

Verify ACL file is installed:

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

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