# bandwhich — Terminal Bandwidth Utilization by Process and Connection

> bandwhich is a CLI tool that shows which process, connection, or remote host is using your bandwidth in real time. Finally answer "what is eating my network?" without opening Wireshark.

## Install

Save in your project root:

# bandwhich — Terminal Bandwidth Monitor

## Quick Use
```bash
# Install
brew install bandwhich        # macOS
cargo install bandwhich       # from source
sudo apt install bandwhich    # Debian/Ubuntu

# Needs raw-socket permission
sudo bandwhich
# Or set capability once:
sudo setcap cap_net_raw+ep $(which bandwhich)
bandwhich
```

## Introduction
When your network is mysteriously saturated, the question "what is using my bandwidth?" usually ends in a 20-minute Wireshark dive. bandwhich answers it in a single command: a live terminal table of processes, remote hosts, and connections, sorted by bandwidth usage.

With over 11,000 GitHub stars, bandwhich is a favorite among sysadmins and power users. It's a Rust rewrite of nethogs + iftop conceptually, with a cleaner UI and better accuracy.

## What bandwhich Does
bandwhich captures packets using libpcap/PF_RING, correlates them to processes via /proc or kernel APIs (depending on OS), and renders three tables: **Processes** (bandwidth per process), **Remote Hosts** (bandwidth per destination), and **Connections** (each TCP/UDP flow). Each updates live with rx/tx rates.

## Architecture Overview
```
[bandwhich (Rust)]
      |
[Packet capture]
   libpcap / BPF on macOS/BSD
   PF_RING / af_packet on Linux
      |
[Process attribution]
   Linux: /proc/net/tcp + /proc/<pid>/fd
   macOS: lsof fallback
   Windows: IP Helper API
      |
[Live aggregation]
   per-process, per-connection, per-host
   rolling byte counters
      |
[Terminal UI]
   3 tables: Processes / Remote Hosts / Connections
   sort by total / up / down
```

## Self-Hosting & Configuration
```bash
# Raw output (for scripting, CSV-able)
sudo bandwhich --raw

# Filter by specific interface
sudo bandwhich -i eth0

# Don't resolve DNS (hostnames will be shown as IPs)
sudo bandwhich -n

# Show totals instead of rates
sudo bandwhich --total-utilization

# Show only processes matching a name pattern
sudo bandwhich --show-dns --raw | grep -i firefox

# Common workflow: "who is eating my uplink?"
sudo bandwhich
# (scan processes, spot the hog, then narrow down with tcpdump if needed)
```

```bash
# Persistent install with capability (no sudo needed)
sudo setcap cap_net_raw,cap_sys_ptrace+eip $(which bandwhich)
bandwhich
# (cap_sys_ptrace needed to peek at other users' sockets on Linux)
```

## Key Features
- **Per-process bandwidth** — see exactly which app is using network
- **Per-host bandwidth** — which remote server is receiving your traffic
- **Per-connection view** — every active TCP/UDP flow, sortable
- **DNS resolution** — hostnames instead of raw IPs (optional)
- **Live updates** — 1s refresh with smoothed rates
- **Interface selection** — focus on eth0 vs wlan0 vs tun0 (VPN)
- **Raw mode** — CSV output for scripting, alerting, logging
- **Cross-platform** — Linux, macOS, Windows, FreeBSD

## Comparison with Similar Tools
| Feature | bandwhich | nethogs | iftop | nload | vnStat |
|---|---|---|---|---|---|
| Per-process view | Yes | Yes (primary) | No | No | No |
| Per-connection view | Yes | No | Yes | No | No |
| Per-host view | Yes | No | Yes (primary) | No | Yes (historical) |
| Live updates | Yes | Yes | Yes | Yes | No (history) |
| Cross-platform | Yes | Linux-first | Unix | Unix | Unix |
| Historical stats | No | No | No | No | Yes (focus) |
| Best For | Who is using bandwidth now | Per-process on Linux | Flow-level debugging | Quick rate overview | Long-term stats |

## FAQ
**Q: Why does bandwhich need sudo?**
A: Raw sockets (to capture packets) and process-table reads require privilege. One-time `setcap` grant is a nicer permanent solution than sudoing every run.

**Q: Is it accurate?**
A: Yes — counts bytes at packet layer. Occasionally under-reports processes that use namespaces in unusual ways (Docker host mode is fine; some VPN clients can be tricky).

**Q: Can I monitor a remote server?**
A: Not directly — bandwhich is for local interfaces. For remote monitoring, run it over SSH: `ssh host -t 'sudo bandwhich'`.

**Q: Does it capture full packets?**
A: No — only headers (size + source/dest IPs + ports). No payload is recorded, so it's privacy-safe and uses negligible CPU.

## Sources
- GitHub: https://github.com/imsnif/bandwhich
- License: MIT

---
Source: https://tokrepo.com/en/workflows/078ff42d-3859-11f1-9bc6-00163e2b0d79
Author: AI Open Source