claudetools/clients/cascades-tucson/docs/network/phase1-voice-qos-design.md

Cascades — Phase 1: Voice QoS Design (VLAN 30)

• Created: 2026-06-18 (Howard-Home / claude-main). Part of network-optimization-master-plan.md Phase 1.
• Status: DESIGN — for review, then build (Howard drives pfSense GUI). Nothing applied.
• Risk: LOW — additive, voice-only prioritization; rollback = disable the shaper. Main caution: size the shaper bandwidth correctly (a wrong value can throttle throughput) → test before/after.

Objective

Guarantee voice quality under load by prioritizing VLAN 30 traffic end-to-end. The phones register to a CLOUD PBX (Vertical) over the internet, so the bottleneck that breaks calls is WAN upload saturation (someone uploading / cloud backup / OneDrive sync fills the uplink → voice RTP queues → jitter, dropped audio). QoS keeps voice ahead of bulk data on the WAN.

The big advantage of the VLAN move

All voice is now one subnet: 10.0.30.0/24. So QoS can match all voice by source subnet — no need to guess SIP/RTP port ranges per PBX. This is the cleanest, most robust match criterion and it only became possible because we isolated voice onto VLAN 30.

Current state (verified 2026-06-18)

• No traffic shaper / limiter configured on pfSense (clean build).
• Dual-WAN: WAN1 igc0 (Cox Fiber, primary, 1G link), WAN2 igc3 (Cox Coax, 2.5G link); WAN_Group failover (downlosslatency). Shaping must be applied on both WAN interfaces.
• pfSense Plus 25.07 (ALTQ shaper + dummynet limiters available).
• Phones mark DSCP EF — CONFIRMED (Howard 2026-06-18). So we can rely on DSCP for WMM (Layer 2) + switch QoS (Layer 3); the 10.0.30.0/24 subnet match (Layer 1) is the safety net. No pfSense set-DSCP rule needed.

Measured WAN bandwidth (2026-06-18) — REFRAMES QoS priority

• WAN1 (fiber, primary): upload ~522 Mbps (Cloudflare single-stream from pfSense). RRD 3-day peaks: 680 Mbps down / 98 Mbps up (actual usage).
• WAN2 (coax): not measurable remotely (source-route bind to 72.211.21.217 failed; needs a WAN2-routed host or the Cox bill). Coax is typically asymmetric ~20–50 Mbps up — size its shaper conservatively.
• Implication: 30 calls ≈ ~3 Mbps. WAN1 upload (~522 Mbps) vs peak usage (98 Mbps) = huge headroom → the WAN is NOT the everyday voice bottleneck. Everyday dropped-calls = RF (Phases 2–4 of the master plan). QoS here is INSURANCE, not the day-to-day fix — it earns its keep in two cases: (1) WAN2 failover (small coax upload + a big upload → real congestion), (2) rare WAN1 saturation (backup / large upload; you do hit 680 Mbps down). Build it (cheap, correct), but set expectations: RF is the substance.

Three layers (priority order; Layer 1 = insurance, see reframe above)

Layer 1 — pfSense WAN shaper (PRIMARY — this is where calls break)

Type: HFSC (hierarchical, lets us guarantee voice a floor while letting it borrow idle bandwidth). Per WAN interface, three queues:

Queue	Role	HFSC settings (starting point)
qVoice	voice (VLAN 30 / DSCP EF)	priority 7, realtime ~30% of WAN-up, link-share 30%, NOT default
qACK	TCP ACKs (keeps downloads snappy)	priority 6, ~10%
qDefault	everything else	default, link-share ~60%

Match rule (floating, WAN, direction out): source 10.0.30.0/24 → qVoice. (Optionally also match DSCP EF if phones mark it — see Layer 4.) One floating rule per WAN, or interface = WAN_Group.

Download side: RTP from the PBX to the phones is shaped on the LAN-side queues. The wizard builds both directions; if hand-building, mirror a qVoice on the internal interfaces too. Upload is the more critical direction for cloud-PBX voice, but do both.

Build path (GUI — Howard drives):

