7.10 SCTP Socket Options

The relatively large number of socket options for SCTP (17 at present writing) reflects the finer grain of control SCTP provides to the application developer. We specify the level as IPPROTO_SCTP.

Several options used to get information about SCTP require that data be passed into the kernel (e.g., association ID and/or peer address). While some implementations of getsockopt support passing data both into and out of the kernel, not all do. The SCTP API defines a sctp_opt_info function (Section 9.11) that hides this difference. On systems on which getsockopt does support this, it is simply a wrapper around getsockopt. Otherwise, it performs the required action, perhaps using a custom ioctl or a new system call. We recommend always using sctp_opt_info when retrieving these options for maximum portability. These options are marked with a dagger () in Figure 7.2 and include SCTP_ASSOCINFO, SCTP_GET_PEER_ADDR_INFO, SCTP_PEER_ADDR_PARAMS, SCTP_PRIMARY_ADDR, SCTP_RTOINFO, and SCTP_STATUS.

SCTP_ADAPTION_LAYER Socket Option

During association initialization, either endpoint may specify an adaption layer indication. This indication is a 32-bit unsigned integer that can be used by the two applications to coordinate any local application adaption layer. This option allows the caller to fetch or set the adaption layer indication that this endpoint will provide to peers.

When fetching this value, the caller will only retrieve the value the local socket will provide to all future peers. To retrieve the peer's adaption layer indication, an application must subscribe to adaption layer events.

SCTP_ASSOCINFO Socket Option

The SCTP_ASSOCINFO socket option can be used for three purposes: (i) to retrieve information about an existing association, (ii) to change the parameters of an existing association, and/or (iii) to set defaults for future associations. When retrieving information about an existing association, the sctp_opt_info function should be used instead of getsockopt. This option takes as input the sctp_assocparams structure.

struct sctp_assocparams {
  sctp_assoc_t sasoc_assoc_id;
  u_int16_t sasoc_asocmaxrxt;
  u_int16_t sasoc_number_peer_destinations;
  u_int32_t sasoc_peer_rwnd;
  u_int32_t sasoc_local_rwnd;
  u_int32_t sasoc_cookie_life;
};

These fields have the following meaning:

• sasoc_assoc_id holds the identification for the association of interest. If this value is set to 0 when calling the setsockopt function, then sasoc_asocmaxrxt and sasoc_cookie_life represent values that are to be set as defaults on the socket. Calling getsockopt will return association-specific information if the association ID is supplied; otherwise, if this field is 0, the default endpoint settings will be returned.

• sasoc_asocmaxrxt holds the maximum number of retransmissions an association will make without acknowledgment before giving up, reporting the peer unusable and closing the association.

• sasoc_number_peer_destinations holds the number of peer destination addresses. It cannot be set, only retrieved.

• sasoc_peer_rwnd holds the peer's current calculated receive window. This value represents the total number of data bytes that can yet be sent. This field is dynamic; as the local endpoint sends data, this value decreases. As the remote application reads data that has been received, this value increases. This value cannot be changed by this socket option call.

• sasoc_local_rwnd represents the local receive window the SCTP stack is currently reporting to the peer. This value is dynamic as well and is influenced by the SO_SNDBUF socket option. This value cannot be changed by this socket option call.

• sasoc_cookie_life represents the number of milliseconds for which a cookie, given to a remote peer, is valid. Each state cookie sent to a peer has a lifetime associated with it to prevent replay attacks. The default value of 60,000 milliseconds can be changed by setting this option with a sasoc_assoc_id value of 0.

We will provide advice on tuning the value of sasoc_asocmaxrxt for performance in Section 23.11. The sasoc_cookie_life can be reduced for greater protection against cookie replay attacks but less robustness to network delay during association initiation. The other values are useful for debugging.

SCTP_AUTOCLOSE Socket Option

This option allows us to fetch or set the autoclose time for an SCTP endpoint. The autoclose time is the number of seconds an SCTP association will remain open when idle. Idle is defined by the SCTP stack as neither endpoint sending or receiving user data. The default is for the autoclose function to be disabled.

The autoclose option is intended to be used in the one-to-many-style SCTP interface (Chapter 9). When this option is set, the integer passed to the option is the number of seconds before an idle connection should be closed; a value of 0 disables autoclose. Only future associations created by this endpoint will be affected by this option; existing associations retain their current setting.

