interface-state

created	"2026-07-12T00:00:00.000Z"
modified	"2026-07-12T00:00:00.000Z"
reviewed	"2026-07-12T00:00:00.000Z"
name	interface-state
description	Local interface, address, route, and neighbor state with iproute2. Use when viewing or configuring a host's own IPs, links, routes, or ARP/NDP cache — the ifconfig/route/arp replacement.
user-invocable	false
allowed-tools	Bash(ip *), Bash(bridge *), Read, Grep, Glob, TodoWrite

Local Interface & Routing State (iproute2)

When to Use This Skill

Scenario	Use this skill	Alternative
Show a host's own IP addresses and interfaces	Yes (ip -br a)
Check interface up/down state and MAC addresses	Yes (ip -br link)
Inspect the routing table or which route a destination takes	Yes (ip route, ip route get)
Read the ARP/NDP neighbor cache	Yes (ip neigh)
See per-interface RX/TX counters, errors, drops	Yes (ip -s link)
Script host network state as JSON	Yes (ip -j … | jq)
Add/remove addresses, bring links up/down, edit routes	Yes (root)
Watch link/addr/route changes live	Yes (ip monitor)
Trace the route or diagnose latency to a remote host		network-diagnostics (trippy, gping)
Find what process is listening on a port		network-diagnostics (ss)
Enumerate hosts on the local L2 segment		layer2-discovery (arp-scan, LLDP)
Discover which switch port a host is on		layer2-discovery (lldpcli)
Scan open ports on a remote host		network-discovery (RustScan, nmap)
Resolve DNS records for a domain		dns-tools (dog, dig)
Monitor per-process bandwidth		network-monitoring (bandwhich)
Load test an HTTP endpoint		http-load-testing (oha)

Expert knowledge for inspecting and configuring a Linux host's own Layer 2/3 state — addresses, links, routes, and the neighbor cache — with the iproute2 ip command. This is the modern replacement for the entire net-tools suite: ifconfig, route, arp, and netstat -i/-r.

Platform note: ip (iproute2) is Linux-only. On macOS the equivalents are ifconfig, netstat -rn, route -n get, and arp -a; this skill targets Linux hosts and the many containers/VMs/servers you shell into.

iproute2 as the net-tools Replacement

Legacy (net-tools)	Modern (iproute2)	Shows
ifconfig	ip addr / ip a	Addresses per interface
ifconfig -a	ip link / ip l	Link state, MAC, MTU
route -n	ip route / ip r	Routing table
arp -a	ip neigh / ip n	ARP/NDP neighbor cache
netstat -i	ip -s link	Per-interface counters
netstat -g	ip maddr	Multicast group membership
ifconfig eth0 up	ip link set eth0 up	Bring interface up
ifconfig eth0 1.2.3.4/24	ip addr add 1.2.3.4/24 dev eth0	Assign address
route add …	ip route add …	Add a route

net-tools is unmaintained and blind to modern kernel features (multiple routing tables, policy rules, VRFs, network namespaces, IPv6 details). Prefer ip on any Linux host.

Global Flags — the Throughline

These modify any ip object and compose freely. The first three are the core habit:

Flag	Long form	Effect
-c	-color	Colorize output (state/scope highlighted)
-br	-brief	One tidy aligned line per entry (the columnar view)
-r	-resolve	Reverse-DNS resolve addresses
-j	-json	Machine-readable JSON (pipe to jq)
-p	-pretty	Pretty-print (pair with -j)
-s	-stats	Include statistics (repeat -s -s for more)
-4 / -6		Restrict to IPv4 / IPv6 only

# The compact colorized address table (memorable as the `ipa` shortcut)
ip -color -brief -resolve addr      # short: ip -c -br -r a

# Same treatment on other objects
ip -c -br link                      # interfaces: state + MAC, one line each
ip -c -br neigh                     # neighbor cache, columnar
ip -c route                         # colorized routing table

