Local Interface & Routing State (iproute2)

When to Use This Skill

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

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:

# 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

Quick Reference

Objects

Common Verbs

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