How to Use the ndp Command in macOS Terminal to Inspect and Manage IPv6 Neighbor Discovery Tables

As corporate, academic, and home networks transition from legacy IPv4 addressing to IPv6, the mechanisms used by host operating systems to discover adjacent network devices, map physical link-layer addresses, and resolve gateway routers have fundamentally changed. While IPv4 relies on the Address Resolution Protocol (ARP) and broadcast frames, IPv6 replaces broadcasts with the Neighbor Discovery Protocol (NDP) running over Internet Control Message Protocol version 6 (ICMPv6). In Apple macOS, network engineers and systems administrators do not use the traditional arp command to troubleshoot IPv6 connectivity. Instead, macOS provides a dedicated low-level diagnostic utility: the ndp command.

Understanding how to use the ndp command in macOS Terminal allows administrators to inspect the local IPv6 neighbor cache, examine default router advertisements, audit prefix assignment lists, delete stale link-layer mappings, and configure static host routes. This technical tutorial outlines the protocol architecture of IPv6 Neighbor Discovery on Darwin-based systems, explains the primary operational flags of the ndp command, demonstrates practical monitoring workflows, and details cache-flushing techniques.

Comparing IPv4 ARP with IPv6 Neighbor Discovery on macOS

To use ndp effectively, it is helpful to contrast how link-layer resolution operates between IPv4 and IPv6 on macOS:

Feature / Mechanism	IPv4 ARP (arp)	IPv6 Neighbor Discovery (ndp)
Underlying Protocol	Raw Ethernet frames (EtherType 0x0806).	ICMPv6 messages (EtherType 0x86DD, Next Header 58).
Discovery Method	Layer 2 Broadcasts (disrupts all nodes on the collision domain).	Solicited-Node Multicast groups (delivered only to relevant hosts).
Router Discovery	Requires manual DHCP option 3 or static default gateway.	Automatic Router Advertisements (RA) and Router Solicitations (RS).
Entry States	Static, Dynamic, Incomplete.	Incomplete, Reachable, Stale, Delay, Probe, Permanent.
Duplicate Address Detection	Gratuitous ARP (optional / non-standardised).	Built-in mandatory Duplicate Address Detection (DAD).

Querying the Entire IPv6 Neighbor Cache

The most frequent operational requirement when diagnosing IPv6 connectivity issues is inspecting the current neighbor cache (analogous to arp -a in IPv4). Open Terminal on your Mac (located in /Applications/Utilities/Terminal.app) and execute:

ndp -a

Terminal will display an inventory of all IPv6 neighbors discovered across your active network interfaces (such as Wi-Fi en0 or Ethernet en1):

Neighbor                                Linklayer Address  Netif Expire    St Flgs Prbs
fe80::1%en0                             0:11:32:45:67:89     en0 23m42s    S  R
2001:db8:85a3::8a2e:370:7334            a4:83:e7:2b:11:04    en0 18m11s    R
fe80::1045:88ff:fe21:33ab%en0          12:45:88:21:33:ab    en0 permanent  R  R

Understanding the tabular column fields is vital for precise network auditing:

• Neighbor: The IPv6 address of the remote node. Notice that Link-Local addresses (prefixed with fe80::) include a zone index suffix (e.g., %en0) identifying the egress interface.
• Linklayer Address: The physical MAC (hardware) address associated with the target IPv6 node.
• Netif: The local network interface binding.
• Expire: The remaining time before the entry is re-validated or evicted from memory.
• St (State): The reachability state of the node under RFC 4861 (R for Reachable, S for Stale, D for Delay, P for Probe).
• Flgs (Flags): Operational flags such as R (indicates the node is an authoritative IPv6 router).

Querying Default IPv6 Routers via Router Advertisements

In IPv6 networks, routers periodically broadcast unsolicited ICMPv6 Router Advertisements (Type 134) or respond to Router Solicitations from your Mac. To inspect the list of upstream IPv6 gateways currently recognised by macOS:

ndp -r

The output lists each default gateway router, its link-local address, lifetime, and priority:

fe80::1%en0 if=en0, flags=0<>, pref=medium, expire=29m45s

If your Mac cannot access external IPv6 websites (such as Google or Cloudflare over IPv6), checking ndp -r quickly confirms whether your local router is correctly issuing advertisements or if the lifetime counter has expired.

Auditing On-Link IPv6 Address Prefixes

IPv6 Stateless Address Autoconfiguration (SLAAC) allows your Mac to derive its global IP address by combining an advertised network prefix with its local interface identifier. To audit the active prefix assignments broadcast by your network gateway:

ndp -p

Terminal prints the advertised subnets and validation timers:

2001:db8:abcd:0001::/64 if=en0, flags=20<ONLINK,AUTONOMOUS>, vltime=2592000, pltime=604800, expire=29d23h

• ONLINK: Specifies that nodes within this /64 subnet are physically attached to the same broadcast domain and reachable without traversing a router.
• AUTONOMOUS: Permits macOS to configure its own IPv6 interface address autonomously using SLAAC.

Deleting and Flushing Stale IPv6 Neighbor Entries

When network hardware is replaced, or when a misconfigured device triggers an IP address collision, stale MAC mappings in the neighbor cache can black-hole traffic. You can target and remove specific entries using the -d flag (requires elevated administrative privileges):

sudo ndp -d 2001:db8:85a3::8a2e:370:7334

The console confirms deletion:

2001:db8:85a3::8a2e:370:7334 (2001:db8:85a3::8a2e:370:7334) deleted

To flush all discovered neighbor entries across all active interfaces simultaneously without rebooting your Mac:

sudo ndp -c

Executing ndp -c instantly clears dynamic mappings, forcing macOS to re-initiate ICMPv6 Neighbor Solicitation multicasts upon the next outbound packet transmission.

Adding Static IPv6 Neighbor Mappings

In secure lab configurations or embedded hardware testing environments where multicast traffic is disabled or firewalled, you can establish static link-layer mappings manually:

sudo ndp -s 2001:db8:1::50 00:11:22:33:44:55

To create a static entry on a Link-Local address, ensure you specify the interface scope:

sudo ndp -s fe80::50%en0 00:11:22:33:44:55

Troubleshooting Common macOS IPv6 NDP Issues

When auditing IPv6 routing and neighbor tables on macOS, be aware of these common network pitfalls:

• Missing Scope Identifier on Link-Local Addresses: Link-local addresses (fe80::/10) are ambiguous without specifying the interface. Attempting to run ndp -d fe80::1 without appending %en0 will return an Invalid argument error. Always suffix the interface name.
• Host State Stuck in “Stale”: Under RFC 4861, reaching a Stale state is normal behavior when no packets have been exchanged for several minutes. macOS will automatically transition the entry to Delay and Probe when fresh traffic is transmitted.
• ICMPv6 Firewall Filtering: If ndp -a displays neighbors as incomplete, verify that upstream switches or local macOS packet filters (such as pf) are not blocking ICMPv6 packet types 133 through 137.

Mastering the ndp command in macOS Terminal provides direct visibility into the foundation of your network stack, ensuring seamless IPv6 diagnostics, rapid cache management, and dependable client routing.