Skip to content
This repository was archived by the owner on May 16, 2026. It is now read-only.

v2.2.0: Internal Network QoS Control

Choose a tag to compare

View all tags
@01rabbit 01rabbit released this 07 Nov 13:08
· 55 commits to main since this release
v2.2.0
f843c4e

Release v2.2.0: Internal Network QoS Control

🎯 Overview

Version 2.2.0 introduces comprehensive Internal Network QoS (Quality of Service) Control for privilege-based traffic shaping and security enforcement within the LAN. This feature enables differentiated bandwidth allocation, MAC address verification, and ARP spoofing protection for trusted devices.

✨ Major Features

1. Mark-Based Traffic Classification

  • Premium (0x10): High-priority devices with guaranteed bandwidth
  • Standard (0x20): Normal priority for regular devices
  • Best Effort (0x30): Default class for unclassified traffic
  • Restricted (0x40): Limited bandwidth for suspicious/untrusted devices

2. Three Security Modes

  • none: Marking only, no enforcement (safe testing mode)
  • verify: Drop packets from privileged IPs with mismatched MAC addresses
  • lock: verify mode + static ARP entries to prevent spoofing

3. Dynamic Priority Adjustment

  • Score-based automatic class reassignment
  • Configurable thresholds and bias factors
  • Optional daemon (azazel_priorityd) for continuous evaluation

4. HTB Traffic Shaping

  • Hierarchical Token Bucket (HTB) implementation using tc
  • Per-class rate/ceil configuration via YAML
  • Idempotent initialization (safe to re-run)

🔧 New Components

Scripts

  • bin/azazel-traffic-init.sh: Initialize tc HTB classes and nftables infrastructure
  • bin/azazel-qos-apply.sh: Apply privilege-based rules from CSV with mode selection
  • bin/azazel-qos-menu.sh: Interactive TUI for privileged host management

Services

  • services/azazel_priorityd.py: Dynamic priority daemon with score-based logic
  • systemd/azazel-traffic-init.service: One-shot init service
  • systemd/azazel-qos-apply.service: One-shot apply service
  • systemd/azazel-priorityd.service: Long-running daemon service

Configuration

  • configs/network/privileged.csv: Authoritative list of premium hosts (IP, MAC, note)
  • configs/network/azazel.yaml: Extended with QoS config (marks, classes, thresholds)

Python Module

  • azazel_pi/core/network/internal_control.py: InternalControlManager for zone management

Documentation

  • docs/INTERNAL_NETWORK_CONTROL.md: Architecture and design decisions
  • docs/QOS_TESTING.md: Testing guide with DRY_RUN results

📋 Configuration Example

privileged.csv:

# IP,MAC,Note
172.16.0.10,aa:bb:cc:dd:ee:ff,Admin workstation
172.16.0.11,00:11:22:33:44:55,IoT controller

azazel.yaml (extended):

mark_map:
  premium: 0x10
  standard: 0x20
  best_effort: 0x30
  restricted: 0x40

classes:
  premium:
    rate: 10000kbit
    ceil: 10000kbit
  standard:
    rate: 5000kbit
    ceil: 8000kbit
  best_effort:
    rate: 2000kbit
    ceil: 5000kbit
  restricted:
    rate: 500kbit
    ceil: 1000kbit

thresholds:
  premium: 80
  standard: 50
  best_effort: 20

dynamic_bias:
  base: 100
  factor: 1.0

🚀 Usage

Manual Operation

# Initialize tc/nft infrastructure (one-time)
sudo bin/azazel-traffic-init.sh configs/network/azazel.yaml

# Apply privileged host rules (verify mode)
sudo MODE=verify bin/azazel-qos-apply.sh configs/network/privileged.csv

# Interactive management
sudo bin/azazel-qos-menu.sh

SystemD Integration

# Enable services
sudo systemctl enable azazel-traffic-init.service
sudo systemctl enable azazel-qos-apply.service
sudo systemctl enable azazel-priorityd.service  # optional

# Start services
sudo systemctl start azazel-traffic-init.service
sudo systemctl start azazel-qos-apply.service

DRY_RUN Mode (Safe Testing)

# Test command generation without execution (no root required)
DRY_RUN=1 bin/azazel-traffic-init.sh configs/network/azazel.yaml
DRY_RUN=1 MODE=verify bin/azazel-qos-apply.sh configs/network/privileged.csv
DRY_RUN=1 MODE=lock bin/azazel-qos-apply.sh configs/network/privileged.csv

🔒 Security Features

  • MAC Verification: Prevents ARP spoofing for privileged devices
  • Static ARP: Lock mode provides additional anti-spoofing protection
  • Gradual Rollout: Safe deployment path (none → verify → lock)
  • DRY_RUN Mode: Test configurations without network modification
  • Idempotent Design: All scripts safe to re-run

✅ Testing Performed

  • ✅ Syntax Validation: All scripts pass bash -n checks
  • ✅ Python Imports: All modules import successfully
  • ✅ Logic Verification: Score-to-class mapping tested and validated
  • ✅ DRY_RUN Mode: Command generation verified without network modification
    • traffic-init: tc qdisc/class/filter setup ✓
    • qos-apply (verify): nft marking + drop rules ✓
    • qos-apply (lock): + static ARP entries ✓
    • priorityd: Daemon startup and assignment output ✓

🔄 Backward Compatibility

  • All changes are additive; existing functionality unaffected
  • QoS features are opt-in via systemd service enablement
  • Config file extensions maintain backward compatibility

📚 Documentation

🔮 Next Steps

  • Real network testing in controlled maintenance window
  • Integration with existing threat scoring system
  • Performance benchmarking with realistic traffic loads
  • Grafana dashboard for QoS metrics visualization

📦 Installation

From Source

git clone https://github.com/01rabbit/Azazel-Pi.git
cd Azazel-Pi
git checkout v2.2.0
sudo scripts/install_azazel_complete.sh --start

Quick Update from v2.1.0

cd Azazel-Pi
git pull origin main
git checkout v2.2.0
# QoS features are opt-in, no automatic migration needed

🙏 Acknowledgments

This release focuses on internal network control capabilities, enabling fine-grained bandwidth management and security enforcement for LAN devices. The DRY_RUN mode ensures safe deployment and testing without risk to production networks.

Full Changelog: v2.1.0...v2.2.0

Assets 2
Loading