Every ip object accepts unambiguous abbreviations: ip a, ip l, ip r, ip n, ip ru (rule), ip m (maddr).

Read-Only Inspection

Addresses & Links

ip -br a                    # addresses, one line per interface
ip -br a show up            # only interfaces that are UP (filters noise)
ip -4 -br a                 # IPv4 only
ip a show eth0              # full detail for one interface
ip -br link                 # L2 view: state, MAC, MTU — no IPs
ip link show eth0           # one interface's link details

Routing

ip route                            # full routing table
ip route get 1.1.1.1                # WHICH route/interface a destination uses
ip route get 1.1.1.1 from 10.0.0.5  # source-based route selection
ip -6 route                         # IPv6 routing table
ip route show table all             # every routing table (policy routing)

ip route get answers "why is this traffic leaving the wrong interface?" — it reports the exact route, source address, and egress device the kernel picks.

Neighbors (ARP/NDP)

ip neigh                    # ARP (v4) + NDP (v6) cache
ip -br neigh                # columnar
ip neigh show dev eth0      # neighbors on one interface

Neighbor states: REACHABLE (confirmed), STALE (cached, unverified), DELAY/PROBE (revalidating), FAILED (unreachable), PERMANENT (static).

Statistics

ip -s link                  # RX/TX bytes, packets, errors, drops per interface
ip -s -s link show eth0     # extended error breakdown for one interface

First stop for "is this NIC dropping packets?" — check the errors/dropped columns.

JSON + jq Scripting — the Real Reason to Learn ip

ip -j emits structured JSON, so scripts parse fields reliably instead of scraping ifconfig text that varies across versions.

# Pretty-printed full address dump
ip -j -p addr

# All IPv4 addresses on the host, one per line
ip -j addr | jq -r '.[].addr_info[] | select(.family=="inet") | .local'

# Primary IP of a specific interface
ip -j addr show eth0 | jq -r '.[0].addr_info[] | select(.family=="inet") | .local'

# Interfaces that are operationally UP
ip -j link | jq -r '.[] | select(.operstate=="UP") | .ifname'

# Default gateway
ip -j route | jq -r '.[] | select(.dst=="default") | .gateway'

# Neighbor cache as ip→mac pairs
ip -j neigh | jq -r '.[] | "\(.dst)\t\(.lladdr // "-")\t\(.state[0])"'

Watching Changes Live

ip monitor                  # stream ALL link/addr/route/neigh changes
ip monitor link             # just interface up/down events
ip monitor address          # address add/remove (watch DHCP renewals)
ip monitor route            # routing table changes

ip monitor is invaluable for catching a flapping interface, a DHCP lease renewal, or a VPN altering routes — it prints events as they happen.

Modern Subsystems net-tools Never Covered

ip rule                     # policy routing rules (which table applies to what)
ip route show table 100     # a specific non-main routing table
ip netns list               # network namespaces (the base under containers)
ip netns exec <ns> ip -br a # run any command inside a namespace
ip -br link show type vlan   # VLAN interfaces
ip -d link show <dev>        # -d = driver/type detail (bond, bridge, vxlan…)
bridge -c fdb show           # bridge forwarding DB (iproute2 bridge tool)
bridge vlan show             # per-port VLAN membership on a bridge

Mutating Commands (require root)

These change live network configuration and are not persistent — they vanish on reboot unless written into the distro's network config (netplan/NetworkManager/systemd-networkd). Flagged here so they're recognizable; run deliberately.

Addresses

sudo ip addr add 10.0.0.5/24 dev eth0        # assign an address
sudo ip addr add 10.0.0.5/24 dev eth0 label eth0:1   # labeled alias
sudo ip addr del 10.0.0.5/24 dev eth0        # remove an address
sudo ip addr flush dev eth0                  # remove ALL addresses on eth0

Links

