tcpconnect(8)

💖 tcpconnect(8) 💖

Bestie, let me explain the tcpconnect tool 🦋 It's the manual page for the tcpconnect command, and it's from the Linux eBPF/bcc toolkit ✨

---

👑 NAME 👑

tcpconnect is a tool that traces active TCP connections (connect()) 🔥 It uses Linux eBPF/bcc, so it's giving low-level energy 💅

---

🎀 SYNOPSIS 🎀

tcpconnect [-h] [-c] [-t] [-p PID] [-P PORT] [-4 | -6] [-L] [-u UID]
[-U] [--cgroupmap MAPPATH] [--mntnsmap MAPPATH] [-d]

---

✨ DESCRIPTION ✨

okay so this tool traces active TCP connections, like the ones made with a connect() syscall 💜 Passive ones from accept() don't count, they're the quiet ones 🙈 It's super useful for general troubleshooting when you want to see what connections the local server is starting 🧚

All connection attempts get traced, even the ones that ultimately fail 💀 Tea spill: failed ones are still in the log 🍓

Under the hood, it traces the kernel tcp_v4_connect() and tcp_v6_connect() functions with dynamic tracing. Heads up, it'll need updating if those functions ever change 😭

When you pass the -d or --dns option, the tool also tries to match each connect call with the most recent DNS query for the IP it connected to 🫶 It does this by tracing the kernel udp_recvmsg() function to collect DNS responses 🌸

⚠️ Since this uses BPF, only the root user can run this tool. Not you, not me, only root 💀

---

🌈 REQUIREMENTS 🌈

You need CONFIG_BPF and bcc, no cap 🧠

If you're using the -d or --dns option, you also need the dnslib and cachetools python packages installed 🎀 You can grab them with pip3, or with apt on Ubuntu 18.04+ using the python3-dnslib and python3-cachetools packages ✨

---

🦋 OPTIONS 🦋

• -h — Prints the usage message. Lowkey the most helpful one 🙈
• -t — Adds a timestamp column 🕰️
• -c — Counts connects per source IP and destination IP/port 📊
• -p PID — Only traces this process ID. The filtering happens in-kernel, so it's efficient 🔥
• -P PORT — A comma-separated list of destination ports to trace. Filtering is in-kernel too 🎯
• -4 — Traces the IPv4 family only 🌸
• -6 — Traces the IPv6 family only 🌈
• -L — Adds an LPORT column for the source port 💅
• -U — Adds a UID column 🫶
• -u UID — Only traces this UID. Filtered in-kernel 👑
• --cgroupmap MAPPATH — Only traces cgroups in this BPF map. Filtered in-kernel 🧚
• --mntnsmap MAPPATH — Only traces mount namespaces in this BPF map. Filtered in-kernel ✨
• -d — Shows the most recent DNS query for the IP address in the connect call. It's probably related to the TCP connection details in the other columns, but it's not guaranteed, so don't bet your life on it 🙈 It works by tracing the udp_recvmsg kernel function and tracking DNS responses the server receives. It only supports UDP DNS packets up to 512 bytes in length. The Python code keeps a cache of 10k DNS responses in memory for up to 24 hours 🧠

If the time difference in milliseconds between when the system received a DNS response and when a connect syscall was traced using an IP from that response is greater than 100ms, the tool reports that delta after the query ⏱️ Most apps should have pretty short deltas. A long delay could be anomalous activity, or it could mean the DNS name requested got misattributed to the IP the connect syscall is using 😭

⚠️ The -d option may not be used with the count feature (option -c). Don't mix them, bestie 💀

---

💖 EXAMPLES 💖

Trace all active TCP connections:

# tcpconnect

Trace all TCP connects, and include timestamps:

# tcpconnect -t

Trace all TCP connects, and include the most recent matching DNS query for each connected IP:

# tcpconnect -d

Trace PID 181 only:

# tcpconnect -p 181

Trace ports 80 and 81 only:

# tcpconnect -P 80,81

Trace IPv4 family only:

# tcpconnect -4

Trace IPv6 family only:

# tcpconnect -6

Trace all TCP connects, and include LPORT:

# tcpconnect -L

Trace all TCP connects, and include UID:

# tcpconnect -U

Trace UID 1000 only:

# tcpconnect -u 1000

Count connects per src ip and dest ip/port:

# tcpconnect -c

Trace a set of cgroups only (see special_filtering.md from bcc sources for more details):

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

Trace a set of mount namespaces only (see special_filtering.md from bcc sources for more details):

# tcpconnect --mntnsmap /sys/fs/bpf/mnt_ns_set

---

🧚 FIELDS 🧚

• TIME(s) — The time of the call, in seconds ⏰
• UID — User ID 🪪
• PID — Process ID 🆔
• COMM — Process name 🏷️
• IP — IP address family (4 or 6) 🌐
• SADDR — Source IP address 📤
• LPORT — Source port 🚪
• DADDR — Destination IP address 📥
• DPORT — Destination port 🎯
• CONNECTS — Accumulated active connections since start 📈
• QUERY — Shows the most recent DNS query for the IP address in the connect call. It's likely related to the other TCP connection details, but not guaranteed 🔍

---

🔥 OVERHEAD 🔥

This tool traces the kernel tcp_v[46]_connect functions and prints output for each event. The rate is usually pretty low (under 1000/s), so the overhead should be negligible 🫧 But if you have an app making a high rate of connect()s, like a proxy server, test and understand the overhead before you use it 🙈

If you're using the -d option to track DNS requests, this tool traces the udp_recvmsg function and generates an event for any packet from UDP port 53. Each event carries up to 512 bytes of the UDP packet payload. Most apps don't use UDP heavily, so the overhead of tracing udp_recvmsg should be negligible too. But if your app receives lots of UDP packets, test and understand the overhead of tracing every received UDP message 👀 Also, running this on a DNS server will have higher overhead than average, because every DNS response packet gets copied to userspace 😭

---

🌸 SOURCE 🌸

This is from bcc 💖

https://github.com/iovisor/bcc

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

---

🌈 OS 🌈

Linux 🐧

---

🧪 STABILITY 🧪

Unstable, it's still in development 🚧

---

💜 AUTHOR 💜

Brendan Gregg 👑

---

🦋 SEE ALSO 🦋

tcptracer(8), tcpaccept(8), funccount(8), tcpdump(8) 🫶

---

Okay bestie, that's the whole tea ☕💅 This page is from the USER COMMANDS section, dated 2020-02-20, and it's tcpconnect(8) 🎀 Stay iconic and go trace some connects 🦋✨