Linux ip neigh: Manage the ARP Table Like a Pro

The neighbor table - known as the ARP table for IPv4 - maps IP addresses to link-layer MAC addresses and sits in the hot path of every frame the host sends. When connectivity breaks at Layer 2, the neighbor table is usually where the truth is hiding: incomplete entries mean ARP resolution is failing, while stale or failed states point to reachability or probing problems. The modern way to inspect and manipulate this table is the ip neigh command from iproute2, which replaces the legacy arp tool. This guide covers ip neigh syntax, the neighbor states you will actually see, and the troubleshooting moves that fix broken resolution.

Showing the Neighbor Table

$ ip neigh show
192.168.1.1 dev eth0 lladdr 00:11:22:33:44:55 REACHABLE
192.168.1.20 dev eth0 lladdr aa:bb:cc:dd:ee:ff STALE
10.0.0.5 dev eth1 FAILED

Filter per device, prefix or state with the usual selectors:

$ ip neigh show dev eth0
$ ip neigh show to 192.168.1.0/24
$ ip neigh show nud failed

Neighbor States (NUD) Explained

The kernel tracks every entry through the Neighbour Unreachability Detection state machine. The states you will see in ip neigh output:

• REACHABLE - the entry is valid and confirmed; traffic flows normally.
• STALE - valid but unconfirmed for a while; the kernel will probe it before use. This is a normal resting state, not an error.
• DELAY / PROBE - the kernel is verifying a stale entry before using it.
• INCOMPLETE - resolution is in progress; no MAC learned yet. Persistent incomplete entries mean ARP requests are unanswered.
• FAILED - probing exceeded the retry limit; the neighbor is unreachable at Layer 2.
• PERMANENT / NOARP - administratively static entries (for example on a bridge or point-to-point link).

Adding, Changing and Deleting Entries

# add a static entry
$ sudo ip neigh add 192.168.1.50 lladdr 00:11:22:33:44:55 dev eth0 nud permanent

# replace or delete
$ sudo ip neigh replace 192.168.1.50 lladdr 00:11:22:33:44:66 dev eth0
$ sudo ip neigh del 192.168.1.50 dev eth0

Flushing the ARP Table

After VLAN changes, MAC moves or NIC replacement, flush the stale entries so the kernel re-resolves:

# flush everything on eth0
$ sudo ip neigh flush dev eth0

# flush dynamic entries for a prefix
$ sudo ip neigh flush to 192.168.1.0/24

# verify and regenerate
$ ip neigh show
$ ping -c 1 192.168.1.1

Flushing with nud all also removes permanent entries - use it only when you really want a clean slate.

Legacy arp Command Mapping

arp -a equals ip neigh show, arp -d equals ip neigh del, and arp -s equals ip neigh add ... nud permanent. Prefer the ip form on modern distributions; it supports IPv6 neighbor discovery entries and state filtering that arp cannot.

Troubleshooting Common Neighbor Problems

• INCOMPLETE for a local IP - check the other host is up, VLAN tags match on both sides, and no firewall drops ARP.
• FAILED after a MAC change - flush the entry; the old MAC is cached.
• Wrong MAC in the table - duplicate IP on the LAN; check for IP conflicts with arping.

Pair this with our tcpdump filters and troubleshooting guide, ethtool network diagnostics, and Linux network namespaces guide.

原文链接：https://man7.org/linux/man-pages/man8/ip-neighbour.8.html