Scroll to navigation

tcpconnect(8) System Manager's Manual tcpconnect(8)


tcpconnect - Trace TCP active connections (connect()). Uses Linux eBPF/bcc.


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


This tool traces active TCP connections (eg, via a connect() syscall; accept() are passive connections). This can be useful for general troubleshooting to see what connections are initiated by the local server.

All connection attempts are traced, even if they ultimately fail.

This works by tracing the kernel tcp_v4_connect() and tcp_v6_connect() functions using dynamic tracing, and will need updating to match any changes to these functions.

When provided with the -d or --dns option, this tool will also correlate connect calls with the most recent DNS query that matches the IP connected. This feature works by tracing the kernel udp_recvmsg() function to collect DNS responses.

Since this uses BPF, only the root user can use this tool.


CONFIG_BPF and bcc.

If using the -d or --dns option, you must have the dnslib and cachetools python packages installed. You can install them with pip3 or with apt on Ubuntu 18.04+ using the python3-dnslib and python3-cachetools packages.


Print usage message.
Include a timestamp column.
Count connects per src ip and dest ip/port.
Trace this process ID only (filtered in-kernel).
Comma-separated list of destination ports to trace (filtered in-kernel).
Include a UID column.
Trace this UID only (filtered in-kernel).
Trace cgroups in this BPF map only (filtered in-kernel).
Trace mount namespaces in this BPF map only (filtered in-kernel).
Shows the most recent DNS query for the IP address in the connect call. This is likely related to the TCP connection details in the other columns, but is not guaranteed. This feature works by tracing the udp_recvmsg kernel function and tracking DNS responses received by the server. 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 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 in that DNS response is greater than 100ms, this tool will report this delta after the query. These deltas should be relatively short for most applications. A long delay between the response and connect could be either anomalous activity or indicate a misattribution between the DNS name requested and the IP that the connect syscall is using.

The -d option may not be used with the count feature (option -c)


# tcpconnect
# tcpconnect -t
# tcpconnect -d
# tcpconnect -p 181
# tcpconnect -P 80,81
# tcpconnect -U
# tcpconnect -u 1000
# tcpconnect -c
# tcpconnect --cgroupmap /sys/fs/bpf/test01
# tcpconnect --mntnsmap /sys/fs/bpf/mnt_ns_set


Time of the call, in seconds.
User ID
Process ID
Process name
IP address family (4 or 6)
Source IP address.
Destination IP address.
Destination port
Accumulated active connections since start.
Shows the most recent DNS query for the IP address in the connect call. This is likely related to the TCP connection details in the other columns, but is not guaranteed.


This traces the kernel tcp_v[46]_connect functions and prints output for each event. As the rate of this is generally expected to be low (< 1000/s), the overhead is also expected to be negligible. If you have an application that is calling a high rate of connect()s, such as a proxy server, then test and understand this overhead before use.

If you are using the -d option to track DNS requests, this tool will trace the udp_recvmsg function and generate an event for any packets from UDP port 53. This event contains up to 512 bytes of the UDP packet payload. Typical applications do not extensively use UDP, so the performance overhead of tracing udp_recvmsg is expected to be negligible, However, if you have an application that receives many UDP packets, then you should test and understand the overhead of tracing every received UDP message. Furthermore, performance overhead of running this tool on a DNS server is expected to be higher than average because all DNS response packets will be copied to userspace.


This is from bcc.

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




Unstable - in development.


Brendan Gregg


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

2020-02-20 USER COMMANDS