Autoclose can be used by a server to force the closing of idle associations without the server needing to maintain additional state. A server using this feature needs to carefully assess the longest idle time expected on all its associations. Setting the autoclose value smaller than needed results in the premature closing of associations.

SCTP_DEFAULT_SEND_PARAM Socket Option

SCTP has many optional send parameters that are often passed as ancillary data or used with the sctp_sendmsg function call (which is often implemented as a library call that passes ancillary data for the user). An application that wishes to send a large number of messages, all with the same parameters, can use this option to set up the default parameters and thus avoid using ancillary data or the sctp_sendmsg call. This option takes as input the sctp_sndrcvinfo structure.

struct sctp_sndrcvinfo {
  u_int16_t sinfo_stream;
  u_int16_t sinfo_ssn;
  u_int16_t sinfo_flags;
  u_int32_t sinfo_ppid;
  u_int32_t sinfo_context;
  u_int32_t sinfo_timetolive;
  u_int32_t sinfo_tsn;
  u_int32_t sinfo_cumtsn;
  sctp_assoc_t sinfo_assoc_id;
};

These fields are defined as follows:

• sinfo_stream specifies the new default stream to which all messages will be sent.

• sinfo_ssn is ignored when setting the default options. When receiving a message with the recvmsg function or sctp_recvmsg function, this field will hold the value the peer placed in the stream sequence number (SSN) field in the SCTP DATA chunk.

• sinfo_flags dictates the default flags to apply to all future message sends. Allowable flag values can be found in Figure 7.16.

  Figure 7.16. Allowable SCTP flag values for the sinfo_flags field.

  

• sinfo_pid provides the default value to use when setting the SCTP payload protocol identifier in all data transmissions.

• sinfo_context specifies the default value to place in the sinfo_context field, which is provided as a local tag when messages that could not be sent to a peer are retrieved.

• sinfo_timetolive dictates the default lifetime that will be applied to all message sends. The lifetime field is used by SCTP stacks to know when to discard an outgoing message due to excessive delay (prior to its first transmission). If the two endpoints support the partial reliability option, then the lifetime is also used to specify how long a message is valid after its first transmission.

• sinfo_tsn is ignored when setting the default options. When receiving a message with the recvmsg function or sctp_recvmsg function, this field will hold the value the peer placed in the transport sequence number (TSN) field in the SCTP DATA chunk.

• sinfo_cumtsn is ignored when setting the default options. When receiving a message with the recvmsg function or sctp_recvmsg function, this field will hold the current cumulative TSN the local SCTP stack has associated with its remote peer.

• sinfo_assoc_id specifies the association identification that the requester wishes the default parameters to be set against. For one-to-one sockets, this field is ignored.

Note that all default settings will only affect messages sent without their own sctp_sndrcvinfo structure. Any send that provides this structure (e.g., sctp_sendmsg or sendmsg function with ancillary data) will override the default settings. Besides setting the default values, this option may be used to retrieve the current default parameters by using the sctp_opt_info function.

SCTP_DISABLE_FRAGMENTS Socket Option

SCTP normally fragments any user message that does not fit in a single SCTP packet into multiple DATA chunks. Setting this option disables this behavior on the sender. When disabled by this option, SCTP will return the error EMSGSIZE and not send the message. The default behavior is for this option to be disabled; SCTP will normally fragment user messages.

This option may be used by applications that wish to control message sizes, ensuring that every user application message will fit in a single IP packet. An application that enables this option must be prepared to handle the error case (i.e., its message was too big) by either providing application-layer fragmentation of the message or a smaller message.

SCTP_EVENTS Socket Option

This socket option allows a caller to fetch, enable, or disable various SCTP notifications. An SCTP notification is a message that the SCTP stack will send to the application. The message is read as normal data, with the msg_flags field of the recvmsg function being set to MSG_NOTIFICATION. An application that is not prepared to use either recvmsg or sctp_recvmsg should not enable events. Eight different types of events can be subscribed to by using this option and passing an sctp_event_subscribe structure. Any value of 0 represents a non-subscription and a value of 1 represents a subscription.

The sctp_event_subscribe structure takes the following form:

