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