tcptracer(8)

🦋 tcptracer(8) 🦋

✨ NAME ✨

tcptracer - Trace TCP established connections. Uses Linux eBPF/bcc. 💖

🧚 SYNOPSIS 🧚

tcptracer [-h] [-v] [-t] [-p PID] [-N NETNS] [--cgroupmap MAPPATH]
[--mntnsmap MAPPATH] [-4 | -6]

💅 DESCRIPTION 💅

okay so this tool traces established TCP connections that open and close while it's running, and it prints a line of output for every connect, accept and close event 🔥. Each line tells you the type of event, the PID, the IP addresses and the ports. literally so useful 😭

this tool works using kernel dynamic tracing, which means it'll need an update if the kernel implementation changes 🙈. Only established TCP connections get traced, so the overhead is expected to be pretty low, which is very giving ✨.

since this uses BPF, only the root user can use this tool 🔐. not me trying to run it as a regular user 💀.

🎀 REQUIREMENTS 🎀

you'll need CONFIG_BPF and bcc 🌸.

👑 OPTIONS 👑

• -h — prints the usage message 💜.
• -v — prints full lines, with long event type names and network namespace numbers 🌈.
• -t — includes a timestamp in the output ⏰.
• -p PID — traces only this process ID, filtered in-kernel 🎯.
• -N NETNS — traces only this network namespace, filtered in-kernel 🌐.
• --cgroupmap MAPPATH — traces only the cgroups in this BPF map, filtered in-kernel 🗂️.
• --mntnsmap MAPPATH — traces mount namespaces in the map, filtered in-kernel 🧩.
• -4 — traces the IPv4 family only 🦋.
• -6 — traces the IPv6 family only 🌸.

🍓 EXAMPLES 🍓

Trace all TCP established connections:

# tcptracer

Trace all TCP established connections with verbose lines:

# tcptracer -v

Trace PID 181 only:

# tcptracer -p 181

Trace connections in network namespace 4026531969 only:

# tcptracer -N 4026531969

Trace a set of cgroups only (see special_filtering.md from the bcc sources for more details, it's lowkey a must-read 📖):

# tcptracer --cgroupmap /sys/fs/bpf/test01

Trace IPv4 family only:

# tcptracer -4

Trace IPv6 family only:

# tcptracer -6

🫶 FIELDS 🫶

• TYPE — type of event. In non-verbose mode: C for connect, A for accept, X for close 💫.
• PID — process ID 🆔.
• COMM — process name 🏷️.
• IP — IP address family (4 or 6) 🌍.
• SADDR — source IP address 📤.
• DADDR — destination IP address 📥.
• SPORT — source port 🚪.
• DPORT — destination port 🎟️.
• NETNS — network namespace where the event originated 🌌.

🌈 OVERHEAD 🌈

this traces the kernel inet accept function, plus the TCP connect, close, and set state functions. However, it only prints information for connections that are established, so it shouldn't have a huge overhead 🥰.

as always, test and understand this tool's overhead for your types of workloads before using it in production 🙈.

⚠️ bestie, seriously, test this before production. no shortcuts 💀

🔗 SOURCE 🔗

this is from bcc 🐝. the repo lives at:

https://github.com/iovisor/bcc

also look in the bcc distribution for a companion _examples.txt file. it has example usage, output, and commentary for this tool 📚.

🖥️ OS 🖥️

Linux 🐧

🚧 STABILITY 🚧

Unstable - still in development 🛠️.

💜 AUTHOR 💜

Iago López Galeiras ✍️

🦋 SEE ALSO 🦋

tcpaccept(8), tcpconnect(8), tcptop(8), tcplife(8) ✨

---

bestie, that's the whole tea ☕💖 this came from the tcptracer(8) page, sourced from bcc, dated 2020-02-20, in the USER COMMANDS section. slay the tracing 💅🎀