Usage — proc-trace-net

SYNOPSIS

proc-trace-net [-ctUurQ46] [-o FILE] [-p PID[,PID,...] | CMD...]

	Flag	Argument	Description
🎨	-c		Force-enable ANSI color output. Auto-detected when stdout is a tty; `NO_COLOR=1` disables it.
⏱️	-t		Show elapsed duration when a connection closes. Appends timing to the close (×) line.
🔄	-U		Show TCP state update events — ESTABLISHED, FIN_WAIT, TIME_WAIT transitions. Shown with a ⇒ marker.
👤	-u		Print owning user of each connection as `<username>`. Root in red, other users in green.
🔍	-r		Perform reverse DNS lookup on remote addresses. Replaces raw IPs with hostnames where available.
🔇	-Q		Suppress error messages (e.g. inode lookup failures). Useful for long-running background monitoring.
4️⃣	-4		Show IPv4 connections only. Mutually exclusive with `-6`.
6️⃣	-6		Show IPv6 connections only. Mutually exclusive with `-4`.
📝	-o	FILE	Append output to FILE instead of stdout. Colors are disabled for file output unless `-c` is also set.
🎯	-p	PID[,PID,...]	Only show connections owned by the given PID(s). Accepts a comma-separated list.

OUTPUT FORMAT

Anatomy of an output line

Each connection event produces one line. Symbols indicate direction and state. With -t, close lines include elapsed duration.

3892 PID — process ID in amber

curl process name (from /proc/<pid>/comm) in cyan

<root> user in red (root) or green (other) — only with -u

TCP protocol (TCP or UDP) in dim grey

10.0.2.15:54321 local address in green

→ direction: → outbound (local initiated), ← inbound (remote initiated)

← inbound connection in purple

× connection closed in red

⇒ TCP state update (ESTABLISHED, FIN_WAIT, etc.) — only with -U

93.184.216.34:443 remote address in amber

0.342s connection duration in cyan — close lines only, with -t

EXAMPLES

System-wide monitoring with color, timing, and user

The most useful default invocation. Watch every TCP/UDP connection machine-wide with colors, close timing, and user context.

system-wide (-ctu)

$ sudo proc-trace-net -ctu
 1234 sshd        <root>  TCP  10.0.2.15:22              ←  203.0.113.7:41002
 2341 systemd-r   <root>  UDP  10.0.2.15:46012           →  8.8.8.8:53
 3892 curl        <rick>  TCP  10.0.2.15:54321           →  93.184.216.34:443
 3892 curl        <rick>  TCP  10.0.2.15:54321           ×  93.184.216.34:443   0.342s

CMD mode — trace a single command

Pass a command after the flags to trace only its network connections. proc-trace-net will exit when the command completes.

cmd mode

$ sudo proc-trace-net -ct curl https://github.com
 9812 curl         TCP  10.0.2.15:48201           →  140.82.114.4:443
 9812 curl         TCP  10.0.2.15:48201           ×  140.82.114.4:443    0.218s

Close timing (-ct)

The -t flag appends connection duration to close events. Spot hung or unusually long connections at a glance.

close timing (-ct)

$ sudo proc-trace-net -ct
 5501 nginx        TCP  10.0.2.15:80              ←  192.168.1.5:52341
 5501 nginx        TCP  10.0.2.15:80              ×  192.168.1.5:52341   0.004s
 7210 postgres     TCP  10.0.2.15:5432            ←  127.0.0.1:41092
 7210 postgres     TCP  10.0.2.15:5432            ×  127.0.0.1:41092     142.001s

TCP state updates (-cU)

The -U flag shows every TCP state transition — useful for debugging connection teardown issues or TIME_WAIT accumulation.

state updates (-cU)

$ sudo proc-trace-net -cU
 3892 curl         TCP  10.0.2.15:54321           →  93.184.216.34:443
 3892 curl         TCP  10.0.2.15:54321           ⇒  93.184.216.34:443   ESTABLISHED
 3892 curl         TCP  10.0.2.15:54321           ⇒  93.184.216.34:443   FIN_WAIT
 3892 curl         TCP  10.0.2.15:54321           ×  93.184.216.34:443

PID filter — watch nginx only (-p)

Use -p with a comma-separated list of PIDs to monitor only specific processes. Combine with pgrep for dynamic PID lookup.

pid filter (-p)

$ sudo proc-trace-net -ct -p $(pgrep nginx | paste -sd,)

Log to file silently (-Qo)

Run in the background, suppressing all error noise, writing a connection log for later analysis.

background logger

$ sudo proc-trace-net -Qto /var/log/connections.log &
[1] 9981

IPv4 only (-4)

Filter to only IPv4 connections. Useful to reduce noise in dual-stack environments.

ipv4 only (-4)

$ sudo proc-trace-net -4 -ct

Reverse DNS (-r)

The -r flag resolves remote IPs to hostnames. Adds latency but makes output much more readable for auditing.

reverse dns (-r)

$ sudo proc-trace-net -ctr
 3892 curl         TCP  10.0.2.15:54321           →  server-93-184-216-34.example.com:443
 2341 systemd-r    UDP  10.0.2.15:46012           →  dns.google:53