242bf7e9e2
- All CLI flags documented with detailed descriptions - EXAMPLES section with 5 common use cases including CSV logging - EXIT STATUS, REQUIREMENTS, and SEE ALSO sections - Documents eBPF kernel probes and privilege requirements
145 lines
3.4 KiB
Groff
145 lines
3.4 KiB
Groff
.TH TCPTOP 1 "2026-03-22" "tcptop 0.1.0" "User Commands"
|
|
.SH NAME
|
|
tcptop \- real-time per-connection network monitor
|
|
.SH SYNOPSIS
|
|
.B tcptop
|
|
[\fIOPTIONS\fR]
|
|
.SH DESCRIPTION
|
|
.B tcptop
|
|
displays live per-connection TCP and UDP statistics in a sortable terminal
|
|
table. It uses eBPF to trace kernel network events with minimal overhead,
|
|
providing real-time visibility into bytes, packets, bandwidth rates, RTT,
|
|
and connection state per process.
|
|
.PP
|
|
The display consists of a summary header showing aggregate statistics
|
|
(total connections, total bandwidth in and out) and a scrollable,
|
|
sortable table of individual connections. Each row shows the protocol,
|
|
local and remote addresses, process information, byte and packet counts,
|
|
bandwidth rates, RTT estimate, and TCP state.
|
|
.PP
|
|
Requires root privileges (or CAP_BPF + CAP_PERFMON capabilities) to attach
|
|
eBPF programs to kernel probes. Exits with code 77 if insufficient
|
|
privileges are detected.
|
|
.PP
|
|
When invoked with the
|
|
.B \-\-log
|
|
option, tcptop runs in headless mode: it skips the TUI entirely and writes
|
|
periodic snapshots of all connection data to a CSV file. This is useful for
|
|
offline analysis or unattended monitoring.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-\-port " " \fIPORT\fR
|
|
Filter by port number. Matches either source or destination port.
|
|
.TP
|
|
.BR \-\-pid " " \fIPID\fR
|
|
Filter by process ID.
|
|
.TP
|
|
.BR \-\-process " " \fINAME\fR
|
|
Filter by process name (substring match).
|
|
.TP
|
|
.BR \-i ", " \-\-interface " " \fIIFACE\fR
|
|
Network interface to monitor.
|
|
.TP
|
|
.B \-\-tcp
|
|
Show only TCP connections.
|
|
.TP
|
|
.B \-\-udp
|
|
Show only UDP connections.
|
|
.TP
|
|
.BR \-\-interval " " \fISECS\fR
|
|
Refresh interval in seconds (default: 1). Controls both TUI refresh rate
|
|
and CSV snapshot cadence.
|
|
.TP
|
|
.BR \-\-log " " \fIPATH\fR
|
|
Log connection data to CSV file. Runs in headless mode (no TUI).
|
|
Overwrites existing file. Snapshots all connections at
|
|
.B \-\-interval
|
|
cadence. Each row includes a timestamp, protocol, addresses, ports,
|
|
process info, byte/packet counts, rates, and RTT.
|
|
.SH INTERACTIVE KEYS
|
|
The following keys are available in TUI mode (i.e., when
|
|
.B \-\-log
|
|
is not specified):
|
|
.TP
|
|
.BR q ", " Ctrl-C
|
|
Quit.
|
|
.TP
|
|
.B Up/Down
|
|
Scroll the connection table.
|
|
.TP
|
|
.B Left/Right
|
|
Change sort column.
|
|
.TP
|
|
.B /
|
|
Enter filter mode (filter by IP, port, or process name).
|
|
.TP
|
|
.B Esc
|
|
Clear filter.
|
|
.SH EXAMPLES
|
|
Monitor all connections:
|
|
.PP
|
|
.RS
|
|
.B sudo tcptop
|
|
.RE
|
|
.PP
|
|
Monitor only TCP connections to port 443:
|
|
.PP
|
|
.RS
|
|
.B sudo tcptop \-\-tcp \-\-port 443
|
|
.RE
|
|
.PP
|
|
Monitor a specific process:
|
|
.PP
|
|
.RS
|
|
.B sudo tcptop \-\-pid 1234
|
|
.RE
|
|
.PP
|
|
Log to CSV with 2-second intervals:
|
|
.PP
|
|
.RS
|
|
.B sudo tcptop \-\-port 443 \-\-log capture.csv \-\-interval 2
|
|
.RE
|
|
.PP
|
|
TCP only with custom refresh:
|
|
.PP
|
|
.RS
|
|
.B sudo tcptop \-\-tcp \-\-interval 2
|
|
.RE
|
|
.SH EXIT STATUS
|
|
.TP
|
|
.B 0
|
|
Normal exit.
|
|
.TP
|
|
.B 77
|
|
Insufficient privileges. The user is not root and does not have the
|
|
required capabilities (CAP_BPF + CAP_PERFMON).
|
|
.SH REQUIREMENTS
|
|
Linux kernel 5.8 or later with eBPF support.
|
|
.B tcptop
|
|
attaches kprobes and tracepoints to the following kernel functions:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
tcp_sendmsg
|
|
tcp_recvmsg
|
|
udp_sendmsg
|
|
udp_recvmsg
|
|
inet_sock_set_state
|
|
.fi
|
|
.RE
|
|
.PP
|
|
The nightly Rust toolchain and
|
|
.B bpf-linker
|
|
are required to compile the eBPF programs from source. Pre-built
|
|
.B .deb
|
|
and
|
|
.B .rpm
|
|
packages include the compiled binary and do not require these build tools.
|
|
.SH SEE ALSO
|
|
.BR top (1),
|
|
.BR ss (8),
|
|
.BR netstat (8),
|
|
.BR bpftool (8)
|
|
.SH AUTHORS
|
|
tcptop contributors.
|