# 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.
