sctp Provider
The sctp provider provides probes for tracing the SCTP protocol.
This provider is under development and is not yet available.
Probes
The sctp probes are described in the table below.
sctp Probes
Probe | Description |
---|---|
state-change | Probe that fires when an SCTP session changes its SCTP state. Previous state is noted in the sctplsinfo_t * probe argument. The sctpinfo_t * and ipinfo_t * arguments are NULL. |
send | Probe that fires whenever SCTP sends a segment (either control or data). |
receive | Probe that fires whenever SCTP receives a segment (either control or data). |
The send and receive probes trace packets on physical interfaces and also packets on loopback interfaces that are processed by sctp.
Arguments
The argument types for the sctp probes are listed in the table below. The arguments are described in the following section. All probes expect state-change have 5 arguments - state-change has 6.
sctp Probe Arguments
Probe | args[0] | args[1] | args[2] | args[3] | args[4] | args[5] |
---|---|---|---|---|---|---|
state-change | null | csinfo_t * | null | sctpsinfo_t * | null | sctplsinfo_t * |
send | pktinfo_t * | csinfo_t * | ipinfo_t * | sctpsinfo_t * | sctpinfo_t * | |
receive | pktinfo_t * | csinfo_t * | ipinfo_t * | sctpsinfo_t * | sctpinfo_t * |
pktinfo_t structure
The pktinfo_t structure is where packet ID info can be made available for deeper analysis if packet IDs become supported by the kernel in the future.
The pkt_addr member is currently always NULL.
typedef struct pktinfo { uintptr_t pkt_addr; /* currently always NULL */ } pktinfo_t;
csinfo_t structure
The csinfo_t structure is where connection state info is made available. It contains a unique (system-wide) connection ID, and the process ID and zone ID associated with the connection.
typedef struct csinfo { uintptr_t cs_addr; uint64_t cs_cid; pid_t cs_pid; zoneid_t cs_zoneid; } csinfo_t;
csinfo_t Members
cs_addr | Address of translated ip_xmit_attr_t *. |
cs_cid | Connection id. A unique per-connection identifier which identifies the connection during its lifetime. |
cs_pid | Process ID associated with the connection. |
cs_zoneid | Zone ID associated with the connection. |
ipinfo_t structure
The ipinfo_t structure contains common IP info for both IPv4 and IPv6.
typedef struct ipinfo { uint8_t ip_ver; /* IP version (4, 6) */ uint16_t ip_plength; /* payload length */ string ip_saddr; /* source address */ string ip_daddr; /* destination address */ } ipinfo_t;
ipinfo_t Members
ip_ver | IP version number. Currently either 4 or 6. |
ip_plength | Payload length in bytes. This is the length of the packet at the time of tracing, excluding the IP header. |
ip_saddr | Source IP address, as a string. For IPv4 this is a dotted decimal quad, IPv6 follows RFC-1884 convention 2 with lower case hexadecimal digits. |
ip_daddr | Destination IP address, as a string. For IPv4 this is a dotted decimal quad, IPv6 follows RFC-1884 convention 2 with lower case hexadecimal digits. |
sctpsinfo_t structure
The sctpsinfo_t structure contains sctp state info.
typedef struct sctpsinfo { uintptr_t sctps_addr; int sctps_num_raddrs; /* number of remote addresses */ uintptr_t sctps_raddrs; /* pointer to first remote address */ uint16_t sctps_lport; /* local port */ uint16_t sctps_rport; /* remote port */ string sctps_laddr; /* local address, as a string */ string sctps_raddr; /* remote address, as a string */ int32_t sctps_state; } sctpsinfo_t;
It may seem redundant to supply the local and remote ports and addresses here as well as in the sctpinfo_t below, but the sctp:::state-change probes do not have associated sctpinfo_t data, so in order to map the state change to a specific port, we need this data here. The sctps_raddrs pointer can be translated to an sctprinfo_t * structure (see below).
sctpsinfo_t Members
sctps_addr | Address of translated sctp_t *. |
sctps_num_raddrs | Number of remote addresses. |
sctps_raddrs | Pointer to first sctp_faddr_t *, which can be translated to an sctprinfo_t * (see below). |
sctps_lport | local port associated with the SCTP connection. |
sctps_rport | remote port associated with the SCTP connection. |
sctps_laddr | local address associated with the SCTP connection, as a string. |
sctps_raddr | remote address associated with the SCTP connection, as a string. |
sctps_state | SCTP state. Inline defintions are provided for the various SCTP states: SCTP_STATE_CLOSED, SCTP_STATE_IDLE, etc. Use inline sctp_state_string[] to convert state to a string. |
sctprinfo_t structure
The sctprinfo_t structure contains sctp remote address info translated from the sctpsinfo_t sctps_raddrs field, or the sctprinfo_t sctpr_next field.
typedef struct sctprinfo { uintptr_t sctpr_addr; int sctpr_state; string sctpr_raddr; string sctpr_laddr; int64_t sctpr_hb_expiry; /* heartbeat retransmit time, msec */ uint32_t sctpr_hb_interval; /* heartbeat interval, msec */ int sctpr_rto; /* round-trip timeout, ticks */ int sctpr_rtt; /* smoothed avg round-trip time ticks */ int sctpr_rtt_var; /* variance of RTT */ uint32_t sctpr_mss; /* max packet size */ uint32_t sctpr_cwnd; /* congestion window */ uint32_t sctpr_ssthresh; /* threshold for congestion avoidance */ uint32_t sctpr_suna; /* sent and unacked */ uint32_t sctpr_pba; /* partial bytes acked */ uint32_t sctpr_acked; /* bytes acked */ uintptr_t sctpr_next; /* next remote address structure */ } sctprinfo_t;
sctprinfo_t Members
sctpr_addr | Address of translated sctp_faddr_t *. |
sctpr_state | State associated with remote address. |
sctpr_raddr | Remote address, as a string. |
sctpr_laddr | Local address, as a string. |
sctpr_hb_expiry | Heartbeat retransmit time, msec. |
sctpr_hb_interval | Heartbeat interval, msec. |
sctpr_rto | Smoothed avarage retransmit timeout, in ticks. |
sctpr_rtt | Smoothed average round-trip time, ticks. |
sctpr_rtt_var | Variance of RTT. |
sctpr_mss | Max segment size, bytes. |
sctpr_cwnd | Congestion window. |
sctpr_ssthresh | Slow start threshold. |
sctpr_suna | Sent and unacked sequence number. |
sctpr_pba | Partial bytes acked. |
sctpr_next | Next remote address structure. |
sctplsinfo_t structure
The sctplsinfo_t structure contains the previous sctp state during a state change.
typedef struct sctplsinfo { int32_t sctps_state; /* SCTP state */ } sctplsinfo_t;
sctplsinfo_t Members
sctps_state | previous SCTP state. Inline defintions are provided for the various SCTP states: SCTP_STATE_CLOSED, SCTP_STATE_IDLE, etc. Use inline sctp_state_string[] to convert state to a string. |
sctpinfo_t structure
The sctpinfo_t structure is a DTrace translated version of the SCTP header.
typedef struct sctpinfo { uint16_t sctp_sport; /* source port */ uint16_t sctp_dport; /* destination port */ uint16_t sctp_verify; /* verification tag */ uint16_t sctp_checksum; /* headers + data checksum */ sctp_chunk_hdr_t *sctp_chunk_hdr; /* generic sctp chunk header */ sctp_hdr_t *sctp_hdr; /* raw SCTP header */ } sctpinfo_t;
sctpinfo_t Members
sctp_sport | SCTP source port. |
sctp_dport | SCTP destination port. |
sctp_verify | SCTP verification tag. |
sctp_checksum | Checksum of SCTP header and payload. |
sctp_chunk_hdr | Pointer to SCTP chunk header. |
sctp_hdr | Pointer to raw SCTP header at time of tracing. |
See RFC-2960 for a detailed explanation of the various SCTP subheader fields.
Examples
Some simple examples of sctp provider usage follow.
sctpstate.d
This DTrace script demonstrates the capability to trace SCTP state changes:
#!/usr/sbin/dtrace -s #pragma D option quiet #pragma D option switchrate=10 int last[int]; dtrace:::BEGIN { printf(" %3s %12s %-20s %-20s\n", "CPU", "DELTA(us)", "OLD", "NEW"); last = timestamp; } sctp:::state-change / last[args[1]->cs_cid] / { this->elapsed = (timestamp - last[args[1]->cs_cid]) / 1000; printf(" %3d %12d %-20s -> %-20s\n", cpu, this->elapsed, sctp_state_string[args[5]->sctps_state], sctp_state_string[args[3]->sctps_state]); last[args[1]->cs_cid] = timestamp; } sctp:::state-change / last[args[1]->cs_cid] == 0 / { printf(" %3d %12s %-20s -> %-20s\n", cpu, "-", sctp_state_string[args[5]->sctps_state], sctp_state_string[args[3]->sctps_state]); last[args[1]->cs_cid] = timestamp; }
The fields printed are:
field | description |
---|---|
CPU | CPU id for the event |
DELTA(us) | time since previous event for that connection, microseconds |
OLD | old SCTP state |
NEW | new SCTP state |
sctpio.d
The following DTrace script traces SCTP packets and prints various details:
#!/usr/sbin/dtrace -s #pragma D option quiet #pragma D option switchrate=10hz dtrace:::BEGIN { printf(" %3s %15s:%-5s %15s:%-5s\n", "CPU", "LADDR", "LPORT", "RADDR", "RPORT"); } sctp:::send { printf(" %3d %16s:%-5d -> %16s:%-5d\n", cpu, args[2]->ip_saddr, args[4]->sctp_sport, args[2]->ip_daddr, args[4]->sctp_dport); } sctp:::receive { printf(" %3d %16s:%-5d <- %16s:%-5d\n", cpu, args[2]->ip_daddr, args[4]->sctp_dport, args[2]->ip_saddr, args[4]->sctp_sport); }
The fields printed are:
field | description |
---|---|
CPU | CPU id that event occurred on |
LADDR | local IP address |
LPORT | local SCTP port |
RADDR | remote IP address |
RPORT | remote SCTP port |
sctp Stability
The sctp provider uses DTrace's stability mechanism to describe its stabilities, as shown in the following table. For more information about the stability mechanism, see Chapter 39, Stability.
Element | Name stability | Data stability | Dependency class |
---|---|---|---|
Provider | Evolving | Evolving | ISA |
Module | Private | Private | Unknown |
Function | Private | Private | Unknown |
Name | Evolving | Evolving | ISA |
Arguments | Evolving | Evolving | ISA |