Interface anti-patterns — the configurations that always cause trouble

A handful of interface configurations reliably cause trouble in production. This lesson is the catalog of anti-patterns and the correct configuration that replaces each.

Anti-pattern 1 — MTU only on one side

[edit]
vyos@vyos# set interfaces ethernet eth0 mtu '9000'
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

The local end has MTU 9000 but the peer has MTU 1500. Jumbo frames from the local end are dropped at the peer. Packets flow up to 1500; everything larger fails silently.

Correct configuration: match MTU on both ends. If the peer cannot be reconfigured, drop back to 1500 locally.

Anti-pattern 2 — firewall on the WAN only

[edit]
vyos@vyos# set firewall ipv4 forward filter rule 10 inbound-interface name 'eth0'
[edit]
vyos@vyos# set firewall ipv4 forward filter rule 10 action 'jump'
[edit]
vyos@vyos# set firewall ipv4 forward filter rule 10 jump-target 'WAN-IN'
[edit]
vyos@vyos# commit

Transit traffic arriving on the WAN is sent to a rule set. Traffic arriving on the LAN interfaces is not, so a misconfigured — or compromised — LAN device can source whatever it likes and the router forwards it.

Correct configuration: decide what the forward filter chain’s default-action is, and then justify every interface that is not covered by a rule. The chain has a default action of its own; leaving it at accept and filtering only the WAN means the router’s posture is “trust everything except the one direction I thought about”.

Anti-pattern 3 — Router Advertisements that carry no DNS

[edit]
vyos@vyos# set service router-advert interface eth0 prefix '2001:db8::/64'
[edit]
vyos@vyos# commit

The interface advertises a prefix, so hosts autoconfigure an address and a default route and IPv6 looks like it is working. Nothing in that advertisement tells them where DNS is. A dual-stack host papers over it by resolving on IPv4; a v6-only host falls back to whatever resolver it was shipped with, and the operator’s split-horizon or filtered DNS is quietly bypassed for exactly the clients that have no other path.

Correct configuration: advertise the resolver too, with RDNSS (RFC 8106), which is a leaf on the same tree:

set service router-advert interface eth0 prefix '2001:db8::/64'
set service router-advert interface eth0 name-server '2001:db8::53'

If your clients are old enough not to implement RDNSS, the alternative is stateless DHCPv6: set the RA’s other-config-flag so hosts know to ask, and run a DHCPv6 server that answers with the DNS options. Pick one deliberately — an RA with neither is the configuration above.

Anti-pattern 4 — speed and duplex forced by hand

[edit]
vyos@vyos# set interfaces ethernet eth0 speed '1000'
[edit]
vyos@vyos# set interfaces ethernet eth0 duplex 'half'
[edit]
vyos@vyos# commit

Forcing the pair disables autonegotiation on this end. If the peer is still autonegotiating, it cannot see a partner and falls back to half-duplex at its own default speed — and a duplex mismatch does not fail cleanly. The link stays up, small packets pass, and throughput collapses under load while the interface counters fill with collisions, late collisions and CRC errors. That is the worst failure shape there is: a link that works well enough to keep suspicion off it.

Correct configuration: leave both nodes at their default so both ends autonegotiate:

set interfaces ethernet eth0 speed 'auto'
set interfaces ethernet eth0 duplex 'auto'

Force the pair only when a device on the far end genuinely cannot negotiate, and then force both ends and record why. Note also that changing this with ethtool does not persist and is overwritten the next time the interface is reconfigured by a commit — on VyOS the configuration tree is the only durable place for it.

Anti-pattern 5 — depending on the switch’s native VLAN

[edit]
vyos@vyos# set interfaces ethernet eth0 vif 10 address '192.0.2.1/24'
[edit]
vyos@vyos# commit

eth0.10 handles frames tagged with VLAN 10. Untagged frames on the same wire are not handled by the sub-interface — they are received by the parent eth0, which here has no address and no purpose, so they arrive and go nowhere.

