tcptop/README.md

tcptop

A real-time, top-like TUI for per-connection network statistics, powered by eBPF.

Features

• Real-time per-connection view (bytes, packets, latency, state)
• eBPF-based kernel tracing (low overhead, no polling)
• Sortable table with mnemonic keys and column navigation
• Live text filtering (/ to search)
• Process attribution (PID and process name)
• TCP and UDP support with protocol filtering
• CSV logging mode for offline analysis (--log)
• Bootstraps pre-existing connections on startup
• Graceful privilege handling (clear error when not root)

Requirements

• Linux kernel 5.15+ (BTF support required for eBPF CO-RE)
• Root privileges (sudo) -- required for eBPF program loading

Installation

From .deb / .rpm

Download the latest package from the Releases page.

# Debian / Ubuntu
sudo dpkg -i tcptop_0.1.0_amd64.deb

# Fedora / RHEL
sudo rpm -i tcptop-0.1.0.x86_64.rpm

For building packages from source, see doc/PACKAGING.md.

From source

See Building from Source below.

Usage

sudo tcptop

CLI flags

Flag	Description
--port <PORT>	Filter by port (matches source or destination)
--pid <PID>	Filter by process ID
--process <NAME>	Filter by process name (substring match)
-i, --interface <IFACE>	Network interface to monitor
--tcp	Show only TCP connections
--udp	Show only UDP connections
--interval <SECS>	Refresh interval in seconds (default: 1)
--log <FILE>	Log connection data to CSV file (headless mode, no TUI)

Keyboard shortcuts

Key	Action
q / Ctrl-C	Quit
j / Down	Scroll down
k / Up	Scroll up
/	Enter filter mode
Esc	Clear filter
Enter	Confirm filter / Sort by selected column
Tab / Right	Next column
Shift-Tab / Left	Previous column
?	Toggle help overlay
c	Toggle extra columns
r / R	Sort by rate in / rate out
p / P	Sort by PID / protocol
n	Sort by process name
s	Sort by state
t	Sort by RTT
a / A	Sort by local / remote address

Examples

# Monitor HTTPS traffic (TCP only, port 443)
sudo tcptop --port 443 --tcp

# Watch a specific process with 2-second refresh
sudo tcptop --pid 1234 --interval 2

# Log all connections to CSV for offline analysis
sudo tcptop --log connections.csv

Building from Source

Prerequisites

• Rust nightly toolchain -- pinned to nightly-2026-03-20 via rust-toolchain.toml
• bpf-linker -- install with cargo install bpf-linker
• LLVM 21+ -- required by bpf-linker on some systems

Build

cargo build --release -p tcptop

The binary will be at target/release/tcptop.

Note: This project does not use cargo xtask. The eBPF program is compiled automatically via aya-build in build.rs.

License

MIT