share/man/man4/dtrace_sctp.4

   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 August 22, 2018
  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
  33 protocol
  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
  54 The DTrace
  55 .Nm sctp
  56 provider allows users to trace events in the
  57 .Xr sctp 4
  58 protocol implementation.
  59 This provider is similar to the
  60 .Xr dtrace_ip 4
  61 and
  62 .Xr dtrace_udp 4
  63 providers,
  64 but additionally contains probes corresponding to protocol events at a level
  65 higher than packet reception and transmission.
  66 .Pp
  67 The
  68 .Fn sctp:cwnd::
  69 probes track changes in the congestion window on a netp.
  70 The
  71 .Fn sctp:rwnd::
  72 probes track changes in the receiver window for an assoc.
  73 The
  74 .Fn sctp:flightsize:net:val
  75 probe tracks changes in the flight size on a net or assoc and the
  76 .Fn sctp:flightsize:assoc:val
  77 probe provides the total flight version.
  78 .Pp
  79 The arguments of all
  80 .Nm sctp
  81 probes except for
  82 .Fn sctp:cwnd::rtt*
  83 and
  84 .Fn sctp::assoc:val
  85 are the Vtag for this end,
  86 the port number of the local side,
  87 the pointer to
  88 .Dv struct sctp_nets *changing ,
  89 the old value of the cwnd,
  90 and the new value of the cwnd.
  91 .Pp
  92 The arguments of
  93 .Fn sctp:::val
  94 are similar to the above except the fourth argument is the up/down amount.
  95 .Pp
  96 The
  97 .Fn sctp:cwnd::rtt*
  98 probe arguments are a bitmap of
  99 .Dv Vtag << 32 | localport << 16 | remoteport ,
 100 a bitmap of
 101 .Dv obw | nbw ,
 102 a bitmap of
 103 .Dv bwrtt | newrtt ,
 104 .Dv flight ,
 105 and a bitmap of
 106 .Dv (cwnd << 32) | point << 16 | retval(0/1) .
 107 .Pp
 108 The
 109 .Fn sctp:cwnd::init
 110 probe fires when a remotely-initiated active SCTP open succeeds.
 111 At this point the new connection is in the ESTABLISHED state, and the probe
 112 arguments expose the headers associated with the final ACK of the four-way
 113 handshake.
 114 .Pp
 115 The
 116 .Fn sctp:::send
 117 and
 118 .Fn sctp:::receive
 119 probes fire when the host sends or receives an SCTP packet, respectively.
 120 As with the
 121 .Xr dtrace_udp 4
 122 provider,
 123 .Nm sctp
 124 probes fire only for packets sent by or to the local host; forwarded packets are
 125 handled in the IP layer and are only visible to the
 126 .Xr dtrace_ip 4
 127 provider.
 128 .Pp
 129 The
 130 .Fn sctp:::state-change
 131 probe fires upon local SCTP association state transitions.
 132 Its first, third and fifth arguments are currently always
 133 .Dv NULL .
 134 Its last argument describes the from-state in the transition, and the to-state
 135 can 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
 141 DTrace type and translator definitions for the
 142 .Nm sctp
 143 provider.
 144 .El
 145 .Sh EXAMPLES
 146 A 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
 151 dtrace:::BEGIN
 152 {
 153         printf(" %3s %15s:%-5s      %15s:%-5s\n", "CPU",
 154             "LADDR", "LPORT", "RADDR", "RPORT");
 155 }
 156
 157 sctp:::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
 164 sctp:::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
 171 A 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
 176 int last[int];
 177
 178 dtrace:::BEGIN
 179 {
 180         printf(" %3s %12s  %-25s    %-25s\n",
 181             "CPU", "DELTA(us)", "OLD", "NEW");
 182 }
 183
 184 sctp:::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
 194 sctp:::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
 204 The
 205 .Fn sctp:::send ,
 206 .Fn sctp:::receive ,
 207 and
 208 .Fn sctp:::state-change
 209 probes are compatible with the
 210 .Nm sctp
 211 provider in Solaris.
 212 All 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
 227 This manual page was written by
 228 .An Devin Teske Aq Mt dteske@FreeBSD.org .