sudo ip link set eth0 up                     # bring interface up
sudo ip link set eth0 down                   # bring interface down
sudo ip link set eth0 mtu 9000               # set MTU (jumbo frames)
sudo ip link set eth0 address 02:11:22:33:44:55   # override MAC
sudo ip link add veth0 type veth peer name veth1  # create a veth pair
sudo ip link delete veth0                    # delete an interface

Routes

sudo ip route add 192.168.5.0/24 via 10.0.0.1        # add a route
sudo ip route add default via 10.0.0.1 dev eth0      # set default gateway
sudo ip route add 10.1.0.0/16 dev eth0 metric 100    # metric-weighted route
sudo ip route del 192.168.5.0/24                     # remove a route
sudo ip route replace default via 10.0.0.254         # atomically swap default

Neighbors

sudo ip neigh add 10.0.0.9 lladdr 00:11:22:33:44:55 dev eth0 nud permanent  # static ARP
sudo ip neigh del 10.0.0.9 dev eth0          # drop a neighbor entry
sudo ip neigh flush dev eth0                 # clear the cache on eth0

Common Patterns

What's my IP and gateway?

ip -br a show up                                  # human view
ip -j route | jq -r '.[] | select(.dst=="default") | .gateway'   # gateway only

Why is traffic taking the wrong path?

ip route get <dest-ip>       # exact route + source + egress interface
ip rule                      # is a policy rule diverting it to another table?
ip route show table <n>      # inspect that table

Is this interface dropping packets?

ip -s link show <dev>        # check errors / dropped counters
watch -n 1 'ip -s link show <dev> | grep -A1 RX'   # watch them climb

Namespace-aware inspection (containers)

for ns in $(ip netns list | awk '{print $1}'); do
  echo "== $ns =="; ip netns exec "$ns" ip -br a
done

Agentic Optimizations

Context	Command
Compact address table	ip -c -br -r a
Host IPv4 list	ip -j addr | jq -r '.[].addr_info[] | select(.family=="inet") | .local'
Default gateway	ip -j route | jq -r '.[] | select(.dst=="default") | .gateway'
Egress interface for a dest	ip route get <ip> | awk '{for(i=1;i<=NF;i++)if($i=="dev")print $(i+1)}'
UP interfaces only	ip -j link | jq -r '.[] | select(.operstate=="UP") | .ifname'
Interface error counts	ip -s link show <dev>
Neighbor ip→mac table	ip -j neigh | jq -r '.[] | "\(.dst) \(.lladdr // "-")"'

Quick Reference

Objects

Object	Abbrev	Purpose
address	a	IP addresses on interfaces
link	l	L2 interface state, MAC, MTU
route	r	Routing tables
neigh	n	ARP/NDP neighbor cache
rule	ru	Policy routing rules
maddr	m	Multicast group membership
netns		Network namespaces
monitor		Live change stream

Common Verbs

Verb	Meaning
show (default)	Display entries
add	Create an entry (root)
del / delete	Remove an entry (root)
set	Modify link properties (root)
replace	Atomically add-or-update (root)
flush	Remove all matching entries (root)
get	Resolve a single lookup (route get)

Troubleshooting

Object "a" is unknown, try "ip help"

Very old iproute2, or a busybox ip applet. Spell the object out (ip address) or check ip -V for the version.

RTNETLINK answers: Operation not permitted

A mutating command run without root. Prefix with sudo.

RTNETLINK answers: File exists on ip route add

The route (or a conflicting one) already exists. Use ip route replace to overwrite atomically, or ip route del first.

Address vanished after reboot

ip addr add is runtime-only. Persist it in the distro's network manager (netplan YAML, NetworkManager connection, or systemd-networkd .network).

Requirements

# iproute2 ships in the base system on essentially all Linux distros.
# If missing (minimal container images):

# Debian/Ubuntu
sudo apt install iproute2

# Alpine
apk add iproute2

# RHEL/Fedora
sudo dnf install iproute

# jq for JSON parsing (examples above)
sudo apt install jq        # or: apk add jq / dnf install jq