tcpconnect.bt(8)

📦 version 0.17.0, in debian bookworm

💖 tcpconnect.bt 💖

ok so bestie, welcome to tcpconnect.bt from section 8 of the System Manager's Manual — yes, the big-girl admin section, we love her 💅

✨ NAME ✨

tcpconnect.bt — trace TCP active connections (connect()), powered by Linux bpftrace/eBPF 🌈

🦋 SYNOPSIS 🦋

tcpconnect.bt

no args, no flags, no drama. she just runs 🎀

💜 DESCRIPTION 💜

so basically this tool traces active TCP connections — think the ones you get from a connect() syscall 🫶. (accept() connections are the passive ones, so those are NOT it, bestie, they're a different vibe entirely.)

this is lowkey perfect for general troubleshooting when you wanna see what connections your local server is initiating. like, who is she calling?? 👀

every single connection attempt gets traced, even if it ultimately fails. no cap. the failures are still getting clocked 💀

how does the magic happen? it works by tracing the kernel tcp_v4_connect() and tcp_v6_connect() functions using dynamic tracing — which means if those kernel functions ever change, this tool will need updating to match them. so keep an eye out, she's sensitive 🧚

and because this uses BPF, only the root user can use this tool. sorry babe, that's just the rules 👑

🌸 REQUIREMENTS 🌸

  • CONFIG_BPF
  • bpftrace

both of them. periodt 💅

⭐ EXAMPLES ⭐

trace all active TCP connections:

# tcpconnect.bt

slay. that's the whole command. iconic behavior honestly 🔥

🍓 FIELDS 🍓

here's the tea on every column she's gonna hand you:

  • TIME(s) — the time of the call, in HH:MM:SS format ⏰
  • PID — process ID
  • COMM — process name
  • SADDR — source IP address
  • SPORT — source port
  • DADDR — destination IP address
  • DPORT — destination port

look at all those little letters, it's giving ✨ organized ✨

🔥 OVERHEAD 🔥

so, the deal: this traces the kernel tcp_v[46]_connect functions and prints output for each event.

is that scary? nope 🫶 because the rate of this is generally expected to be low — like < 1000/s — so the overhead is also expected to be negligible.

BUT — and this is important, bestie, don't skip this part 🙈 — if you've got an application calling a high rate of connect()s, such as a proxy server, then you need to test and understand this overhead before use. do not just rawdog it into prod, I'm begging 😭

🌈 SOURCE 🌈

this is from bpftrace:

https://github.com/iovisor/bpftrace

also, go look in the bpftrace distribution for a companion _examples.txt file — it's got example usage, output, and commentary for this tool 👑 (basically the director's commentary track, we're obsessed)

and pssst — this is a bpftrace version of the bcc tool of the same name. the bcc tool may provide more options and customizations, so if you want more knobs to turn:

https://github.com/iovisor/bcc

💖 OS 💖

Linux 🐧 (obviously, she's not doing all this on anything else)

💀 STABILITY 💀

Unstable - in development.

translation: she's still in her growing era, handle with care 🌱

🎀 AUTHOR 🎀

Brendan Gregg, adapted for bpftrace by Dale Hamel

legends. both of them. thank you for your service 🫡💜

🌟 SEE ALSO 🌟

(the whole friend group, go say hi)

ok bye bestie, go trace some connects 🦋💅✨

this one's from the USER COMMANDS corner of the manual, dated 2018-11-24, and it lives at tcpconnect.bt(8) — mwah, xoxo 🎀

📦 where this page comes from