wanctl Control Plane

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.

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 — Router, shaper, steering, and failover authority
• Switching & VLAN Fabric — Layer 2 transport boundaries
• Network Monitoring Intent — Evidence and failure questions