# wanctl Control Plane > Adaptive CAKE control, external rate-controller integration, bounded WAN steering, and safety boundaries. Status: active · Kind: intent · Last verified: 2026-07-20 · Date: 2025-12-15 This document describes the control boundaries around adaptive WAN shaping and optional traffic steering. `wanctl` improves latency under changing link conditions. It does not replace static security policy, baseline routing, or operator authority. > Design principles: see **[Lab Philosophy](/homelab/philosophy)**. --- ## Purpose The control plane is designed to: - keep latency predictable while a WAN is busy - adapt CAKE rates within configured limits - combine multiple congestion signals instead of trusting one noisy metric - expose decisions and retained state for inspection - preserve a stable network when measurements or automation fail Adaptive shaping is the primary function. Routing changes are optional, separately bounded behavior. --- ## Two Rate-Control Modes The architecture supports two service models. ### Native Controller In native mode, one controller instance per WAN: - measures latency and queue behavior - fuses measurement signals into a congestion state - selects bounded CAKE rates through the configured backend - persists state and publishes health and metrics - provides the state consumed by optional steering This is the portable default and uses the same control logic across link types; link-specific behavior comes from configuration rather than code branches. ### External Rate Controller In external mode, an upstream CAKE autorate process owns reflector measurement and rate decisions. A state bridge then: - translates the external controller's output into the wanctl state model - supplements measurements needed by the shared contract - updates the same durable metrics and health representation - supplies compatible state to steering and operator tools External mode changes who owns rate decisions, not the state and observability contract. Native and external controllers are mutually exclusive for a given WAN so two writers cannot fight over the same queue. --- ## Control Inputs and Outputs The controller evaluates a bounded set of signals, including: - latency relative to an established baseline - independent measurement quality and disagreement - packet loss and outlier behavior - CAKE drops and queue depth - current load and configured rate bounds It produces: - a congestion state with hysteresis - bounded upload and download rates - persisted state for restart continuity - structured logs, health, and time-series metrics Missing or low-confidence inputs reduce authority. They do not justify an unbounded rate or route change. --- ## Steering Is a Separate Control Loop Queue control asks how quickly packets should leave a congested link. Steering asks which WAN a new connection should use. Those are separate decisions. Optional steering: - consumes the same per-WAN health state in either rate-control mode - applies only to explicitly eligible new connections - preserves established connection path and NAT affinity - leaves bulk and forced-path policy independent of queue class - uses hysteresis and bounded state transitions to avoid flapping A high-priority queue class does not automatically grant permission to move a connection to another WAN. --- ## Route-Ownership Boundary Whole-route failover remains distinct from congestion steering. Active route mutation is guarded while another router-side mechanism owns default-route failover. Observation and dry-run surfaces may record intended actions, but they do not implicitly authorize route changes. Any future ownership transfer requires: - one unambiguous active owner - reconciliation with current router state - visible guard and circuit-breaker status - a retained rollback snapshot - an attended, bounded canary Degraded congestion alone must not move the entire network onto a lower-capacity alternate path. --- ## Explicit Non-Authority The control plane does not own: - firewall or NAT policy - VLAN definitions or inter-zone authorization - addressing or DNS policy - switching or wireless configuration - the router's identity-aware QoS classification contract Those remain static, separately reviewed boundaries. --- ## Observability Contract Operators and monitoring should be able to determine: - which rate-control mode owns each WAN - whether measurements are fresh and trustworthy - current congestion state and bounded rates - the reason for the latest state transition - whether steering is active and which new flows are eligible - route-owner, guard, reconciliation, circuit-breaker, and rollback readiness - whether retained state was recovered after restart Native and external modes intentionally expose compatible state, health, and metrics so changing the rate owner does not blind the surrounding system. --- ## Safety and Failure Behavior The system favors stable degradation over aggressive automation: - rate changes stay inside configured floors and ceilings - only one process may own a WAN's rate decisions - hysteresis and cooldowns limit oscillation - malformed, stale, or low-confidence measurements reduce control authority - persisted state avoids an unsafe cold restart - steering affects eligible new connections, not established flows - guarded route mutation fails closed when ownership is ambiguous - manual disable and rollback remain available without redesigning static policy When a still-powered inline shaper or controller fails, a watchdog may bypass the bridge and preserve raw connectivity without CAKE. That is a degraded state, not successful shaping. Internal powered bypass does not cover complete host power loss. --- ## Design Invariants - Adaptive shaping remains useful without steering. - Steering remains useful without route ownership. - External integration preserves the public state contract. - No WAN has two rate writers. - Dynamic behavior is bounded, observable, and reversible. - Live rollout or route mutation requires separate operator approval. --- ## Related Documentation - [Edge & Traffic Policy](/homelab/network/edge-and-traffic-policy) — Router, shaper, steering, and failover authority - [Switching & VLAN Fabric](/homelab/network/switching-and-vlan-fabric) — Layer 2 transport boundaries - [Network Monitoring Intent](/homelab/network/monitoring-and-observability) — Evidence and failure questions