# rust-iproute2

[English](README.md) | [中文](README.zh-CN.md)

Cross-platform `ip` / `bridge` / `ss` commands that bring the Linux iproute2 CLI
experience to **macOS / Windows / Linux**, with usage and output aligned to real
Linux iproute2.

## Installation

**macOS (Homebrew)**

```bash
brew tap hhktony/rust-iproute2
brew install rust-iproute2
```

**Windows (Scoop / Winget)**

```powershell
scoop bucket add hhktony https://github.com/hhktony/scoop-rust-iproute2
scoop install rust-iproute2
# or
winget install hhktony.rust-iproute2
```

**Any platform (mise)**

```toml
# ~/.config/mise/config.toml
[tools]
"github:hhktony/rust-iproute2" = { version = "0.1.0", exe = "ip" }
```

> Installing multiple binaries (`bridge`/`ss`) from a single release via mise is
> still evolving (see [jdx/mise#8266](https://github.com/jdx/mise/discussions/8266));
> use Homebrew/Scoop or build from source for `bridge`/`ss` meanwhile.

**From source**: see [Build](#build) below. After install, all of `ip` /
`bridge` / `ss` are available.

## Design

- **Wraps system commands** — no netlink/FFI dependency; invokes each platform's
  native commands and parses their output.
  - **Linux**: passes through the system's real `ip`/`ss`/`bridge` (output is the
    golden standard).
  - **macOS**: wraps `ifconfig`/`netstat`/`ndp`/`arp`/`route`/`networksetup`.
  - **Windows**: wraps native `ipconfig /all`, `route print`, `netstat -ano`,
    `arp -a` (parsed locale-independently, by value).
- **Architecture**: a `core` library (data model + formatter + dispatch,
  platform-agnostic) plus per-platform `Provider`s. macOS and Windows share the
  same formatter, so output consistency is guaranteed structurally.

## Build

```bash
cargo build --release   # produces target/release/{ip,bridge,ss}
cargo test              # run all tests
```

## Supported commands

```bash
# Link (interfaces)
ip link                 ip -br link            ip link show en0
ip link set dev en0 up                          # needs root (auto sudo on macOS)
ip link set dev en0 mtu 9000
ip link set dev en0 address random|factory|<MAC>

# Address
ip addr                 ip -4 addr             ip -br addr
ip addr add 10.0.0.5/24 dev en0
ip addr del 10.0.0.5 dev en0

# Route
ip route                ip -6 route            ip route get 8.8.8.8
ip route add 192.168.0.0/16 via 10.0.0.1
ip route del 192.168.0.0/16
ip route flush table main

# Neighbour (ARP/NDP)
ip neigh                ip -4 neigh            ip neigh show dev en0
ip neigh flush dev en0

# Bridge
bridge link             bridge link show dev en2

# Socket statistics
ss                      ss -t -a               ss -nat        ss -s

# Common options
-j[son]  -p[retty]  -c[olor][=always|auto|never]  -br[ief]  -o[neline]  -4  -6
```

Commands, subcommands, and long options all support iproute2-style unambiguous
prefix abbreviations (`ip a`, `ip ro`, `ss -nat`, etc.).

## Privilege

Write operations require admin privileges: **macOS auto-prepends `sudo`**
(prompts for password); **Linux** passes through natively (the underlying tool
errors when not root); **Windows** must be run in an elevated terminal.

## License

MIT