• Easiest: Firewall → Traffic Shaper → Wizard → "Multiple Lan/Wan" — set #WAN=2, #LAN as needed, enter each WAN's bandwidth (below), on the VoIP page choose "prioritize by address" = 10.0.30.0/24 with a guaranteed %; the wizard generates HFSC queues + the float rules. Then tune.
• Or manual: Firewall → Traffic Shaper → By Interface → add HFSC on WAN1 + WAN2, create the 3 queues, then Firewall → Rules → Floating → match 10.0.30.0/24 out → Ackqueue/Queue = qACK/qVoice.

Sizing inputs: WAN1 upload ~522 Mbps (measured 2026-06-18) → shape qVoice's parent to ~480–500 Mbps. WAN2 (coax) upload still UNKNOWN (remote source-route test failed) — get from the Cox bill or a speedtest from a host routed via WAN2; size conservatively (assume ~35 Mbps up until measured). Shaping to ~90–95% of actual upload keeps the queue in pfSense (where we control priority), not at the ISP. WAN2 is the one that actually constrains voice (on failover), so its number matters most.

Layer 2 — UniFi WMM (the WiFi phones — Poly)

Over the air, WMM maps DSCP → WiFi access categories; voice (DSCP EF/46) → WMM Voice AC (gets TXOP priority over data). WMM is ON by default on UniFi — verify it's enabled on CSCNet and that the U7 APs honor DSCP→WMM. This is what protects the 22 Poly phones over the air during WiFi congestion. (Ties into the RF work — a clean 5/6 GHz + WMM = good wireless voice.)

Layer 3 — UniFi switch QoS (the wired AudioCodes)

UniFi switches honor 802.1p/DSCP and queue tagged voice to a high-priority egress queue — mostly automatic once the phones mark DSCP. LAN links are gig and rarely congested, so this is the least critical layer, but confirm the USW isn't stripping DSCP and that voice VLAN 30 frames get the priority queue.

Layer 4 — DSCP marking (make the above reliable)

• Verify the phones mark voice: AudioCodes + Poly typically tag RTP EF (46) and signaling CS3 (24) by default, often set via the PBX/provisioning. Confirm with Vertical (Richard) or capture a packet.
• If they DON'T mark (or inconsistently): add a pfSense floating rule that SETS DSCP EF on 10.0.30.0/24 traffic (Advanced → "Match/Set DSCP"). Then Layer 1/2/3 can all match on EF too.
• Match-by-subnet (Layer 1) works regardless of DSCP — it's the safety net. DSCP makes WMM (Layer 2) and switch QoS (Layer 3) automatic.

Implementation order

1. Get the Cox WAN upload numbers (blocker for Layer 1 sizing).
2. Confirm phones mark DSCP EF (Vertical) — decides whether we add the pfSense set-DSCP rule.
3. Build Layer 1 (pfSense HFSC + float rule) — dry-run mindset: set it, then validate.
4. Verify Layer 2 (WMM on CSCNet) + Layer 3 (switch honoring DSCP).
5. Validate (below). Tune qVoice % if needed.

Validation (prove it works)

• Baseline: from a LAN host, saturate the WAN upload (big upload / iperf3 -u / speedtest) WHILE on a call from a voice phone — note the breakup without QoS.
• After: repeat the same saturation; call stays clean. Check Firewall → Traffic Shaper → Queues: qVoice carrying voice with ~0 drops while qDefault absorbs the saturation + drops.
• Confirm both WANs (test on primary; fail to WAN2 and re-test).

Rollback

Firewall → Traffic Shaper → disable/remove the shaper; delete the floating rule. Zero residual effect (QoS only orders packets under congestion; removing it reverts to FIFO). The set-DSCP rule (if added) can stay or go independently.

Notes / interplay with the rest of the plan

• QoS is independent of the RF work — it helps wired + WiFi voice immediately and can be built tonight regardless of the 2.4/5/6 GHz changes.
• It does NOT fix RF problems (a phone on a 50%-retry 2.4 GHz radio still suffers) — QoS handles congestion/ contention for bandwidth, RF tuning handles the air. Both are needed; they're complementary.