Interface diagnostics — what to run when an interface is broken

When an interface is broken, the routing engineer needs a disciplined diagnostic flow. This lesson covers the standard command set, the triage flow, and the failure modes each command is designed to detect.

The triage flow

flowchart TB
  A[Interface broken] --> B[Step 1: link state<br/>show interface]
  B --> C{Link OK?}
  C -->|no| D[Physical layer<br/>cable, switch port, NIC]
  C -->|yes| E[Step 2: address<br/>ip addr show]
  E --> F{Address OK?}
  F -->|no| G[Address config<br/>DHCP, static, IPv6]
  F -->|yes| H[Step 3: route<br/>ip route show]
  H --> I{Route OK?}
  I -->|no| J[Routing config<br/>static, dynamic, default]
  I -->|yes| K[Step 4: peer<br/>ping, mtr, tcpdump]
  K --> L{Peer OK?}
  L -->|no| M[Upstream issue<br/>firewall, ISP, MTU]
  L -->|yes| N[Check application / firewall]

Step 1 — link state

vyos@vyos:~$ show interface ethernet eth0
eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
    inet 192.0.2.1/24 brd 192.0.2.255 scope global eth0
       valid_lft forever preferred_lft forever
    RX:  bytes  packets  errors  dropped  overrun  mcast
    12345678   123456   0       0        0        1234
    TX:  bytes  packets  errors  dropped  carrier  collisions
    87654321   876543   0       0        0        0

The output shows:

• state UP — the interface is admin-up and link-up.
• RX errors 0 TX errors 0 — no link-layer errors.
• RX dropped 0 TX dropped 0 — no packet drops.

If errors or dropped are non-zero, the link has issues: check the cable, the switch port, the auto-negotiation.

Step 2 — address

vyos@vyos:~$ ip addr show eth0
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
    inet 192.0.2.1/24 brd 192.0.2.255 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 fe80::5054:ff:fe12:3456/64 scope link
       valid_lft forever preferred_lft forever

The interface has the expected IPv4 address. inet6 fe80:: is the link-local IPv6 address (always present if IPv6 is enabled).

If the address is missing:

• DHCP: check show dhcp client leases.
• Static: re-issue the set command.
• IPv6: check Router Advertisements.

Step 3 — route

vyos@vyos:~$ ip route show
default via 192.0.2.254 dev eth0 proto static metric 100
192.0.2.0/24 dev eth0 proto kernel scope link src 192.0.2.1 metric 100

The routing table has a default route via 192.0.2.254 (the upstream gateway) and a connected route for the local subnet.

If a route is missing:

• Default: set protocols static route 0.0.0.0/0 next-hop <gateway>.
• Specific: set protocols static route <prefix> next-hop <gateway>.
• Dynamic: check the routing protocol (show ip bgp summary, show ip ospf neighbor).

Step 4 — peer

vyos@vyos:~$ ping -c 5 192.0.2.254
PING 192.0.2.254 (192.0.2.254) 56(84) bytes of data.
64 bytes from 192.0.2.254: icmp_seq=1 ttl=64 time=0.421 ms
...

vyos@vyos:~$ mtr -r -c 10 8.8.8.8
Start: 2026-08-15T14:23:01+01:00
HOST: vyos                         Loss%  Snt  Last  Avg  Best  Wrst StDev
  1. 192.0.2.254                   0.0%  10   0.4   0.4   0.3   0.5   0.1
  2. 10.0.0.1                      0.0%  10   1.2   1.3   1.0   2.1   0.3
  3. 8.8.8.8                       0.0%  10  12.4  12.5  12.0  14.1   0.6

ping tests reachability to the next hop; mtr traces the path to a remote host with packet loss statistics.

Packet capture with tcpdump

vyos@vyos:~$ tcpdump -i eth0 -n -c 10
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
14:23:01.421 IP 192.0.2.10 > 192.0.2.1: ICMP echo request
14:23:01.422 IP 192.0.2.1 > 192.0.2.10: ICMP echo reply
...

tcpdump shows the actual packets on the wire. It is the most direct way to confirm traffic is flowing. Common uses:

• Confirm ARP is resolving (arp who-has).
• Confirm BGP packets (tcp port 179).
• Confirm traffic is leaving the interface (tcpdump -i eth0 src host 192.0.2.1).
• Confirm MTU errors (tcpdump -i eth0 'ip[6:2] & 0x3fff != 0').

Reading error counters

vyos@vyos:~$ ip -s link show eth0
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
    RX: bytes  packets  errors  dropped  missed  mcast
    12345678   123456   12      0        0       1234
    TX: bytes  packets  errors  dropped  carrier  collisions
    87654321   876543   0       0        0        0

Non-zero errors indicates:

• RX errors: CRC errors, frame errors, FIFO overrun. Likely a physical-layer issue.
• TX errors: TX FIFO errors. Likely a driver issue or rate limiting.
• dropped: kernel queue overrun. Likely congestion.
• carrier: link-layer carrier loss. Likely physical-layer issue.
• collisions: half-duplex link. Should be zero on full-duplex.

How the result is validated

The diagnostic commands confirm:

• Link state: show interface ethernet
• Address: ip addr show
• Route: ip route show
• Peer: ping, mtr, tcpdump

If all four pass, the interface is operational. If any step fails, the operator fixes the failing layer before continuing.

How it fails

The production failure modes the engineer must recognise:

• Diagnostic commands run on the wrong interface. A typo of eth1 for eth0 produces output that looks plausible but is for the wrong link.
• tcpdump with no output. A packet capture with no packets can mean the link is down, the filter is wrong, or the peer is not sending. Each has a different fix.
• mtr showing high loss at one hop. The issue may not be at the hop that shows loss; mtr’s loss counters are end-to-end per hop and can be misleading for asymmetric paths.
• RX errors but link up. A cable with intermittent issues produces RX errors without dropping the link. Replace the cable.
• No route to a host that is reachable. The host may be on a directly-connected subnet but the route is missing from the routing table.

Rollback

Diagnostic commands are read-only. The recovery is for the underlying issue:

• Bad link: replace cable, fix switch port.
• Bad address: reconfigure.
• Bad route: reconfigure or restart routing protocol.
• Bad peer: investigate upstream.

Production discipline

Cross-course references

The Linux course’s XXII-Linux-NetTroubleshoot covers the underlying network troubleshooting. The Proxmox course’s XXIX-Proxmox-Networking covers the host-side diagnostics. The Observability course’s LX-Observability-NetworkObs covers how to alert on diagnostic output.

Quiz