struct sctp_event_subscribe {
  u_int8_t sctp_data_io_event;
  u_int8_t sctp_association_event;
  u_int8_t sctp_address_event;
  u_int8_t sctp_send_failure_event;
  u_int8_t sctp_peer_error_event;
  u_int8_t sctp_shutdown_event;
  u_int8_t sctp_partial_delivery_event;
  u_int8_t sctp_adaption_layer_event;
};

Figure 7.17 summarizes the various events. Further details on notifications can be found in Section 9.14.

SCTP_GET_PEER_ADDR_INFO Socket Option

This option retrieves information about a peer address, including the congestion window, smoothed RTT and MTU. This option may only be used to retrieve information about a specific peer address. The caller provides a sctp_paddrinfo structure with the spinfo_address field filled in with the peer address of interest, and should use sctp_opt_info instead of getsockopt for maximum portability. The sctp_paddrinfo structure has the following format:

struct sctp_paddrinfo {
  sctp_assoc_t spinfo_assoc_id;
  struct sockaddr_storage spinfo_address;
  int32_t spinfo_state;
  u_int32_t spinfo_cwnd;
  u_int32_t spinfo_srtt;
  u_int32_t spinfo_rto;
  u_int32_t spinfo_mtu;
};

The data returned to the caller provides the following:

• spinfo_assoc_id contains association identification information, also provided in the "communication up" notification (SCTP_COMM_UP). This unique value can be used as a shorthand method to represent the association for almost all SCTP operations.

• spinfo_address is set by the caller to inform the SCTP socket on which address to return information. On return, its value should be unchanged.

• spinfo_state holds one or more of the values seen in Figure 7.18.

  Figure 7.18. SCTP peer address states.

  

  An unconfirmed address is one that the peer had listed as a valid address, but the local SCTP endpoint has not been able to confirm that the peer holds that address. An SCTP endpoint confirms an address when a heartbeat or user data, sent to that address, is acknowledged. Note that an unconfirmed address will also not have a valid retransmission timeout (RTO) value. Active addresses represent addresses that are considered available for use.

• spinfo_cwnd represents the current congestion window recorded for the peer address. A description of how the the cwnd value is managed can be found on page 177 of [Stewart and Xie 2001].

• spinfo_srtt represents the current estimate of the smoothed RTT for this address.

• spinfo_rto represents the current retransmission timeout in use for this address.

• spinfo_mtu represents the current path MTU as discovered by path MTU discovery.

One interesting use for this option is to translate an IP address structure into an association identification that can be used in other calls. We will illustrate the use of this socket option in Chapter 23. Another possibility is for the application to track performance to each address of a multihomed peer and update the primary address of the association to the peer's best address. These values are also useful for logging and debugging.

SCTP_I_WANT_MAPPED_V4_ADDR Socket Option

This flag can be used to enable or disable IPv4-mapped addresses on an AF_INET6-type socket. Note that when enabled (which is the default behavior), all IPv4 addresses will be mapped to a IPv6 address before sending to the application. If this option is disabled, the SCTP socket will not map IPv4 addresses and will instead pass them as a sockaddr_in structure.

SCTP_INITMSG Socket Option

This option can be used to get or set the default initial parameters used on an SCTP socket when sending out the INIT message. The option uses the sctp_initmsg structure, which is defined as:

struct sctp_initmsg {
  uint16_t sinit_num_ostreams;
  uint16_t sinit_max_instreams;
  uint16_t sinit_max_attempts;
  uint16_t sinit_max_init_timeo;
};

These fields are defined as follows:

• sinit_num_ostreams represents the number of outbound SCTP streams an application would like to request. This value is not confirmed until after the association finishes the initial handshake, and may be negotiated downward via peer endpoint limitations.

• sinit_max_instreams represents the maximum number of inbound streams the application is prepared to allow. This value will be overridden by the SCTP stack if it is greater than the maximum allowable streams the SCTP stack supports.

• sinit_max_attempts expresses how many times the SCTP stack should send the initial INIT message before considering the peer endpoint unreachable.

• sinit_max_init_timeo represents the maximum RTO value for the INIT timer. During exponential backoff of the initial timer, this value replaces RTO.max as the ceiling for retransmissions. This value is expressed in milliseconds.

Note that when setting these fields, any value set to 0 will be ignored by the SCTP socket. A user of the one-to-many-style socket (described in Section 9.2) may also pass an sctp_initmsg structure in ancillary data during implicit association setup.

