iproute2mac

CLI wrapper for basic network utilities on macOS, inspired by iproute2 on Linux systems – ip, bridge and ss commands

Provided functionality is limited and command output is not fully compatible with [iproute2].
Goal of this project is to make basic network configuration/debug tasks on macOS easy for admins who already use Linux systems.
For advanced usage use netstat, ifconfig, ndp, arp, route and networksetup directly.

If you are interested in contributing, please see our Contribution Guidelines.

Installation

A) [Preferred] Using Homebrew (Maintained by @brona):

# [Optional] Install Homebrew first, see http://brew.sh for options
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install iproute2mac
brew install iproute2mac

See https://formulae.brew.sh/formula/iproute2mac and iproute2mac.rb for mode details.

B) Manual installation from HEAD:

sudo mkdir /usr/local/iproute2mac
sudo chown -R $(whoami):admin /usr/local/iproute2mac
cd /usr/local/
git clone https://github.com/brona/iproute2mac.git
ln -s iproute2mac/src/ip.py /usr/local/bin/ip
ln -s iproute2mac/src/bridge.py /usr/local/bin/bridge
ln -s iproute2mac/src/ss.py /usr/local/bin/ss

C) Using MacPorts (Maintained by @i0ntempest):

See https://ports.macports.org/port/iproute2mac/ and Portfile

D) Using NixOS (Maintained by @jiegec):

See https://search.nixos.org/packages?show=iproute2mac&type=packages&query=iproute2mac and package.nix

Supported commands / Example usage

Goal of this utility is to provide compatible CLI with [iproute2], supporting same command shortcuts and user experience.

• Help
  • ip help
  • ip link help
  • ip addr help
  • ip route help
  • ip neigh help
  • bridge help
  • bridge link help
  • ss help
• Link module (Interfaces)
  • List local interfaces ip link
  • List interfaces in brief format ip -br link
  • Show one interface ip link show en0
  • Shutdown interface ip link set dev en0 down
  • Start interface ip link set dev en0 up
  • Set custom MAC address ip link set dev en0 address 00:12:34:45:78:90
  • Set random MAC address ip link set en0 address random
  • Set factory default MAC address ip link set en0 address factory
  • Set MTU ip link set dev en0 mtu 9000
• Neighbour module (ARP/NDP)
  • Show all neighbours ip neigh
  • Show all IPv4 (ARP) neighbours ip -4 neigh
  • Show all IPv6 (NDP) neighbours ip -6 neigh
  • Show all IPv4 (ARP) neighbours for a specific interface ip -4 neigh show dev en0
  • Show neighbours filtered by prefix ip -4 neigh show 192.0.2.0/24
  • IPv6 (NDP) neighbours cannot be currently shown for a specific interface
  • Flush all neighbours (IPv4 + IPv6) for a specific interface ip neigh flush dev en0
  • Flush all IPv4 (ARP) neighbours for a specific interface ip -4 neigh flush dev en0
  • IPv6 (NDP) neighbours are being flushed for all interfaces
• Address module
  • List all addresses ip addr
  • List all addresses in brief format ip -br addr
  • List IPv4 addresses ip -4 addr
  • List IPv6 addresses ip -6 addr
  • Add address to interface ip addr add 10.0.0.5/24 dev en0
  • Remove address from interface ip addr del 10.0.0.5 dev en0
• Route module
  • List IPv4 addresses ip route
  • List IPv6 addresses ip -6 route
  • Flush route cache (no-op on MacOS) ip route flush cache
  • Flush routes ip route flush table main
  • Match for specific route ip route show default
  • Get route for destination ip route get 8.8.8.8
  • Add static route ip route add 192.168.0.0/16 nexthop 10.0.0.1
  • Add default route ip route add default nexthop 10.0.0.1
  • Replace static route ip route replace 192.0.2.0/24 dev utun1
  • Remove static route ip route del 192.168.0.0/16
• Bridge module
  • List bridge interfaces bridge link
  • List one bridged interface bridge link show dev en2
• Socket Statistics (ss)
  • Show all sockets ss
  • Show listening sockets ss -l
  • Show TCP sockets ss -t
  • Show UDP sockets ss -u
  • Show IPv4 sockets ss -4
  • Show IPv6 sockets ss -6
  • Show socket statistics ss -s
  • Show all sockets (including listening) ss -a
• JSON output
  • List interfaces: ip -j link show
  • List addresses: ip -j addr show
  • List neighbours: ip -j neigh show
  • List routes: ip -j route show
  • List bridges (with pretty print): bridge -j -p link show
  • List sockets: ss -j
