sctp provider

Skip to end of metadata
Go to start of metadata

sctp Provider

The sctp provider provides probes for tracing the SCTP protocol.

This provider is under development and is not yet available.

Top

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.

Top

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 *  

Top

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;

Top

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.

Top

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.

Top

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.

Top

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.

Top

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.

Top

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.

Top

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

Top

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
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Oracle community and they might not be employed or in any way formally affiliated with Oracle. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Oracle nor any other party necessarily agrees with them.