SCTP_MAXBURST Socket Option

This socket option allows the application to fetch or set the maximum burst size used when sending packets. When an SCTP implementation sends data to a peer, no more than SCTP_MAXBURST packets are sent at once to avoid flooding the network with packets. An implementation may apply this limit by either: (i) reducing its congestion window to the current flight size plus the maximum burst size times the path MTU, or (ii) using this value as a separate micro-control, sending at most maximum burst packets at any single send opportunity.

SCTP_MAXSEG Socket Option

This socket option allows the application to fetch or set the maximum fragment size used during SCTP fragmentation. This option is similar to the TCP option TCP_MAXSEG described in Section 7.9.

When an SCTP sender receives a message from an application that is larger than this value, the SCTP sender will break the message into multiple pieces for transport to the peer endpoint. The size that the SCTP sender normally uses is the smallest MTU of all addresses associated with the peer. This option overrides this value downward to the value specified. Note that the SCTP stack may fragment a message at a smaller boundary than requested by this option. This smaller fragmentation will occur when one of the paths to the peer endpoint has a smaller MTU than the value requested in the SCTP_MAXSEG option.

This value is an endpoint-wide setting and may affect more than one association in the one-to-many interface style.

SCTP_NODELAY Socket Option

If set, this option disables SCTP's Nagle algorithm. This option is OFF by default (i.e., the Nagle algorithm is ON by default). SCTP's Nagle algorithm works identically to TCP's except that it is trying to coalesce multiple DATA chunks as opposed to simply coalescing bytes on a stream. For a further discussion of the Nagle algorithm, see TCP_MAXSEG.

SCTP_PEER_ADDR_PARAMS Socket Option

This socket option allows an application to fetch or set various parameters on an association. The caller provides the sctp_paddrparams structure, filling in the association identification. The sctp_paddrparams structure has the following format:

struct sctp_paddrparams {
  sctp_assoc_t spp_assoc_id;
  struct sockaddr_storage spp_address;
  u_int32_t spp_hbinterval;
  u_int16_t spp_pathmaxrxt;
};

These fields are defined as follows:

• spp_assoc_id holds the association identification for the information being requested or set. If this value is set to 0, the endpoint default values are set or retrieved instead of the association-specific values.

• spp_address specifies the IP address for which these parameters are being requested or set. If the spp_assoc_id field is set to 0, then this field is ignored.

• spp_hbinterval is the interval between heartbeats. A value of SCTP_NO_HB disables heartbeats. A value of SCTP_ISSUE_HB requests an on-demand heartbeat. Any other value changes the heartbeat interval to this value in milliseconds. When setting the default parameters, the value of SCTP_ISSUE_HB is not allowed.

• spp_hbpathmaxrxt holds the number of retransmissions that will be attempted on this destination before it is declared INACTIVE. When an address is declared INACTIVE, if it is the primary address, an alternate address will be chosen as the primary.

SCTP_PRIMARY_ADDR Socket Option

This socket option fetches or sets the address that the local endpoint is using as primary. The primary address is used, by default, as the destination address for all messages sent to a peer. To set this value, the caller fills in the association identification and the peer's address that should be used as the primary address. The caller passes this information in a sctp_setprim structure, which is defined as:

struct sctp_setprim {
  sctp_assoc_t            ssp_assoc_id;
  struct sockaddr_storage ssp_addr;
};

These fields are defined as follows:

• spp_assoc_id specifies the association identification on which the requester wishes to set or retrieve the current primary address. For the one-to-one style, this field is ignored.

• sspp_addr specifies the primary address, which must be an address belonging to the peer. If the operation is a setsockopt function call, then the value in this field represents the new peer address the requester would like to be made into the primary destination address.

Note that retrieving the value of this option on a one-to-one socket that has only one local address associated with it is the same as calling getsockname.

SCTP_RTOINFO Socket Option

This socket option can be used to fetch or set various RTO information on a specific association or the default values used by this endpoint. When fetching, the caller should use sctp_opt_info instead of getsockopt for maximum portability. The caller provides a sctp_rtoinfo structure of the following form:

struct sctp_rtoinfo {
  sctp_assoc          srto_assoc_id;
  uint32_t            srto_initial;
  uint32_t            srto_max;
  uint32_t            srto_min;
};

These fields are defined as follows:

• srto_assoc_id holds either the specific association of interest or 0. If this field contains the value 0, then the system's default parameters are affected by the call.

• srto_initial contains the initial RTO value used for a peer address. The initial RTO is used when sending an INIT chunk to the peer. This value is in milliseconds and has a default value of 3,000.

• srto_max contains the maximum RTO value that will be used when an update is made to the retransmission timer. If the updated value is larger than the RTO maximum, then the RTO maximum is used as the RTO instead of the calculated value. The default value for this field is 60,000 milliseconds.

• srto_min contains the minimum RTO value that will be used when starting a retransmission timer. Anytime an update is made to the RTO timer, the RTO minimum value is checked against the new value. If the new value is smaller than the minimum, the minimum replaces the new value. The default value for this field is 1,000 milliseconds.

A value of 0 for srto_initial, srto_max, or srto_min indicates that the default value currently set should not be changed. All time values are expressed in milliseconds. We provide guidance on setting these timers for performance in Section 23.11.

SCTP_SET_PEER_PRIMARY_ADDR Socket Option

Setting this option causes a message to be sent that requests that the peer set the specified local address as its primary address. The caller provides an sctp_setpeerprim structure and must fill in both the association identification and a local address to request the peer mark as its primary. The address provided must be one of the local endpoint's bound addresses. The sctp_setpeerprim structure is defined as follows:

struct sctp_setpeerprim {
  sctp_assoc_t            sspp_assoc_id;
  struct sockaddr_storage sspp_addr;
};

These fields are defined as follows:

• sspp_assoc_id specifies the association identification on which the requester wishes to set the primary address. For the one-to-one style, this field is ignored.

• sspp_addr holds the local address that the requester wishes to ask the peer system to set as the primary address.

This feature is optional, and must be supported by both endpoints to operate. If the local endpoint does not support the feature, an error of EOPNOTSUPP will be returned to the caller. If the remote endpoint does not support the feature, an error of EINVAL will be returned to the caller. Note that this value may only be set and cannot be retrieved.

SCTP_STATUS Socket Option

This socket option will retrieve the current state of an SCTP association. The caller should use sctp_opt_info instead of getaddrinfo for maximum portability. The caller provides an sctp_status structure, filling in the association identification field, sstat_assoc_id. The structure will be returned filled in with the information pertaining to the requested association. The sctp_status structure has the following format:

struct sctp_status {
  sctp_assoc_t sstat_assoc_id;
  int32_t sstat_state;
  u_int32_t sstat_rwnd;
  u_int16_t sstat_unackdata;
  u_int16_t sstat_penddata;
  u_int16_t sstat_instrms;
  u_int16_t sstat_outstrms;
  u_int32_t sstat_fragmentation_point;
  struct sctp_paddrinfo sstat_primary;
};

These fields are defined as follows:

• sstat_assoc_id holds the association identification.

• sstat_state holds one of the values found in Figure 7.19 and indicates the overall state of the association. A detailed depiction of the states an SCTP endpoint goes through during association setup or shutdown can be found in Figure 2.8.

  Figure 7.19. SCTP states.

  

• sstat_rwnd holds our endpoint's current estimate of the peer's receive window.

• sstat_unackdata holds the number of unacknowledged DATA chunks pending for the peer.

• sstat_penddata holds the number of unread DATA chunks that the local endpoint is holding for the application to read.

• sstat_instrms holds the number of streams the peer is using to send data to this endpoint.

• sstat_outstrms holds the number of allowable streams that this endpoint can use to send data to the peer.

• sstat_fragmentation_point contains the current value the local SCTP endpoint is using as the fragmentation point for user messages. This value is normally the smallest MTU of all destinations, or possibly a smaller value set by the local application with SCTP_MAXSEG.

• sstat_primary holds the current primary address. The primary address is the default address used when sending data to the peer endpoint.

These values are useful for diagnostics and for determining the characteristics of the session; for example, the sctp_get_no_strms function in Section 10.2 will use the sstat_outstrms member to determine how many streams are available for outbound use. A low sstat_rwnd and/or a high sstat_unackdata value can be used to determine that the peer's receive socket buffer is becoming full, which can be used as a cue to the application to slow down transmission if possible. The sstat_fragmentation_point can be used by some applications to reduce the number of fragments that SCTP has to create, by sending smaller application messages.