• Color output
  • Enable colors: ip -color link show
  • Force colors: ip -color=always link show
  • Auto colors: ip -color=auto link show
  • Disable colors: ip -color=never link show
  • Same options work for bridge and ss commands

Changelog

<details open> <summary><b>HEAD</b></summary>

• No changes yet

</details> <details open> <summary><b>v1.7.4</b></summary>

• ss -H is now supported (--no-header)

</details> <details open> <summary><b>v1.7.3</b></summary>

• Fixed https://github.com/brona/iproute2mac/issues/77, improved ip command parsing for degenerate cases.
• Fixed https://github.com/brona/iproute2mac/issues/76, ss now correctly parses getopt style arguments (e.g. ss -nat).
• Fixed https://github.com/brona/iproute2mac/issues/73, ip -4 addr shows only interfaces that have ipv4 address assigned (thanks @pluharok)
• Fixed -- and - parsing (https://github.com/brona/iproute2mac/pull/74, thanks @rrotter)

</details> <details open> <summary><b>v1.7.2</b></summary>

• Fixed ip route crashing with IndexError: pop from empty list bug introduced in v1.7.1

</details> <details open> <summary><b>v1.7.1</b></summary>

• ip addr and ip link returns results in ifindex order (https://github.com/brona/iproute2mac/issues/72)
• ip addr and ip link support up filter (https://github.com/brona/iproute2mac/issues/71)
• Added ip route list [[exact] PREFIX] selector (https://github.com/brona/iproute2mac/issues/66)

</details> <details open> <summary><b>v1.7.0</b></summary>

• Added ss command (https://github.com/brona/iproute2mac/issues/20 ,https://github.com/brona/iproute2mac/pull/70, thanks @luoling8192)
• Added -brief option for link and address modules (https://github.com/brona/iproute2mac/issues/42 ,https://github.com/brona/iproute2mac/pull/69 thanks @xraystyle)
• Added -oneline option for link and addr modules (https://github.com/brona/iproute2mac/issues/17 ,https://github.com/brona/iproute2mac/pull/62 thanks @waketzheng)

</details> <details> <summary><b>v1.0 ~ v1.6</b></summary> <details open> <summary><b>v1.6.0</b></summary>

• Added --color with auto, always and never modes for show commands (https://github.com/brona/iproute2mac/issues/21 and https://github.com/brona/iproute2mac/issues/42, PR https://github.com/brona/iproute2mac/pull/63)
• Fixed https://github.com/brona/iproute2mac/issues/68 ip neigh show not displaying lladdr in the output
• Fixed ip neigh show json output not matching iproute2 (state and router fields)

</details> <details open> <summary><b>v1.5.4</b></summary>

• Fixed https://github.com/brona/iproute2mac/issues/56 address parsing for ptp links

</details> <details open> <summary><b>v1.5.3</b></summary>

• Fixed https://github.com/brona/iproute2mac/issues/21 --color option parsing

</details> <details open> <summary><b>v1.5.2</b></summary>

• Fixed https://github.com/brona/iproute2mac/issues/57

</details> <details open> <summary><b>v1.5.1</b></summary>

• Fixed https://github.com/brona/iproute2mac/issues/56

</details> <details open> <summary><b>v1.5.0</b></summary>

• Added -json option (https://github.com/brona/iproute2mac/issues/49)
• Added bridge command
• Internal reworking of ip ... show functions

</details> <details open> <summary><b>v1.4.2</b></summary>

• -color option is now being ignored (https://github.com/brona/iproute2mac/issues/47, thanks @lexhuismans)
• Added support for double dashed options,
  e.g. --color as well as -color
• ip route add now ignores 2 additional arguments,
  e.g. ip r a 1.1.1.1 via 2.2.2.2 dev utun5 is interpreted as ip r a 1.1.1.1 via 2.2.2.2 (https://github.com/brona/iproute2mac/issues/45)

</details> <details open> <summary><b>v1.4.1</b></summary>

• Fixed ip neigh show dev en0 (https://github.com/brona/iproute2mac/issues/43, thanks @SimonTate)

</details> <details open> <summary><b>v1.4.0</b></summary>

• Internal cleanup and code style changes
• Added support for blackhole routes ip route add blackhole 192.0.2.0/24 (thanks @mhio)
• :warning: ip route flush cache no longer flushes anything
• ip route flush table main flushes all routes
• ip neigh show 192.0.2.0/24 filters neighbours
• Flag compatibility for -help and -Version
• Uniform matching for show command alternatives

</details> <details open> <summary><b>v1.3.0</b></summary>

• Migrated to Python 3

</details> <details open> <summary><b>v1.2.3</b></summary>

• Fixed issues with ip route on macOS Catalina (thanks @jiegec)
• ip route now returns host addr