ip-ntable

ip ntable { show | get | set | flush | add | change | delete } [ options ]

show
    Displays neighbour table entries, optionally filtered by device, address, or state.

get
    Retrieves detailed information for a specific neighbour table entry by address.

set
    Modifies global parameters of the neighbour cache, such as timeouts and garbage collection settings.

add
    Adds a new static neighbour table entry for a given IP address and hardware address.

change
    Modifies an existing neighbour table entry's properties.

delete
    Deletes a specific neighbour table entry.

flush
    Removes neighbour table entries, often used to clear stale entries or for troubleshooting.

ip-ntable (or ip ntable) is a sub-command of the ip utility in Linux, part of the iproute2 package. It is used to examine and manage the kernel's neighbour cache (often referred to as the ARP table for IPv4 or NDP cache for IPv6). This cache stores mappings between IP addresses and hardware (MAC) addresses for directly connected hosts.
The command allows administrators to inspect existing neighbour table entries, define global parameters for the neighbour cache, and manage specific entries. It provides fine-grained control over various aspects like entry timeouts, garbage collection, and state transitions, which are crucial for network performance and stability. It's a powerful tool for diagnosing network connectivity issues at Layer 2.

Requires root privileges (CAP_NET_ADMIN capability).
Improper use of ip ntable set can severely impact network performance or connectivity.
Many of the parameters configured via ip ntable set correspond to sysctl entries under net.ipv[4|6].neigh.*.

When using ip ntable set, several important global parameters can be configured to tune the neighbour cache's behavior. Key parameters include:
base_reachable_time: Controls the base for how long a neighbour entry is considered valid (reachable).
retrans_time: Influences the retransmission timeout for neighbour solicitations.
gc_stale_time: Defines how long entries can stay in a 'stale' state before garbage collection considers them for removal. Adjusting these values is crucial for network performance, especially in environments with dynamic network topologies or specific connectivity requirements.

While both ip ntable and ip neighbor (or ip neigh) deal with the kernel's neighbour cache, they serve slightly different primary purposes. ip neighbor is primarily used for managing individual neighbour entries (e.g., adding or deleting static ARP entries for specific hosts). In contrast, ip ntable offers more extensive control over the global parameters and behavior of the entire neighbour table, allowing for tuning of timeouts, garbage collection, and other system-wide neighbour caching mechanisms. There is some functional overlap, particularly for adding/deleting entries, but their core focus differs.

The ip-ntable command is an integral part of the iproute2 utility suite, developed primarily by Alexey Kuznetsov. This suite was created to provide a unified and more powerful interface for controlling TCP/IP networking on Linux, replacing older, disparate tools like ifconfig and arp. ip-ntable specifically addresses the need for detailed management of the kernel's neighbour cache, offering granular control over its parameters and entries, which was not comprehensively available in previous tools.

ip(8), ip-neighbor(8), arp(8), sysctl(8)