Octet

Say this first

ip neigh is the ARP table for IPv4 and the NDP cache for IPv6, with a state machine. REACHABLE: the mapping was confirmed recently. STALE: the confirmation is old, but the entry is still used. DELAY: the entry was used while stale and the kernel waits a few seconds for an upper layer, such as a TCP ACK, to confirm it. PROBE: it is sending unicast ARP requests. FAILED: nobody answered. INCOMPLETE: first resolution in progress. PERMANENT is a static entry.

Go deeper

Example

Output

$ ip neigh show dev ens192
10.0.10.1 lladdr 00:1c:7f:3a:11:02 REACHABLE
10.0.10.30 lladdr 00:50:56:a1:9c:44 STALE
10.0.10.31 lladdr 00:50:56:a1:47:e0 DELAY
10.0.10.44 FAILED
10.0.10.5 lladdr 00:50:56:a1:00:05 PERMANENT

The lifecycle and default timers

No entry: the kernel broadcasts a request, entry is INCOMPLETE (3 tries, mcast_solicit, 1 s apart).
Reply received: REACHABLE for a random time between 15 and 45 seconds (base_reachable_time_ms 30000, randomised by half either way).
Timer expires: STALE. Still used to send traffic, nothing is sent on the wire yet.
A packet is sent using a stale entry: DELAY for 5 seconds (delay_first_probe_time). If TCP sees an ACK from that neighbour in that window, it confirms the entry and it returns to REACHABLE.
No confirmation: PROBE, 3 unicast requests (ucast_solicit). No answer: FAILED.

So STALE is normal and healthy. FAILED and INCOMPLETE are the states that mean trouble.

Fixing entries

Shell

ip neigh flush dev ens192                    # clear dynamic entries on one interface
ip neigh del 10.0.10.30 dev ens192
ip neigh replace 10.0.10.5 lladdr 00:50:56:a1:00:05 dev ens192 nud permanent
ip -s neigh show 10.0.10.30                  # adds used/confirmed/updated timers

They will ask next

You moved an IP to a new server and some clients still reach the old one. What do you do?
Their ARP caches still point at the old MAC. Send gratuitous ARP from the new server: arping -U -c 3 -I ens192 10.0.10.30 (iputils arping). Clustering tools such as keepalived do this on failover. If a firewall or router ignores gratuitous ARP, clear its entry by hand.
The kernel logs "neighbour table overflow". What happened?
The cache hit gc_thresh3 (1024 entries by default, with gc_thresh1 128 and gc_thresh2 512). It happens on hosts that sit on very large subnets or on Kubernetes nodes. Raise the three thresholds with sysctl under net.ipv4.neigh.default..
What does the router flag mean in an IPv6 entry?
The neighbour advertised itself as a router (the R flag in its NA). It appears for the default gateway's link-local address in ip -6 neigh.

Traps

Calling STALE an error. It is the normal resting state of an entry nobody has confirmed lately.
Using arp -n and missing IPv6 entries. ip neigh shows both families.

How did you do?Book 3.3 Internet (IP)