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

HEAD

• No changes yet

v1.7.6

• Fix https://github.com/brona/iproute2mac/issues/81, ss -l now shows only LISTENING sockets.

v1.7.5

• Address https://github.com/brona/iproute2mac/issues/80, migrate to subprocess.run()

v1.7.4

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

v1.7.3

• 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)

v1.7.2

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

v1.7.1

• 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)

v1.7.0

• 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)

v1.0 ~ v1.6

v1.6.0

• 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)

v1.5.4

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

v1.5.3

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

v1.5.2

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

v1.5.1

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

v1.5.0

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

v1.4.2

• -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)

v1.4.1

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

v1.4.0

• Internal cleanup and code style changes
• Added support for blackhole routes ip route add blackhole 192.0.2.0/24 (thanks @mhio)
• ⚠️ 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

v1.3.0

• Migrated to Python 3

v1.2.3

• Fixed issues with ip route on macOS Catalina (thanks @jiegec)
• ip route now returns host addresses (thanks @crvv)
• Added ip route flush cache (thanks @npeters)
• Added ip route replace 192.0.2.0/24 dev utun1 (thanks @npeters)
• Added ip addr add 192.0.2.1/32 peer 192.0.2.1 dev utun1 (thanks @npeters)

v1.2.2

• Fixed argument handling while using ip -4 (thanks @bsholdice)
• Fixed ip help (thanks @KireinaHoro)

v1.2.1

• Fixed error return codes and test script
• ip neigh flush now requires specific device (consistent behaviour with iproute2)

v1.2.0

• Enhanced input parsing to support arbitrary length commands (thanks @deployable)
• Added simple test script (thanks @deployable)
• Fixed error return codes to simulate iproute2
  (currently, help messages are inconsistently printed to stderr for all errors, unlike in iproute2)

v1.1.2

• ip route get now correctly shows src for IPv6 addresses (thanks @codeaholics)

v1.1.1

• Added dev option to ip route add command (thanks @ThangCZ)

v1.1.0

• Added source IP address to ip route get command
• Accepted to Homebrew master branch, tap is no longer supported

v1.0.9

• Fixed versioning

v1.0.8

• Better error handling and error messages (thanks @rgcr)

v1.0.7

• Help messages are now sent to stderr (thanks @rgcr)

v1.0.6

• Fixed ip -6 neigh failing for N status flag

v1.0.5

• Added s shortcuts to show commands (thanks @vmoutoussamy)

v1.0.4

• Added ip neigh flush (thanks @ThangCZ)
• Added dev option to ip neigh show and ip neigh flush

v1.0.3

• Fixed ifconfig: dev: bad value in ip addr del

v1.0.2

• Interface name is concatenated to ip addr inet rows

Authors

See AUTHORS.

Used software/code:

• macgen.py - Function for generating random MAC address
• SpoofMAC - Code for obtaining factory default MAC address for interface

License

• The MIT License (MIT)