That is fine until the switch port’s native VLAN is 10 and somebody assumes the router will pick those frames up as VLAN 10 traffic. It will not. The router sees untagged frames; the switch believes it sent VLAN 10; both are behaving correctly and the service does not work.

Correct configuration: make the tagging explicit on both ends. Configure the switch port to tag every VLAN it carries to this router, so nothing arrives untagged; or, if untagged frames must be carried, configure the parent interface deliberately for whatever that untagged traffic is and document that it is the native VLAN.

Anti-pattern 6 — jumbo frames without negotiation

[edit]
vyos@vyos# set interfaces ethernet eth0 mtu '9000'
[edit]
vyos@vyos# commit

The MTU is set but the switch port and the NIC do not negotiate jumbo frames. Packets larger than 1500 are dropped silently.

Correct configuration: verify all components in the path support jumbo frames before configuring MTU 9000. Test with ping -M do -s 8972 <peer>.

Anti-pattern 7 — interface description missing

[edit]
vyos@vyos# set interfaces ethernet eth0 address '192.0.2.1/24'
[edit]
vyos@vyos# commit

The interface has an address but no description. Six months later, the operator cannot remember which interface is the WAN and which is the LAN. The wrong interface gets reconfigured during an incident.

Correct configuration: always set a description:

set interfaces ethernet eth0 description 'WAN - ISP primary uplink'

Anti-pattern 8 — IP address on a bridge member

[edit]
vyos@vyos# set interfaces bridge br0 member interface eth0
[edit]
vyos@vyos# set interfaces ethernet eth0 address '192.0.2.1/24'
[edit]
vyos@vyos# commit

The interface is a bridge member but has its own address. The address is reachable but the bridge cannot route through it correctly. The bridge’s routing is confused.

Correct configuration: the address should be on the bridge, not the member:

set interfaces bridge br0 address '192.0.2.1/24'
delete interfaces ethernet eth0 address '192.0.2.1/24'

Anti-pattern 9 — disabled interface left enabled

A box decommissioned from production but the configuration is still live. The interface is up but the peer is gone. The box sends ARP, gets no replies, and logs warnings.

Correct configuration: set interfaces ethernet ethX disable; commit; save for any interface that is not in active use.

Anti-pattern 10 — MAC override without documentation

set interfaces ethernet eth0 mac 'aa:bb:cc:dd:ee:ff'
commit
save

The MAC is overridden but the change is not documented. Six months later, the operator sees the strange MAC in the ARP table and cannot remember why.

Correct configuration: always document the override in the team’s interface inventory.

How the result is validated

show configuration commands | match "interfaces ethernet"
show interfaces ethernet
compare saved

sudo ethtool eth0

The first lists the interface configuration as commands you can diff against a known-good file; the second shows the operational state VyOS knows about; compare saved is the one that answers “is what is running also what will come back after a reboot”, which is the question a hand-edited router usually fails. Drop to ethtool for the driver-level view — negotiated speed and duplex, and whether autonegotiation is on — because that is the layer where anti-pattern 4 shows up.

How it fails

The meta-anti-pattern is the configuration that is “working” but fragile. Common examples:

• MTU mismatch that works for ICMP but fails for large TCP segments.
• Firewall on one side only, masking upstream failures.
• Missing description, masking operational confusion.
• Address on bridge member, masking routing errors.
• Jumbo frames without negotiation, masking dropped packets.

Rollback

The recovery from an interface anti-pattern:

• MTU mismatch: reconfigure the local end to match the peer.
• Firewall gap: add the missing forward filter rule, and check the chain’s default-action while you are there.
• RA with no DNS: add name-server to the interface’s service router-advert block.
• Forced duplex: set speed auto and duplex auto on both ends and confirm with ethtool.
• Address on bridge member: move the address to the bridge.
• Jumbo frames: drop MTU back to 1500.

All of these are ordinary commits, so rollback N and commit-confirm apply — and commit-confirm is worth the habit for anything touching the interface you are connected over.

Production discipline

Cross-course references

The OPNsense course’s VII-OPNsense-Interfaces covers the equivalent anti-patterns 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 anti-patterns.

Quiz