share/man/man4/dtrace_tcp.4

   1 .\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd August 1, 2018
  28 .Dt DTRACE_TCP 4
  29 .Os
  30 .Sh NAME
  31 .Nm dtrace_tcp
  32 .Nd a DTrace provider for tracing events related to the
  33 .Xr tcp 4
  34 protocol
  35 .Sh SYNOPSIS
  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 *" \
  47     "tcpinfo_t *"
  48 .Fn tcp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "tcpsinfo_t *" \
  49     "tcpinfo_t *"
  50 .Fn tcp:::state-change "void *" "csinfo_t *" "void *" "tcpsinfo_t *" "void *" \
  51     "tcplsinfo_t *"
  52 .Sh DESCRIPTION
  53 The DTrace
  54 .Nm tcp
  55 provider allows users to trace events in the
  56 .Xr tcp 4
  57 protocol implementation.
  58 This provider is similar to the
  59 .Xr dtrace_ip 4
  60 and
  61 .Xr dtrace_udp 4
  62 providers, but additionally contains probes corresponding to protocol events at
  63 a level higher than packet reception and transmission.
  64 All
  65 .Nm tcp
  66 probes except for
  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
  70 .Vt ipinfo_t
  71 argument exposes the version-agnostic fields of the IP header, while the
  72 .Vt tcpinfo_t
  73 argument exposes the TCP header, and the
  74 .Vt tcpsinfo_t
  75 argument describes details of the corresponding TCP connection state, if any.
  76 Their fields are described in the ARGUMENTS section.
  77 .Pp
  78 The
  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
  83 handshake.
  84 The
  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.
  89 .Pp
  90 The
  91 .Fn tcp:::connect-established ,
  92 .Fn tcp:::connect-refused ,
  93 and
  94 .Fn tcp:::connect-request
  95 probes are similar to the
  96 .Ql accept
  97 probes, except that they correspond to locally-initiated TCP connections.
  98 The
  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
 105 segment.
 106 The
 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
 111 RST segment.
 112 The
 113 .Fn tcp:::connect-request
 114 probe fires as the kernel prepares to transmit the initial SYN segment of a
 115 three-way handshake.
 116 .Pp
 117 The
 118 .Fn tcp:::send
 119 and
 120 .Fn tcp:::receive
 121 probes fire when the host sends or receives a TCP packet, respectively.
 122 As with the
 123 .Xr dtrace_udp 4
 124 provider,
 125 .Nm tcp
 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
 128 .Xr dtrace_ip 4
 129 provider.
 130 .Pp
 131 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
 135 .Dv NULL .
 136 Its last argument describes the from-state in the transition, and the to-state
 137 can be obtained from
 138 .Dv args[3]->tcps_state .
 139 .Sh ARGUMENTS
 140 The
 141 .Vt pktinfo_t
 142 argument is currently unimplemented and is included for compatibility with other
 143 implementations of this provider.
 144 Its fields are:
 145 .Bl -tag -width "uinptr_t pkt_addr" -offset indent
 146 .It Vt uinptr_t pkt_addr
 147 Always set to 0.
 148 .El
 149 .Pp
 150 The
 151 .Vt csinfo_t
 152 argument is currently unimplemented and is included for compatibility with other
 153 implementations of this provider.
 154 Its fields are:
 155 .Bl -tag -width "uintptr_t cs_addr" -offset indent
 156 .It Vt uintptr_t cs_addr
 157 Always set to 0.
 158 .It Vt uint64_t cs_cid
 159 A pointer to the
 160 .Vt struct inpcb
 161 for this packet, or
 162 .Dv NULL .
 163 .It Vt pid_t cs_pid
 164 Always set to 0.
 165 .El
 166 .Pp
 167 The
 168 .Vt ipinfo_t
 169 type is a version-agnostic representation of fields from an IP header.
 170 Its fields are described in the
 171 .Xr dtrace_ip 4
 172 manual page.
 173 .Pp
 174 The
 175 .Vt tcpsinfo_t
 176 type is used to provide a stable representation of TCP connection state.
 177 Some
 178 .Nm tcp
 179 probes, such as
 180 .Fn tcp:::accept-refused ,
 181 fire in a context where there is no TCP connection; this argument is
 182 .Dv NULL
 183 in that case.
 184 Its fields are:
 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
 189 .Vt struct tcpcb .
 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
 197 Local TCP port.
 198 .It Vt uint16_t tcps_rport
 199 Remote TCP port.
 200 .It Vt string tcps_laddr
 201 Local address.
 202 .It Vt string tcps_raddr
 203 Remote address.
 204 .It Vt int32_t tcps_state
 205 Current TCP state.
 206 The valid TCP state values are given by the constants prefixed with
 207 .Ql TCPS_
 208 in
 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
 232 begins.
 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.
 243 .It Vt int tcps_srtt
 244 Smoothed round-trip time.
 245 .El
 246 .Pp
 247 The
 248 .Vt tcpinfo_t
 249 type exposes the fields in a TCP segment header in host order.
 250 Its fields are:
 251 .Bl -tag -width "struct tcphdr *tcp_hdr" -offset indent
 252 .It Vt uint16_t tcp_sport
 253 Source TCP port.
 254 .It Vt uint16_t tcp_dport
 255 Destination TCP port.
 256 .It Vt uint32_t tcp_seq
 257 Sequence number.
 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
 263 TCP flags.
 264 .It Vt uint16_t tcp_window
 265 TCP window size.
 266 .It Vt uint16_t tcp_checksum
 267 Checksum.
 268 .It Vt uint16_t tcp_urgent
 269 Urgent data pointer.
 270 .It Vt struct tcphdr *tcp_hdr
 271 A pointer to the raw TCP header.
 272 .El
 273 .Pp
 274 The
 275 .Vt tcplsinfo_t
 276 type is used by the
 277 .Fn tcp:::state-change
 278 probe to provide the from-state of a transition.
 279 Its fields are:
 280 .Bl -tag -width "int32_t tcps_state" -offset indent
 281 .It Vt int32_t tcps_state
 282 A TCP state.
 283 The valid TCP state values are given by the constants prefixed with
 284 .Ql TCPS_
 285 in
 286 .Pa /usr/lib/dtrace/tcp.d .
 287 .El
 288 .Sh FILES
 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
 292 .Nm tcp
 293 provider.
 294 .El
 295 .Sh EXAMPLES
 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
 300
 301 dtrace:::BEGIN
 302 {
 303         printf(" %3s %15s:%-5s      %15s:%-5s %6s  %s\\n", "CPU",
 304             "LADDR", "LPORT", "RADDR", "RPORT", "BYTES", "FLAGS");
 305 }
 306
 307 tcp:::send
 308 {
 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,
 312             this->length);
 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 " : "");
 320         printf("\b)\\n");
 321 }
 322
 323 tcp:::receive
 324 {
 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 " : "");
 336         printf("\b)\\n");
 337 }
 338 .Ed
 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
 343
 344 int last[int];
 345
 346 dtrace:::BEGIN
 347 {
 348         printf("   %12s %-20s    %-20s %s\\n",
 349             "DELTA(us)", "OLD", "NEW", "TIMESTAMP");
 350 }
 351
 352 tcp:::state-change
 353 {
 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;
 359 }
 360
 361 tcp:::state-change
 362 /last[args[1]->cs_cid] == 0/
 363 {
 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;
 368 }
 369 .Ed
 370 .Sh COMPATIBILITY
 371 This provider is compatible with the
 372 .Nm tcp
 373 provider in Solaris.
 374 .Sh SEE ALSO
 375 .Xr dtrace 1 ,
 376 .Xr dtrace_ip 4 ,
 377 .Xr dtrace_sctp 4 ,
 378 .Xr dtrace_udp 4 ,
 379 .Xr dtrace_udplite 4 ,
 380 .Xr tcp 4 ,
 381 .Xr SDT 9
 382 .Sh HISTORY
 383 The
 384 .Nm tcp
 385 provider first appeared in
 386 .Fx
 387 10.0.
 388 .Sh AUTHORS
 389 This manual page was written by
 390 .An Mark Johnston Aq Mt markj@FreeBSD.org .
 391 .Sh BUGS
 392 The
 393 .Vt tcps_local
 394 and
 395 .Vt tcps_active
 396 fields of
 397 .Vt tcpsinfo_t
 398 are not filled in by the translator.