1tcpconnect(8) System Manager's Manual tcpconnect(8)
2
6 tcpconnect - Trace TCP active connections (connect()). Uses Linux
7 eBPF/bcc.
8
10 tcpconnect [-h] [-c] [-t] [-p PID] [-P PORT] [-u UID] [-U] [--cgroupmap
11 MAPPATH] [--mntnsmap MAPPATH] [-d]
12
14 This tool traces active TCP connections (eg, via a connect() syscall;
15 accept() are passive connections). This can be useful for general trou‐
16 bleshooting to see what connections are initiated by the local server.
17 All connection attempts are traced, even if they ultimately fail.
19 This works by tracing the kernel tcp_v4_connect() and tcp_v6_connect()
21 functions using dynamic tracing, and will need updating to match any
22 changes to these functions.
23 When provided with the -d or --dns option, this tool will also corre‐
25 late connect calls with the most recent DNS query that matches the IP
26 connected. This feature works by tracing the kernel udp_recvmsg()
27 function to collect DNS responses.
28 Since this uses BPF, only the root user can use this tool.
30
32 CONFIG_BPF and bcc.
33 If using the -d or --dns option, you must have the dnslib and
35 cachetools python packages installed. You can install them with pip3
36 or with apt on Ubuntu 18.04+ using the python3-dnslib and
37 python3-cachetools packages.
38
40 -h Print usage message.
41 -t Include a timestamp column.
43 -c Count connects per src ip and dest ip/port.
45 -p PID Trace this process ID only (filtered in-kernel).
47 -P PORT
49 Comma-separated list of destination ports to trace (filtered in-
50 kernel).
51 -U Include a UID column.
53 -u UID Trace this UID only (filtered in-kernel).
55 --cgroupmap MAPPATH
57 Trace cgroups in this BPF map only (filtered in-kernel).
58 --mntnsmap MAPPATH
60 Trace mount namespaces in this BPF map only (filtered in-ker‐
61 nel).
62 -d Shows the most recent DNS query for the IP address in the con‐
64 nect call. This is likely related to the TCP connection details
65 in the other columns, but is not guaranteed. This feature works
66 by tracing the udp_recvmsg kernel function and tracking DNS
67 responses received by the server. It only supports UDP DNS
68 packets up to 512 bytes in length. The python code keeps a
69 cache of 10k DNS responses in memory for up 24 hours.
70 If the time difference in milliseconds between when the system
72 received a DNS response and when a connect syscall was traced
73 using an IP in that DNS response is greater than 100ms, this
74 tool will report this delta after the query. These deltas
75 should be relatively short for most applications. A long delay
76 between the response and connect could be either anomalous
77 activity or indicate a misattribution between the DNS name
78 requested and the IP that the connect syscall is using.
79 The -d option may not be used with the count feature (option -c)
81
83 Trace all active TCP connections:
84 # tcpconnect
85 Trace all TCP connects, and include timestamps:
87 # tcpconnect -t
88 Trace all TCP connects, and include most recent matching DNS query for
90 each connected IP
91 # tcpconnect -d
92 Trace PID 181 only:
94 # tcpconnect -p 181
95 Trace ports 80 and 81 only:
97 # tcpconnect -P 80,81
98 Trace all TCP connects, and include UID:
100 # tcpconnect -U
101 Trace UID 1000 only:
103 # tcpconnect -u 1000
104 Count connects per src ip and dest ip/port:
106 # tcpconnect -c
107 Trace a set of cgroups only (see special_filtering.md from bcc sources
109 for more details):
110 # tcpconnect --cgroupmap /sys/fs/bpf/test01
111 Trace a set of mount namespaces only (see special_filtering.md from bcc
113 sources for more details):
114 # tcpconnect --mntnsmap /sys/fs/bpf/mnt_ns_set
115
117 TIME(s)
118 Time of the call, in seconds.
119 UID User ID
121 PID Process ID
123 COMM Process name
125 IP IP address family (4 or 6)
127 SADDR Source IP address.
129 DADDR Destination IP address.
131 DPORT Destination port
133 CONNECTS
135 Accumulated active connections since start.
136 QUERY Shows the most recent DNS query for the IP address in the con‐
138 nect call. This is likely related to the TCP connection details
139 in the other columns, but is not guaranteed.
140
142 This traces the kernel tcp_v[46]_connect functions and prints output
143 for each event. As the rate of this is generally expected to be low (<
144 1000/s), the overhead is also expected to be negligible. If you have an
145 application that is calling a high rate of connect()s, such as a proxy
146 server, then test and understand this overhead before use.
147 If you are using the -d option to track DNS requests, this tool will
149 trace the udp_recvmsg function and generate an event for any packets
150 from UDP port 53. This event contains up to 512 bytes of the UDP
151 packet payload. Typical applications do not extensively use UDP, so
152 the performance overhead of tracing udp_recvmsg is expected to be neg‐
153 ligible, However, if you have an application that receives many UDP
154 packets, then you should test and understand the overhead of tracing
155 every received UDP message. Furthermore, performance overhead of run‐
156 ning this tool on a DNS server is expected to be higher than average
157 because all DNS response packets will be copied to userspace.
158
160 This is from bcc.
161 https://github.com/iovisor/bcc
163 Also look in the bcc distribution for a companion _examples.txt file
165 containing example usage, output, and commentary for this tool.
166
168 Linux
169
171 Unstable - in development.
172
174 Brendan Gregg
175
177 tcptracer(8), tcpaccept(8), funccount(8), tcpdump(8)
178USER COMMANDS 2020-02-20 tcpconnect(8)