How to Inspect and Tune Kernel Neighbour Tables in Linux Using ip ntable

The Linux kernel maintains neighbour tables to map Layer 3 IP addresses to Layer 2 data link hardware addresses. For IPv4, this system governs the Address Resolution Protocol (ARP) table, while IPv6 relies on Neighbour Discovery Protocol (NDP). When high network density, virtualisation hypervisors, software-defined networks, or container clusters generate massive numbers of concurrent connections, default neighbour table limits can become exhausted. This leads to dropped packets, kernel warnings such as “neighbour table overflow”, and network communication stalls. The ip ntable command provides administrators with direct visibility into kernel neighbour table parameters, allowing precise inspection and tuning of garbage collection intervals, cache sizes, and lookup thresholds.

Understanding Linux Kernel Neighbour Tables

In the Linux networking stack, neighbour tables store the state of active, stale, and reachable network neighbours. Every network interface interacting over Ethernet registers entries within these tables. To maintain efficient memory utilisation and fast hash lookup speeds, the kernel groups neighbour management into distinct tables:

• arp_cache: The primary ARP table responsible for IPv4 Layer 2 address mappings.
• ndisc_cache: The Neighbour Discovery cache responsible for IPv6 Layer 2 address mappings.

Each table operates under strict garbage collection (GC) parameters. When the number of entries exceeds predefined thresholds, the kernel aggressively purges stale records or fails to create new entries altogether if the hard limit is reached. Using ip ntable, you can interrogate both active table configurations and modify operational parameters in real time without restarting system services.

Inspecting Neighbour Tables Using ip ntable show

To inspect all neighbour tables currently managed by the kernel, execute ip ntable show in your terminal. This command displays the registered tables alongside their active operational attributes and interface bindings.

ip ntable show

The output presents structured blocks detailing each table’s name, device associations, and configurable parameters. To inspect a specific table such as the IPv4 ARP cache, append the name filter:

ip ntable show name arp_cache

To view IPv6 neighbour discovery parameters, query the ndisc_cache table:

ip ntable show name ndisc_cache

To examine device-specific overrides where an interface has dedicated neighbour configuration rules, specify the device parameter:

ip ntable show dev eth0

Key Kernel Neighbour Table Parameters and Thresholds

When reviewing the output of ip ntable show, several core metrics govern how the table scales and purges expired entries:

• thresh1 (gc_thresh1): The minimum entry threshold. Below this count, the kernel never triggers garbage collection.
• thresh2 (gc_thresh2): The soft threshold. When the table size exceeds this number for longer than 5 seconds, asynchronous garbage collection begins purging stale entries.
• thresh3 (gc_thresh3): The hard maximum limit. If the neighbour table reaches this value, synchronous garbage collection kicks in immediately. If entries cannot be purged fast enough, incoming neighbour resolution fails and the kernel logs table overflow errors.
• gc_int: The garbage collection interval in milliseconds, defining how frequently the kernel evaluates the table for cleaning.
• base_reachable: The baseline duration in milliseconds that an entry remains in a confirmed “reachable” state before transitioning to “stale”.
• retrans: The retransmit timer in milliseconds for neighbour solicitation or probe packets.

Tuning Neighbour Table Parameters with ip ntable change

In high-throughput environments such as Kubernetes worker nodes, Open vSwitch gateways, or busy reverse proxies, the default thresh3 hard limit (often set between 1024 and 4096 entries) can easily be saturated. You can adjust these thresholds directly using the ip ntable change command.

For example, to double the capacity thresholds for the IPv4 ARP cache, run:

sudo ip ntable change name arp_cache thresh1 1024 thresh2 4096 thresh3 8192

You can also tune the base reachable timer to adjust how long confirmed entries stay valid before requiring re-verification. To set the base reachable time to 60,000 milliseconds (60 seconds) on arp_cache:

sudo ip ntable change name arp_cache base_reachable 60000

To apply a similar adjustment to the IPv6 Neighbour Discovery cache:

sudo ip ntable change name ndisc_cache thresh1 1024 thresh2 4096 thresh3 8192

Verify that your changes were registered by running:

ip ntable show name arp_cache

Tuning Neighbour Tables via sysctl for Persistent Configuration

While ip ntable change modifies active kernel tables immediately, settings revert to defaults upon system reboot. To make custom neighbour table limits permanent across reboots, apply corresponding parameters via sysctl configuration files.

Create a dedicated sysctl configuration file at /etc/sysctl.d/99-neighbour-tables.conf:

sudo nano /etc/sysctl.d/99-neighbour-tables.conf

Add the following configuration directives:

# IPv4 ARP Cache Tuning
net.ipv4.neigh.default.gc_thresh1 = 1024
net.ipv4.neigh.default.gc_thresh2 = 4096
net.ipv4.neigh.default.gc_thresh3 = 8192
net.ipv4.neigh.default.gc_interval = 30

# IPv6 Neighbour Discovery Cache Tuning
net.ipv6.neigh.default.gc_thresh1 = 1024
net.ipv6.neigh.default.gc_thresh2 = 4096
net.ipv6.neigh.default.gc_thresh3 = 8192
net.ipv6.neigh.default.gc_interval = 30

Apply the configuration immediately without rebooting:

sudo sysctl --system

Troubleshooting Neighbour Table Saturation and Dropouts

To verify whether your system is actively dropping packets or suffering from table exhaustion, monitor kernel diagnostics and statistics. Inspect the system journal and dmesg logs for overflow indicators:

sudo dmesg | grep -i "neighbour table overflow"

You can also inspect raw neighbour statistics directly through the proc filesystem:

cat /proc/net/stat/arp_cache

The first line provides headers, while subsequent lines display counters including entries, allocations, destroys, and hash bucket grow events. If the table allocation count approaches thresh3 or shows rapid destruction under pressure, increase the garbage collection thresholds and verify network interface ARP behaviour using ip neigh show.