ip-neighbour

Display the neighbour/ARP table entries

$ ip [[n|neighbour]]

$ sudo ip [[n|neighbour]] [[f|flush]] dev [ethX]

$ ip [[n|neighbour]] [[g|get]] [lookup_ip] dev [ethX]

$ sudo ip [[n|neighbour]] [add|delete] [ip_address] lladdr [mac_address] dev [ethX] nud reachable

$ sudo ip [[n|neighbour]] [change|replace] [ip_address] lladdr [new_mac_address] dev [ethX]

ip [ OPTIONS ] neigh { add | del | change | replace | set } ADDR dev DEV [ lladdr LLADDR ] [ nud { permanent | reachable | stale | delay | probe | failed } ] [ expires TIME ] [ proxy ] [ router ] ...
ip [ OPTIONS ] neigh { show | flush } [ dev DEV ] [ to PREFIX ] [ nud STATE ] [ proxy ] ...

dev DEV
    Specifies the network device (e.g., eth0, wlan0) on which to operate or filter.

to PREFIX
    Filters or specifies the IP address or network prefix for the neighbor entry.

lladdr LLADDR
    Specifies the link-layer (MAC) address to be associated with an IP address. Used with add, change, etc.

nud { STATE }
    Sets or filters by the Neighbor Unreachability Detection (NUD) state for the entry. Possible states include permanent (static, never expires), reachable (recently confirmed), stale (valid but old), delay (waiting validation), probe (actively probing), and failed (resolution failed).

add
    Adds a new neighbor cache entry.

del
    Deletes an existing neighbor cache entry.

change
    Modifies an existing neighbor cache entry. Fails if the entry doesn't exist.

replace
    Replaces an existing entry or adds it if it doesn't exist.

set
    An alias for the replace command.

show
    Displays neighbor cache entries. This is the default command if no action is specified.

flush
    Clears neighbor cache entries matching specified criteria. Useful for clearing stale or failed entries.

expires TIME
    Sets the expiration time for the neighbor entry, in seconds. Ignored if permanent is set.

proxy
    When used with add, marks the entry as a proxy ARP/NDP entry, allowing the host to answer ARP/NDP requests for this address. When used with show, filters for proxy entries.

The ip neigh command, a subcommand of the iproute2 utility, is used for managing the kernel's neighbor cache. This cache, also known as the ARP cache for IPv4 or the NDISC (Neighbor Discovery Protocol) cache for IPv6, stores mappings between IP addresses and hardware (MAC) addresses for devices on the local network segment. These mappings are fundamental for Layer 2 communication, allowing a host to determine the correct MAC address to send data frames to a specific IP address.

ip neigh provides functionalities to view, add, delete, change, or replace neighbor entries. It's an indispensable tool for network administrators and users for troubleshooting connectivity issues, understanding local network topology, and manually configuring static neighbor entries. The command can display various states of neighbor entries, such as REACHABLE, STALE, FAILED, PERMANENT, or PROBE, which indicate the current status of the address resolution process and reachability of the neighbor.

Modifying neighbor cache entries (e.g., using add, del, change) typically requires root privileges.
The kernel dynamically manages neighbor cache entries; manually added entries (unless marked permanent) can still be superseded or aged out if the kernel's Neighbor Unreachability Detection (NUD) mechanism finds a discrepancy or determines the neighbor is no longer reachable.
Interpreting the NUD states (e.g., stale, failed) is crucial for accurate network troubleshooting, as they indicate the current status of reachability.

NUD is a crucial part of IP's neighbor management. It's a kernel mechanism that continuously tracks the reachability of neighbors, ensuring that the cache entries are up-to-date. When a neighbor becomes unreachable, NUD detects this and updates the entry's state, preventing data from being sent to a non-existent or moved MAC address. The nud parameter in ip neigh allows for manual control or filtering based on these states, which are vital for network diagnostics.

The ip neigh command effectively consolidates the management of both IPv4's Address Resolution Protocol (ARP) cache and IPv6's Neighbor Discovery Protocol (NDP) cache. While the underlying protocols and their mechanisms differ, ip neigh provides a unified interface to view and manipulate these critical mappings between IP addresses and link-layer addresses (MAC addresses), making network management consistent regardless of the IP version in use.

Common uses include troubleshooting connectivity issues by inspecting failed or stale entries, clearing specific entries (e.g., ip neigh flush all) to force re-resolution, adding permanent entries for critical devices or specific network configurations, or setting up proxy ARP/NDP. The default command, when no subcommand is specified, is show, making ip neigh a quick way to list all current neighbor entries and their states.

The ip command, including its neigh subcommand, is part of the iproute2 utility suite. This suite was developed by Alexey Kuznetsov starting in the late 1990s as a modern replacement for older network configuration tools like ifconfig, route, netstat, arp, and ndp. iproute2 was designed to be more powerful, flexible, and better suited for advanced Linux networking, supporting features like policy routing, traffic control, and comprehensive IPv6 management. The ip neigh command specifically unified the management of IPv4 ARP and IPv6 NDISC caches, providing a consistent interface for neighbor resolution across both protocols, which was a significant improvement over separate, protocol-specific utilities.

ip(8), arp(8), ndp(8), ip-link(8), ip-address(8)