1 .\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd a DTrace provider for tracing events related to the
36 .Fn tcp:::accept-established "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
37 "tcpsinfo_t *" "tcpinfo_t *"
38 .Fn tcp:::accept-refused "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
39 "tcpsinfo_t *" "tcpinfo_t *"
40 .Fn tcp:::connect-established "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
41 "tcpsinfo_t *" "tcpinfo_t *"
42 .Fn tcp:::connect-refused "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
43 "tcpsinfo_t *" "tcpinfo_t *"
44 .Fn tcp:::connect-request "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \
45 "tcpsinfo_t *" "tcpinfo_t *"
46 .Fn tcp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "tcpsinfo_t *" \
48 .Fn tcp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "tcpsinfo_t *" \
50 .Fn tcp:::state-change "void *" "csinfo_t *" "void *" "tcpsinfo_t *" "void *" \
55 provider allows users to trace events in the
57 protocol implementation.
58 This provider is similar to the
62 providers, but additionally contains probes corresponding to protocol events at
63 a level higher than packet reception and transmission.
67 .Fn tcp:::state-change
68 have the same number and type of arguments.
69 The last three arguments are used to describe a TCP segment: the
71 argument exposes the version-agnostic fields of the IP header, while the
73 argument exposes the TCP header, and the
75 argument describes details of the corresponding TCP connection state, if any.
76 Their fields are described in the ARGUMENTS section.
79 .Fn tcp:::accept-established
80 probe fires when a remotely-initiated active TCP open succeeds.
81 At this point the new connection is in the ESTABLISHED state, and the probe
82 arguments expose the headers associated with the final ACK of the three-way
85 .Fn tcp:::accept-refused
86 probe fires when a SYN arrives on a port without a listening socket.
87 The probe arguments expose the headers associated with the RST to be transmitted
88 to the remote host in response to the SYN segment.
91 .Fn tcp:::connect-established ,
92 .Fn tcp:::connect-refused ,
94 .Fn tcp:::connect-request
95 probes are similar to the
97 probes, except that they correspond to locally-initiated TCP connections.
99 .Fn tcp:::connect-established
100 probe fires when the SYN-ACK segment of a three-way handshake is received from
101 the remote host and a final ACK is prepared for transmission.
102 This occurs immediately after the local connection state transitions from
103 SYN-SENT to ESTABLISHED.
104 The probe arguments describe the headers associated with the received SYN-ACK
107 .Fn tcp:::connect-refused
108 probe fires when the local host receives a RST segment in response to a SYN
109 segment, indicating that the remote host refused to open a connection.
110 The probe arguments describe the IP and TCP headers associated with the received
113 .Fn tcp:::connect-request
114 probe fires as the kernel prepares to transmit the initial SYN segment of a
121 probes fire when the host sends or receives a TCP packet, respectively.
126 probes fire only for packets sent by or to the local host; forwarded packets are
127 handled in the IP layer and are only visible to the
132 .Fn tcp:::state-change
133 probe fires upon local TCP connection state transitions.
134 Its first, third and fifth arguments are currently always
136 Its last argument describes the from-state in the transition, and the to-state
138 .Dv args[3]->tcps_state .
142 argument is currently unimplemented and is included for compatibility with other
143 implementations of this provider.
145 .Bl -tag -width "uinptr_t pkt_addr" -offset indent
146 .It Vt uinptr_t pkt_addr
152 argument is currently unimplemented and is included for compatibility with other
153 implementations of this provider.
155 .Bl -tag -width "uintptr_t cs_addr" -offset indent
156 .It Vt uintptr_t cs_addr
158 .It Vt uint64_t cs_cid
169 type is a version-agnostic representation of fields from an IP header.
170 Its fields are described in the
176 type is used to provide a stable representation of TCP connection state.
180 .Fn tcp:::accept-refused ,
181 fire in a context where there is no TCP connection; this argument is
185 .Bl -tag -width "uint16_t tcps_lport" -offset indent
186 .It Vt uintptr_t tcps_addr
187 The address of the corresponding TCP control block.
188 This is currently a pointer to a
190 .It Vt int tcps_local
191 A boolean indicating whether the connection is local to the host.
192 Currently unimplemented and always set to -1.
193 .It Vt int tcps_active
194 A boolean indicating whether the connection was initiated by the local host.
195 Currently unimplemented and always set to -1.
196 .It Vt uint16_t tcps_lport
198 .It Vt uint16_t tcps_rport
200 .It Vt string tcps_laddr
202 .It Vt string tcps_raddr
204 .It Vt int32_t tcps_state
206 The valid TCP state values are given by the constants prefixed with
209 .Pa /usr/lib/dtrace/tcp.d .
210 .It Vt uint32_t tcps_iss
211 Initial send sequence number.
212 .It Vt uint32_t tcps_suna
213 Initial sequence number of sent but unacknowledged data.
214 .It Vt uint32_t tcps_snxt
215 Next sequence number for send.
216 .It Vt uint32_t tcps_rack
217 Sequence number of received and acknowledged data.
218 .It Vt uint32_t tcps_rnxt
219 Next expected sequence number for receive.
220 .It Vt u_long tcps_swnd
221 TCP send window size.
222 .It Vt int32_t tcps_snd_ws
223 Window scaling factor for the TCP send window.
224 .It Vt u_long tcps_rwnd
225 TCP receive window size.
226 .It Vt int32_t tcps_rcv_ws
227 Window scaling factor for the TCP receive window.
228 .It Vt u_long tcps_cwnd
229 TCP congestion window size.
230 .It Vt u_long tcps_cwnd_ssthresh
231 Congestion window threshold at which slow start ends and congestion avoidance
233 .It Vt uint32_t tcps_sack_fack
234 Last sequence number selectively acknowledged by the receiver.
235 .It Vt uint32_t tcps_sack_snxt
236 Next selectively acknowledge sequence number at which to begin retransmitting.
237 .It Vt uint32_t tcps_rto
238 Round-trip timeout, in milliseconds.
239 .It Vt uint32_t tcps_mss
240 Maximum segment size.
241 .It Vt int tcps_retransmit
242 A boolean indicating that the local sender is retransmitting data.
244 Smoothed round-trip time.
249 type exposes the fields in a TCP segment header in host order.
251 .Bl -tag -width "struct tcphdr *tcp_hdr" -offset indent
252 .It Vt uint16_t tcp_sport
254 .It Vt uint16_t tcp_dport
255 Destination TCP port.
256 .It Vt uint32_t tcp_seq
258 .It Vt uint32_t tcp_ack
259 Acknowledgement number.
260 .It Vt uint8_t tcp_offset
261 Data offset, in bytes.
262 .It Vt uint8_t tcp_flags
264 .It Vt uint16_t tcp_window
266 .It Vt uint16_t tcp_checksum
268 .It Vt uint16_t tcp_urgent
270 .It Vt struct tcphdr *tcp_hdr
271 A pointer to the raw TCP header.
277 .Fn tcp:::state-change
278 probe to provide the from-state of a transition.
280 .Bl -tag -width "int32_t tcps_state" -offset indent
281 .It Vt int32_t tcps_state
283 The valid TCP state values are given by the constants prefixed with
286 .Pa /usr/lib/dtrace/tcp.d .
289 .Bl -tag -width "/usr/lib/dtrace/tcp.d" -compact
290 .It Pa /usr/lib/dtrace/tcp.d
291 DTrace type and translator definitions for the
296 The following script logs TCP segments in real time:
297 .Bd -literal -offset indent
298 #pragma D option quiet
299 #pragma D option switchrate=10hz
303 printf(" %3s %15s:%-5s %15s:%-5s %6s %s\\n", "CPU",
304 "LADDR", "LPORT", "RADDR", "RPORT", "BYTES", "FLAGS");
309 this->length = args[2]->ip_plength - args[4]->tcp_offset;
310 printf(" %3d %16s:%-5d -> %16s:%-5d %6d (", cpu, args[2]->ip_saddr,
311 args[4]->tcp_sport, args[2]->ip_daddr, args[4]->tcp_dport,
313 printf("%s", args[4]->tcp_flags & TH_FIN ? "FIN|" : "");
314 printf("%s", args[4]->tcp_flags & TH_SYN ? "SYN|" : "");
315 printf("%s", args[4]->tcp_flags & TH_RST ? "RST|" : "");
316 printf("%s", args[4]->tcp_flags & TH_PUSH ? "PUSH|" : "");
317 printf("%s", args[4]->tcp_flags & TH_ACK ? "ACK|" : "");
318 printf("%s", args[4]->tcp_flags & TH_URG ? "URG|" : "");
319 printf("%s", args[4]->tcp_flags == 0 ? "null " : "");
325 this->length = args[2]->ip_plength - args[4]->tcp_offset;
326 printf(" %3d %16s:%-5d <- %16s:%-5d %6d (", cpu,
327 args[2]->ip_daddr, args[4]->tcp_dport, args[2]->ip_saddr,
328 args[4]->tcp_sport, this->length);
329 printf("%s", args[4]->tcp_flags & TH_FIN ? "FIN|" : "");
330 printf("%s", args[4]->tcp_flags & TH_SYN ? "SYN|" : "");
331 printf("%s", args[4]->tcp_flags & TH_RST ? "RST|" : "");
332 printf("%s", args[4]->tcp_flags & TH_PUSH ? "PUSH|" : "");
333 printf("%s", args[4]->tcp_flags & TH_ACK ? "ACK|" : "");
334 printf("%s", args[4]->tcp_flags & TH_URG ? "URG|" : "");
335 printf("%s", args[4]->tcp_flags == 0 ? "null " : "");
339 The following script logs TCP connection state changes as they occur:
340 .Bd -literal -offset indent
341 #pragma D option quiet
342 #pragma D option switchrate=25hz
348 printf(" %12s %-20s %-20s %s\\n",
349 "DELTA(us)", "OLD", "NEW", "TIMESTAMP");
354 this->elapsed = (timestamp - last[args[1]->cs_cid]) / 1000;
355 printf(" %12d %-20s -> %-20s %d\\n", this->elapsed,
356 tcp_state_string[args[5]->tcps_state],
357 tcp_state_string[args[3]->tcps_state], timestamp);
358 last[args[1]->cs_cid] = timestamp;
362 /last[args[1]->cs_cid] == 0/
364 printf(" %12s %-20s -> %-20s %d\\n", "-",
365 tcp_state_string[args[5]->tcps_state],
366 tcp_state_string[args[3]->tcps_state], timestamp);
367 last[args[1]->cs_cid] = timestamp;
371 This provider is compatible with the
379 .Xr dtrace_udplite 4 ,
385 provider first appeared in
389 This manual page was written by
390 .An Mark Johnston Aq Mt markj@FreeBSD.org .
398 are not filled in by the translator.