1.\" Copyright (c) 2018 Devin Teske <dteske@FreeBSD.org> 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd June 29, 2023 27.Dt DTRACE_SCTP 4 28.Os 29.Sh NAME 30.Nm dtrace_sctp 31.Nd a DTrace provider for tracing events related to the 32.Xr sctp 4 33protocol 34.Sh SYNOPSIS 35.Fn sctp:cwnd::init uint32_t uint32_t uintptr_t int int 36.Fn sctp:cwnd::ack uint32_t uint32_t uintptr_t int int 37.Fn sctp:cwnd::rttvar uint64_t uint64_t uint64_t uint64_t uint64_t 38.Fn sctp:cwnd::rttstep uint64_t uint64_t uint64_t uint64_t uint64_t 39.Fn sctp:cwnd::fr uint32_t uint32_t uintptr_t int int 40.Fn sctp:cwnd::to uint32_t uint32_t uintptr_t int int 41.Fn sctp:cwnd::bl uint32_t uint32_t uintptr_t int int 42.Fn sctp:cwnd::ecn uint32_t uint32_t uintptr_t int int 43.Fn sctp:cwnd::pd uint32_t uint32_t uintptr_t int int 44.Fn sctp:rwnd:assoc:val uint32_t uint32_t int int 45.Fn sctp:flightsize:net:val uint32_t uint32_t uintptr_t int int 46.Fn sctp:flightsize:assoc:val uint32_t uint32_t int int 47.Fn sctp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "sctpsinfo_t *" \ 48 "sctpinfo_t *" 49.Fn sctp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "sctpsinfo_t *" \ 50 "sctpinfo_t *" 51.Fn sctp:::state-change "void *" "csinfo_t *" "void *" "sctpsinfo_t *" \ 52 "void *" "sctplsinfo_t *" 53.Sh DESCRIPTION 54The DTrace 55.Nm sctp 56provider allows users to trace events in the 57.Xr sctp 4 58protocol implementation. 59This provider is similar to the 60.Xr dtrace_ip 4 61and 62.Xr dtrace_udp 4 63providers, 64but additionally contains probes corresponding to protocol events at a level 65higher than packet reception and transmission. 66.Pp 67The 68.Fn sctp:cwnd:: 69probes track changes in the congestion window on a netp. 70The 71.Fn sctp:rwnd:: 72probes track changes in the receiver window for an assoc. 73The 74.Fn sctp:flightsize:net:val 75probe tracks changes in the flight size on a net or assoc and the 76.Fn sctp:flightsize:assoc:val 77probe provides the total flight version. 78.Pp 79The arguments of all 80.Nm sctp 81probes except for 82.Fn sctp:cwnd::rtt* 83and 84.Fn sctp::assoc:val 85are the Vtag for this end, 86the port number of the local side, 87the pointer to 88.Dv struct sctp_nets *changing , 89the old value of the cwnd, 90and the new value of the cwnd. 91.Pp 92The arguments of 93.Fn sctp:::val 94are similar to the above except the fourth argument is the up/down amount. 95.Pp 96The 97.Fn sctp:cwnd::rtt* 98probe arguments are a bitmap of 99.Dv Vtag << 32 | localport << 16 | remoteport , 100a bitmap of 101.Dv obw | nbw , 102a bitmap of 103.Dv bwrtt | newrtt , 104.Dv flight , 105and a bitmap of 106.Dv (cwnd << 32) | point << 16 | retval(0/1) . 107.Pp 108The 109.Fn sctp:cwnd::init 110probe fires when a remotely-initiated active SCTP open succeeds. 111At this point the new connection is in the ESTABLISHED state, and the probe 112arguments expose the headers associated with the final ACK of the four-way 113handshake. 114.Pp 115The 116.Fn sctp:::send 117and 118.Fn sctp:::receive 119probes fire when the host sends or receives an SCTP packet, respectively. 120As with the 121.Xr dtrace_udp 4 122provider, 123.Nm sctp 124probes fire only for packets sent by or to the local host; forwarded packets are 125handled in the IP layer and are only visible to the 126.Xr dtrace_ip 4 127provider. 128.Pp 129The 130.Fn sctp:::state-change 131probe fires upon local SCTP association state transitions. 132Its first, third and fifth arguments are currently always 133.Dv NULL . 134Its last argument describes the from-state in the transition, and the to-state 135can be obtained from 136.Dv args[3]->sctps_state . 137.\" .Sh ARGUMENTS 138.Sh FILES 139.Bl -tag -width "/usr/lib/dtrace/sctp.d" -compact 140.It Pa /usr/lib/dtrace/sctp.d 141DTrace type and translator definitions for the 142.Nm sctp 143provider. 144.El 145.Sh EXAMPLES 146A script that logs SCTP packets in real time: 147.Bd -literal -offset indent 148#pragma D option quiet 149#pragma D option switchrate=10hz 150 151dtrace:::BEGIN 152{ 153 printf(" %3s %15s:%-5s %15s:%-5s\\n", "CPU", 154 "LADDR", "LPORT", "RADDR", "RPORT"); 155} 156 157sctp:::send 158{ 159 printf(" %3d %16s:%-5d -> %16s:%-5d\\n", cpu, 160 args[2]->ip_saddr, args[4]->sctp_sport, 161 args[2]->ip_daddr, args[4]->sctp_dport); 162} 163 164sctp:::receive 165{ 166 printf(" %3d %16s:%-5d <- %16s:%-5d\\n", cpu, 167 args[2]->ip_daddr, args[4]->sctp_dport, 168 args[2]->ip_saddr, args[4]->sctp_sport); 169} 170.Ed 171A script that logs SCTP association state changes as they occur: 172.Bd -literal -offset indent 173#pragma D option quiet 174#pragma D option switchrate=10 175 176int last[int]; 177 178dtrace:::BEGIN 179{ 180 printf(" %3s %12s %-25s %-25s\\n", 181 "CPU", "DELTA(us)", "OLD", "NEW"); 182} 183 184sctp:::state-change 185/ last[args[1]->cs_cid] / 186{ 187 this->elapsed = (timestamp - last[args[1]->cs_cid]) / 1000; 188 printf(" %3d %12d %-25s -> %-25s\\n", cpu, this->elapsed, 189 sctp_state_string[args[5]->sctps_state], 190 sctp_state_string[args[3]->sctps_state]); 191 last[args[1]->cs_cid] = timestamp; 192} 193 194sctp:::state-change 195/ last[args[1]->cs_cid] == 0 / 196{ 197 printf(" %3d %12s %-25s -> %-25s\\n", cpu, "-", 198 sctp_state_string[args[5]->sctps_state], 199 sctp_state_string[args[3]->sctps_state]); 200 last[args[1]->cs_cid] = timestamp; 201} 202.Ed 203.Sh COMPATIBILITY 204The 205.Fn sctp:::send , 206.Fn sctp:::receive , 207and 208.Fn sctp:::state-change 209probes are compatible with the 210.Nm sctp 211provider in Solaris. 212All other probes are only available in FreeBSD. 213.Sh SEE ALSO 214.Xr dtrace 1 , 215.Xr dtrace_ip 4 , 216.Xr dtrace_udp 4 , 217.Xr dtrace_udplite 4 , 218.Xr sctp 4 , 219.Xr SDT 9 220.\" .Sh HISTORY 221.\" The 222.\" .Nm sctp 223.\" provider first appeared in 224.\" .Fx 225.\" UNKNOWN. 226.Sh AUTHORS 227This manual page was written by 228.An Devin Teske Aq Mt dteske@FreeBSD.org . 229