Wiretop

Real-time network traffic monitoring tool for the command line.

Wiretop displays bandwidth usage between host pairs on a network interface, showing which connections are consuming bandwidth and how traffic flows between hosts.

Features

• Real-time packet capture and analysis
• Traffic rates over multiple time windows (2s, 10s, 40s averages)
• Cumulative totals for each connection
• Visual bar graphs for bandwidth comparison
• DNS resolution for IP addresses
• Service name resolution for ports
• BPF filter support
• Interactive keyboard controls
• Text-only output mode for scripting
• Cross-platform support (Linux, macOS, Windows, FreeBSD)

Installation

From Source

# Clone the repository
git clone https://github.com/vyrti/wiretop.git
cd wiretop

# Build and install
cargo install --path .

Prerequisites

Linux

# Debian/Ubuntu
sudo apt install build-essential pkg-config libpcap-dev

# RHEL/Fedora
sudo dnf install gcc pkg-config libpcap-devel

# Alpine
apk add build-base pkgconfig libpcap-dev

macOS

libpcap is included with macOS. Install Xcode Command Line Tools if needed:

xcode-select --install

Windows

1. Install Npcap (recommended) or WinPcap
2. Download and install the Npcap SDK
3. Install Visual Studio Build Tools

FreeBSD

libpcap is included in the base system:

pkg install rust

Usage

Basic Usage

# Monitor default interface (requires privileges)
sudo wiretop

# Monitor specific interface
sudo wiretop -i eth0

# List available interfaces
wiretop -I

Command Line Options

OPTIONS:
    -i, --interface <NAME>     Network interface to capture on
    -I, --list-interfaces      List available network interfaces
    -f, --filter <FILTER>      BPF filter expression
    -n, --no-dns               Disable DNS resolution
    -N, --no-port-names        Disable port name resolution
    -p, --promiscuous          Enable promiscuous mode
    -t, --text                 Text-only output (no TUI)
    -o, --one-line             One-line per flow output format
    -b, --no-bars              Disable bar graph display
    -B, --bandwidth-in-bytes   Show bandwidth in bytes (default)
    -u, --bandwidth-unit       Bandwidth unit: bytes, bits, or packets
    -s, --aggregate-source     Aggregate by source address
    -d, --aggregate-dest       Aggregate by destination address
    -l, --line-limit <N>       Limit output to N lines
    -h, --help                 Print help information
    -V, --version              Print version information

Keyboard Controls (Interactive Mode)

Key	Action
q, Esc	Quit
p, P	Pause/resume display
h, ?	Show help
n	Toggle DNS resolution
N	Toggle port resolution
b	Toggle bar graph display
B, u	Cycle bandwidth units
1	Sort by 2-second rate
2	Sort by 10-second rate
3	Sort by 40-second rate
<	Sort by source
>	Sort by destination
j, Down	Scroll down
k, Up	Scroll up
g, Home	Go to top
G, End	Go to bottom
l, /	Set display filter
c	Clear display filter
o	Freeze flow order
T	Toggle totals display

Examples

# Monitor HTTP traffic only
sudo wiretop -f "tcp port 80"

# Monitor traffic to/from specific host
sudo wiretop -f "host 192.168.1.100"

# Text mode for scripting
sudo wiretop -t | tee traffic.log

# One-line format with cumulative totals
sudo wiretop -to

# Show bandwidth in bits per second
sudo wiretop -u bits

Privilege Requirements

Packet capture requires elevated privileges:

Linux

# Option 1: Run as root
sudo wiretop

# Option 2: Set capabilities (recommended)
sudo setcap cap_net_raw+ep /usr/local/bin/wiretop

macOS

# Run as root
sudo wiretop

# Or configure BPF device permissions

Windows

Run as Administrator, or install Npcap with "Allow non-admin users" option.

FreeBSD

# Run as root
sudo wiretop

# Or add user to bpf group
sudo pw groupmod bpf -m username

Configuration File

Wiretop can be configured via a TOML file:

Linux/FreeBSD: ~/.config/wiretop/config.toml macOS: ~/Library/Application Support/wiretop/config.toml Windows: %APPDATA%\wiretop\config.toml

Example configuration:

interface = "eth0"
dns_resolution = true
port_resolution = true
promiscuous = false
show_bars = true
bandwidth_unit = "bytes"
sort_method = "rate2s"

License

Dual-licensed under MIT or Apache-2.0 at your option.

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

Note: All contributions require agreement to our Contributor License Agreement (CLA).