← Full reference

ip

Network interfaces, IP addresses, routes and the ARP table — ip addr, ip link, ip route, ip neigh

ip from the iproute2 package shows and changes the network configuration: interfaces, addresses, routes, neighbors. It replaces the old ifconfig, route and arp.

Syntax

ip [options] OBJECT [command] [arguments]

The object is what you're looking at: addr, link, route, neigh, rule, netns. The default command is show (or list). Objects and commands can be abbreviated to an unambiguous prefix: ip a, ip r, ip l, ip n.

Common options

OptionMeaning
-brbrief: one line per interface — name, state, addresses
-4 / -6IPv4 only / IPv6 only
-sstatistics: bytes, packets, errors, dropped; -s -s — more detail
-ddetails: interface type, driver parameters
-oeach record on one line — handy for grep and awk
-jJSON output (-j -p — indented), then process with jq
-ccolored output
-n namerun in another network namespace

ip addr — addresses

CommandWhat it does
ip addrall interfaces and their addresses
ip addr show dev eth0addresses of one interface
ip addr show scope globalonly "real" addresses, without loopback and link-local
ip addr add 10.0.0.2/24 dev eth0add an address (the mask is required)
ip addr del 10.0.0.2/24 dev eth0delete an address
ip addr flush dev eth0delete all addresses of an interface

Reading the output:

2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP
    link/ether 6a:5d:a3:85:87:be brd ff:ff:ff:ff:ff:ff
    inet 172.17.0.5/16 brd 172.17.255.255 scope global eth0
       valid_lft forever preferred_lft forever
PartMeaning
<…UP,LOWER_UP>UP — the interface is enabled, LOWER_UP — there's a physical link ("cable plugged in")
mtu 1500maximum packet size
state UP / DOWN / UNKNOWNoperational state of the link
link/ether …MAC address
inet 172.17.0.5/16IPv4 address and prefix length; inet6 — IPv6
brdthe subnet's broadcast address
scope global / link / hostaddress for the outside world / only for its own segment / only for this machine
valid_lftaddress lifetime (finite for DHCP-assigned ones)

ip link — interfaces

CommandWhat it does
ip linkinterfaces: flags, MTU, MAC, state
ip link set eth0 up / downenable / disable an interface
ip link set eth0 mtu 1400change the MTU
ip link set eth0 address 02:00:00:00:00:01change the MAC
ip link add dummy0 type dummycreate a virtual interface (dummy, bridge, veth, vlan…)
ip link del dummy0delete a virtual interface

ip route — routes

CommandWhat it does
ip routethe main routing table
ip route show defaultonly the default route (gateway)
ip route get 1.1.1.1which route, interface and source address a packet will use
ip route add 10.10.0.0/16 via 192.168.1.1route to a network via a gateway; dev eth0 — directly via an interface
ip route add default via 192.168.1.1default gateway
ip route replace …add or replace a route with the same destination and metric
ip route del 10.10.0.0/16delete a route
ip route show table localother tables: local, main, a number; table selection rules — ip rule

A route line:

default via 172.17.0.1 dev eth0
172.17.0.0/16 dev eth0 proto kernel scope link src 172.17.0.5

default — where everything goes that didn't match other routes. via — through which gateway, dev — through which interface, src — which source address to use. proto kernel scope link — a route to the machine's own subnet, added by the kernel itself when the address was assigned. metric — priority: among several identical routes the one with the lower metric wins. Among overlapping routes the most specific one (with the longest mask) wins.

ip neigh and netns

CommandWhat it does
ip neighneighbors: IP → MAC and state (REACHABLE, STALE, FAILED)
ip neigh flush dev eth0flush the neighbor cache
ip netns listnetwork namespaces
ip netns exec name commandrun a command inside a namespace

Examples

# all interfaces and addresses, briefly
ip -br addr

# IPv4 addresses only
ip -4 -br addr

# default gateway
ip route show default

# which interface the machine will use to reach an address
ip route get 8.8.8.8

# is there a link on the interface and how many errors
ip -s link show eth0

# IP addresses as "interface address/mask" via JSON and jq
ip -j addr | jq -r '.[] | .ifname as $i | .addr_info[] | "\($i) \(.local)/\(.prefixlen)"'

# address and route by hand (requires privileges)
ip addr add 192.168.50.10/24 dev eth1
ip link set eth1 up
ip route add 10.20.0.0/16 via 192.168.50.1

Pitfalls

  • Changes don't survive a reboot. ip addr add and ip route add change only the kernel's current state. Persistent configuration lives in netplan (/etc/netplan/), NetworkManager or /etc/network/interfaces.
  • You can't change anything without privileges: RTNETLINK answers: Operation not permitted. You need root, and in a container also the NET_ADMIN capability — in the sandbox usually only viewing is available.
  • state UNKNOWN on lo and virtual interfaces is normal: they have no "cable". Look at the UP,LOWER_UP flags in angle brackets.
  • The mask is required. ip addr add 10.0.0.2 dev eth0 adds the address with a /32 mask, and no route to the subnet appears.
  • ip route add for an existing route gives RTNETLINK answers: File exists. Use replace or del first.
  • Two default routes with different metrics are a common cause of "the internet works, then it doesn't". Check ip route show default.
  • Names like eth0@if12 mean this is one end of a veth pair (usually in a container). In commands use the name without @…: dev eth0.
  • ip route get sends nothing to the network — it's only a query to the routing table.

See also

ss · dig · jq · curl