Runbook: Troubleshoot VLAN Connectivity

Purpose

This runbook diagnoses why a host on a VLAN cannot reach its gateway or other VLANs, isolating the fault between OPNsense, the trunk, the access switch port, and the host itself. It is the diagnostic companion to opnsense-rb-add-vlan.

When to use this runbook

Use this runbook when a host on a VLAN loses connectivity (was working, or never came up after a VLAN add), or when inter-VLAN routing is failing in a way that points at OPNsense or the trunk. If the issue is clearly a host-side firewall, start on the host and skip the OPNsense-side diagnostics.

Pre-checks

• Capture a fresh encrypted config backup before any change.
• Confirm the affected VLAN ID, the parent interface on OPNsense, and the access switch the device is on.
• Confirm the device IP, expected gateway IP, and expected behavior (gateway reachable? specific destination reachable?).

Procedure

1. Verify the VLAN exists. Open Interfaces > Other Types > VLAN. The VLAN ID should be listed with the correct parent interface. If missing, the device cannot possibly reach OPNsense until the VLAN is created.
2. Verify assignment. Open Interfaces > Assignments. The VLAN should be assigned to an OPT entry. Click the OPT and confirm Enable interface is checked and the IP/CIDR is correct.
3. Verify the interface is up. At the OPNsense shell (Diagnostics > Command Prompt), run ifconfig <vlan_if>. You should see status: active and the configured address. If status: no carrier, the trunk or parent link is down.
4. Verify the firewall rules. Open Firewall > Rules > [VLAN interface]. The default deny at the bottom catches anything not explicitly allowed. Add or fix rules before going further.
5. Test from OPNsense to the device. From Diagnostics > Ping, ping the device IP. Success means the path OPNsense → device is healthy; failure means the issue is on the access side or the device.
6. Test from the device to its gateway. From the device, ping the VLAN interface IP. Failure means the path device → OPNsense is broken — usually the trunk, the access port, or the host firewall.
7. Capture on the parent interface. At the OPNsense shell, run tcpdump -nei <parent_if> vlan <vlan_id> -c 50 while reproducing. You should see 802.1Q-tagged frames for the VLAN. No frames at all = the trunk is not carrying the VLAN.
8. If no frames arrive, check the upstream switch. Confirm the OPNsense-facing port is a trunk and the VLAN ID is on the allowed list. Confirm the device-facing port is an access port for the VLAN ID. Watch the counters increment on both ports during the test.
9. Capture on the VLAN interface itself. Run tcpdump -nei <vlan_if> -c 50 while reproducing. You should see untagged frames; if you only see tagged frames, the parent NIC is not stripping the tag as expected (rare, indicates a driver issue).
10. Check spanning tree. A blocked port on the access side silently drops frames. Check the switch STP state for the access port; an ALN/BLK state means STP is blocking. Configure portfast/edge on access ports if STP is delaying connectivity.
11. Check for duplicate IPs. A duplicate IP on the VLAN causes intermittent connectivity. From the device, arp -an shows the gateway MAC. From OPNsense, arp -an | grep <device_ip> should show the same MAC. Mismatch means ARP is fighting.
12. For inter-VLAN issues. OPNsense routes between local interfaces by default, but a block rule on either side will stop it. Confirm rules exist in both directions on both interfaces. For asymmetric routing across multiple hops, check the path in both directions.

Verification

• Device can ping the VLAN interface IP.
• OPNsense can ping the device IP from Diagnostics > Ping.
• ifconfig <vlan_if> shows status: active and the configured address.
• Packet capture on the parent interface shows 802.1Q-tagged frames for the VLAN.
• Inter-VLAN flows complete end-to-end when expected.

Rollback

• If firewall rules were changed, disable the new rules and apply.
• If the VLAN interface was toggled, restore it to its prior enable state.
• Restore the pre-change encrypted config backup if alias or other changes were made.
• Revert any switch port changes to the documented prior state.

Escalation

• Escalate to the network team if the trunk is not carrying the VLAN: switch port mode mismatch, allowed VLAN list mismatch, or trunk disabled.
• Escalate to the network team if spanning tree is blocking a port; portfast or edge-port configuration may be needed on access ports.
• Escalate to the platform team if the parent NIC does not show the VLAN despite a correct config; suspect driver issue or unsupported hardware.
• Escalate to security if the request is to allow inter-VLAN routing that crosses trust boundaries (e.g. guest to corporate) without a documented exception.