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 neigh { add | change | replace | append | delete | get } { ADDRESS dev IFNAME [ lladdr LLADDR ] [ nud STATE ] [ proxy ] }
ip neigh { list | flush | show } [ dev IFNAME ] [ to PREFIX ] [ state STATE-LIST ] [ nud STATE-LIST ] [ vrf NAME ] [ router ] [ proxy ] [ vlan VID ] [ unmanaged ]

add
    Add a new neighbor entry

change
    Change an existing neighbor entry

replace
    Add a new neighbor or change an existing one

append
    Add a new neighbor after the current one (for lists)

delete
    Delete a neighbor entry

get
    Get a neighbor entry

list
    List neighbor entries (alias: show)

flush
    Flush neighbor entries matching criteria

dev IFNAME
    Device name (interface)

lladdr LLADDR
    Link-layer (MAC) address

nud STATE
    NUD state: permanent, noarp, stale, reachable, delay, probe, failed, inactive

proxy
    Make entry a proxy ARP/ND entry

to PREFIX
    Prefix to match for list/flush

state STATE-LIST
    Kernel states for filtering (e.g., permanent)

vrf NAME
    Virtual Routing and Forwarding instance

router
    Show only router entries

vlan VID
    Filter by VLAN ID

unmanaged
    Show unmanaged entries

self
    Show entries pointing to self

The ip neigh (or ip neighbor) command, part of the iproute2 suite, manages the kernel's neighbor discovery tables for IPv4 (ARP) and IPv6 (Neighbor Discovery Protocol - ND). It displays, adds, modifies, or deletes entries mapping IP addresses to link-layer (MAC) addresses.

Dynamic entries are learned automatically via ARP requests or ND messages, but static entries can be added for security, failover, or troubleshooting. Common use cases include viewing the ARP cache with ip neigh show, flushing stale entries, or adding permanent entries to prevent ARP spoofing.

This replaces legacy tools like arp, offering more features like VRF support, VLAN filtering, and fine-grained state control. Neighbor Unreachability Detection (NUD) states track entry freshness: reachable, stale, delay, probe, etc. Incorrect usage, like permanent entries with wrong MACs, can break connectivity, so caution is advised.

Essential for network admins debugging connectivity issues, securing switches, or configuring routers.

Requires root for modifications; permanent entries can cause network loops or blackholing if MAC is wrong. IPv6 requires link-local scope. Flush may temporarily disrupt traffic.

permanent: Never expires, static.
noarp: Valid but don't create ARP entry.stale: Unconfirmed, may be invalid.
reachable: Recently confirmed.
delay/probe: Probing unreachability.

ip neigh show dev eth0: List ARP for eth0.
ip neigh add 192.168.1.1 lladdr 00:11:22:33:44:55 dev eth0 nud permanent: Static ARP.
ip neigh flush dev eth0 nud stale: Clear stale entries.

Introduced in iproute2 (1999-2001) by Alexey Kuznetsov as modern replacement for arp(8)/ipchains. Enhanced in Linux 2.4+ kernels with NUD and IPv6 support; current versions (iproute2 6.x) add VRF, BFD integration.

ip(8), arp(8), bridge(8), ss(8), rdisc6(8)