# Switching & VLAN Fabric

> This document describes the Layer 2 transport fabric and the boundaries it must preserve for routing, security, and QoS to remain inspectable.

Status: active · Kind: reference · Last verified: 2026-07-20 · Date: 2025-12-15

This document describes the Layer 2 transport fabric and the boundaries it must
preserve for routing, security, and QoS to remain inspectable.

The switching fabric forwards intent; it does not decide intent.

> Design principles: see **[Lab Philosophy](/homelab/philosophy)**.

---

## Design Goals

The fabric is designed to:

- provide predictable, low-latency forwarding
- preserve clear Layer 2 and Layer 3 boundaries
- keep routing and security policy out of access switches
- preserve VLAN tags and locally assigned DSCP markings end to end
- prefer hardware-offloaded transport over distributed control logic
- fail in understandable physical segments

---

## Topology Model

The physical layout follows a simple hierarchy:

- a rack-resident core aggregates the router and downstream switching
- rack access switches connect servers and infrastructure devices
- remote access switches extend tagged trunks to other rooms
- access points and endpoints attach at the edge of the fabric

The core and access layers do not perform inter-VLAN routing. Their job is to
move frames between explicit access ports and trunks.

---

## VLAN Propagation

VLANs are defined as trust boundaries and terminate at the router. Switches are
responsible for:

- VLAN tagging and forwarding
- explicit access-port membership
- explicit tagged trunks between infrastructure devices
- hardware-offloaded switching where supported

The fabric avoids VLAN translation, stacked VLANs, and per-switch policy
interpretation. A switch should not need application knowledge to forward a
flow correctly.

---

## Layer 3 and Security Boundary

The router remains the Layer 3 authority:

- inter-VLAN and WAN routing occur there
- firewall and NAT policy occur there
- device- and service-aware traffic classification occurs there
- WAN route selection and steering eligibility occur there

This centralizes identity-aware decisions without pretending that all packet
handling happens on one device.

---

## QoS Contract Preservation

The current packet path is:

```text
LAN endpoint → Layer 2 fabric → router classifier / route selector → inline bridge shaper / CAKE → WAN
```

The ordinary switching fabric preserves the router's normalized DSCP marking.
It does not reclassify traffic, select CAKE tins, or run independent queue
policy.

The inline WAN bridge is a deliberate exception to the otherwise transport-only
Layer 2 role. It sits at each bottleneck and owns queue enforcement: carrier
mark washing, reply-path class restoration, CAKE scheduling, shaping, and
adaptive rates.

That distinction keeps ownership clear:

- **switching fabric:** transport VLAN and DSCP state
- **router:** classify, firewall, NAT, and select routes
- **inline bridge shaper:** enforce the queue contract at the bottleneck

Queue priority does not imply WAN steering. The fabric carries both decisions
but owns neither.

---

## Failure Characteristics

The topology keeps physical failure domains visible:

- loss of an access switch affects its attached segment
- loss of a remote trunk isolates that remote segment
- loss of the switching core interrupts paths that depend on core aggregation
- loss of the router removes Layer 3 policy and WAN reachability
- loss of inline shaping may fall back to raw powered bypass, preserving
  connectivity without congestion control
- complete loss of power to the shaper host is not covered by its internal
  powered-bypass mechanism

Bypass is a continuity mechanism, not a healthy QoS state. Restoration requires
confirming that the bridge, classifier contract, and CAKE enforcement are all
observable again.

---

## Design Invariants

- Switches remain transport devices, not policy engines.
- Trunks carry only the VLANs they require.
- Access ports map endpoints into one intended trust zone.
- Router-originated DSCP survives the switching path unchanged.
- Carrier-originated markings are not trusted as local priority intent.
- Hardware offload is preferred unless it would bypass an explicitly required
  policy boundary.
- New routing, shaping, or classification behavior requires a separate design
  and rollback plan.

---

## Related Documentation

- [Edge & Traffic Policy](/homelab/network/edge-and-traffic-policy) — Routing, classification, shaping, and fail-safe authority
- [wanctl Control Plane](/homelab/network/wanctl-control-plane) — Adaptive control and steering boundaries
- [NetBox as Source of Truth](/homelab/network/netbox-source-of-truth) — Intended topology and addressing authority