VLAN troubleshooting — finding the broken VLAN in five minutes

A broken VLAN has a small set of common failure modes. This lesson is the diagnostic flow that finds the root cause in five minutes, the tcpdump flags that reveal tagged frames, and the symptoms that identify each failure.

The diagnostic flow

flowchart TB
  A[VLAN broken] --> B[Step 1: link up?<br/>show interface ethernet]
  B --> C{Link OK?}
  C -->|no| D[Physical layer]
  C -->|yes| E[Step 2: tagged frames arriving?<br/>tcpdump -e -n vlan id]
  E --> F{Frames arriving?}
  F -->|no| G[Switch port configuration]
  F -->|yes| H[Step 3: sub-interface state<br/>ip link show eth0.N]
  H --> I{Sub-interface up?}
  I -->|no| J[VyOS configuration]
  I -->|yes| K[Step 4: routing<br/>show ip route]
  K --> L{Route OK?}
  L -->|no| M[Routing config]
  L -->|yes| N[Step 5: firewall<br/>show log firewall]

Step 1 — link up

vyos@vyos:~$ show interface ethernet eth0
eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ...

If the link is down, the issue is physical. Check the cable, the switch port, the NIC driver.

Step 2 — tagged frames arriving

vyos@vyos:~$ tcpdump -i eth0 -e -n vlan 10 -c 10
tcpdump: listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
14:23:01.421 aa:bb:cc:dd:ee:ff > 11:22:33:44:55:66, ethertype 802.1Q (0x8100), vlan 10, ethertype IPv4, 192.0.2.10 > 192.0.2.1: ICMP echo request

The -e flag shows the link-layer header (including the VLAN tag). The vlan 10 filter captures only VLAN 10 frames.

Step 3 — sub-interface state

vyos@vyos:~$ ip link show eth0.10
3: eth0.10@eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ...

The sub-interface is up. If it is down, the issue is the VyOS configuration:

vyos@vyos:~$ show configuration commands | match "eth0 vif 10"

Step 4 — routing

vyos@vyos:~$ show ip route
S    0.0.0.0/0 [1/0] via 192.0.2.254, eth0.10
C    192.0.2.0/24 is directly connected, eth0.10

If a route is missing, the issue is the routing configuration.

Step 5 — firewall

vyos@vyos:~$ show log firewall | last 20

The firewall log shows dropped packets and the rule that dropped them.

Common failure modes and their symptoms

How the result is validated

The diagnostic commands confirm:

• Link state: show interface ethernet eth0
• Tagged frames: tcpdump -i eth0 -e -n vlan <id>
• Sub-interface state: ip link show eth0.<id>
• Routing: show ip route
• Firewall: show log firewall | last 20

How it fails

The diagnostic commands themselves can fail:

• tcpdump with no output: the filter is wrong, or the link is down, or the peer is not sending.
• show interface shows up but no traffic: the firewall or routing is broken.
• ip link show shows the sub-interface but no address: missing address directive.
• show log firewall is empty: the firewall is not logging or the traffic is not reaching the firewall.

Rollback

The recovery from a broken VLAN:

• Switch port wrong: reconfigure the switch.
• Sub-interface missing: set interfaces ethernet eth0 vif <N> address '...'; commit; save.
• Firewall blocking: reconfigure the firewall rule.
• Routing missing: reconfigure the route.

Production discipline

Cross-course references

The OPNsense course’s XIV-OPNsense-VLAN covers the equivalent configuration on the firewall side. The Linux course’s XXII-Linux-NetTroubleshoot covers the underlying network troubleshooting. The Observability course’s LX-Observability-NetworkObs covers how to alert on VLAN changes.

Quiz