Troubleshooting
Most problems with a Debian router are in one of three places, and each has a command that tells you which: networkctl for interfaces, sysctl net.ipv4.ip_forward for routing, and the nftables counters for the policy.
The VLAN that never appears
A .netdev file for a VLAN does nothing on its own. networkd creates a VLAN only when the parent interface's .network file names it with VLAN=. In the lab, a new printers VLAN had its .netdev and .network files, networkctl reload succeeded, and the interface simply didn't exist. Adding VLAN=printers to the trunk's file, and reloading again, created it at once. There's no error message for this, so it's the first thing to check.
Symptoms and causes
| Symptom | Check | Likely cause |
|---|---|---|
A link stays pending in networkctl | systemctl status systemd-udevd | networkd waits for udev to set up each link; udev isn't running |
A link is unmanaged | networkctl status <link> | No .network file matches its name; check [Match] Name= |
| A VLAN interface doesn't exist | grep VLAN= /etc/systemd/network/*.network | The parent's .network doesn't list it |
| VLAN up, but hosts can't reach the gateway | tcpdump -nei eth1 vlan | The switch port isn't tagging that VLAN, or the IDs differ |
| Nothing is forwarded between VLANs | sysctl net.ipv4.ip_forward | Forwarding off: the sysctl.d file is missing or not applied |
| One pair of VLANs can't talk | nft list chain inet filter forward | That pair isn't in the verdict map: the final counter climbs |
| Internet fails, VLANs work | The ISP side of a capture | No masquerade, or it matches the wrong output interface |
| Can't reach the router itself | nft list chain inet filter input | The input chain doesn't allow it from that VLAN |
Cheat sheets: nftables, Network error messages explained, Common ports.
root@router:~# ls /etc/systemd/network | grep printers; networkctl reload; sleep 2; networkctl list printers
30-printers.netdev
30-printers.network
Interface "printers" not found.
root@router:~# sed -i 's/^VLAN=servers$/VLAN=servers\nVLAN=printers/' /etc/systemd/network/20-trunk.network && grep VLAN= /etc/systemd/network/20-trunk.network && networkctl reload && sleep 2 && networkctl list printers
VLAN=staff
VLAN=guest
VLAN=servers
VLAN=printers
IDX LINK TYPE OPERATIONAL SETUP
16 printers vlan routable configured
1 links listed.- Lines 1–4: Both files exist and the reload succeeds, but the VLAN doesn't.
- Lines 6–10: Name it in the trunk's .network file…
- Lines 11–12: …and reload again: now it exists.
Check your understanding
A new VLAN's interface doesn't exist after networkctl reload, and nothing is logged. What do you check first?
- That the parent port's .network file lists it with VLAN=.
- That forwarding is on.
- The nftables forward chain.
- That the switch port is tagged.