119 lines
3.0 KiB
Markdown
119 lines
3.0 KiB
Markdown
# 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](https://github.com/zrowitsch/tcptop/releases) page.
|
|
|
|
```sh
|
|
# 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](doc/PACKAGING.md).
|
|
|
|
### From source
|
|
|
|
See [Building from Source](#building-from-source) below.
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
# 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
|
|
|
|
```sh
|
|
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](LICENSE)
|