SCTP user-land implementation (usrsctp)

SCTP is a message oriented, reliable transport protocol with direct support for multihoming that runs on top of IP or UDP, and supports both v4 and v6 versions.

Like TCP, SCTP provides reliable, connection oriented data delivery with congestion control. Unlike TCP, SCTP also provides message boundary preservation, ordered and unordered message delivery, multi-streaming and multi-homing. Detection of data corruption, loss of data and duplication of data is achieved by using checksums and sequence numbers. A selective retransmission mechanism is applied to correct loss or corruption of data.

In this manual the socket API for the SCTP User-land implementation will be described. It is based on RFC 6458. The main focus of this document is on pointing out the differences to the SCTP Sockets API. For all aspects of the sockets API that are not mentioned in this document, please refer to RFC 6458. Questions about SCTP itself can hopefully be answered by RFC 4960.

Getting Started

The user-land stack has been tested on FreeBSD 10.0, Ubuntu 11.10, Windows 7, Mac OS X 10.6, and Mac OS X 10.7. The current version of the user-land stack is provided on github. Download the tarball and untar it in a folder of your choice. The tarball contains all the sources to build the libusrsctp, which has to be linked to the object file of an example program. In addition there are two applications in the folder programs that can be built and run.

Building the Library and the Applications

Unix-like Operating Systems

In the folder usrsctp type

$ ./bootstrap
$ ./configure
$ make

Now, the library libusrsctp.la has been built in the subdirectory usrsctplib, and the example programs are ready to run from the subdirectory programs.

If you have root privileges or are in the sudoer group, you can install the library in /usr/local/lib and copy the header file to /usr/include with the command

$ sudo make install

Windows

On Windows you need a compiler like Microsoft Visual Studio. You can build the library and the example programs with the command line tool of the compiler by typing

$ nmake -f Makefile.nmake

in the directory usrsctp.

CMake

Create a directory outside the usrsctp directory, enter it and generate files by typing

$ cmake <path-to-usrsctp-sources>
$ cmake --build .

By default CMake generates a DEBUG build with verbose output.

Running the Test Programs

Several test programs are included, including a discard server and a client. You can run both to send data from the client to the server. The client reads data from stdin and sends them to the server, which prints the message in the terminal and discards it. The sources of the server are also provided here and those of the client here.

Using UDP Encapsulation

Both programs can either send data over SCTP directly or use UDP encapsulation, thus encapsulating the SCTP packet in a UDP datagram. The first mode works on loopback or in a protected setup without any NAT boxes involved. In all other cases it is better to use UDP encapsulation.

The usage of the discard_server is

$ discard_server [local_encaps_port remote_encaps_port]

For UDP encapsulation the ports have to be specified. The local and remote encapsulation ports can be arbitrarily set. For example, you can call

$ ./discard_server 11111 22222

on a Unix-like OS and

$ discard_server.exe 11111 22222

on Windows.

The client needs two additional parameters, the server's address and its port. Its usage is

$ client remote_addr remote_port [local_port local_encaps_port remote_encaps_port]

The remote address is the server‘s address. If client and server are started on the same machine, the loopback address 127.0.0.1 can be used for Unix-like OSs and the local address on Windows. The discard port is 9, thus 9 has to be taken as remote port. The encapsulation ports have to match those of the server, i.e. the server’s local_encaps_port is the client's remote_encaps_port and vice versa. Thus, the client can be started with

$ ./client 127.0.0.1 9 0 22222 11111

on a Unix-like OS and

$ client.exe 192.168.0.1 9 0 22222 11111

on Windows provided your local IP address is 192.168.0.1.

Sending over SCTP

To send data over SCTP directly you might need root privileges because raw sockets are used. Thus instead of specifying the encapsulation ports you have to start the programs prepending sudo or in case of Windows start the program from an administrator console.

Using the Callback API

Instead of asking constantly for new data, a callback API can be used that is triggered by SCTP. A callback function has to be registered that will be called whenever data is ready to be delivered to the application.

The discard_server has a flag to switch between the two modi. If use_cb is set to 1, the callback API will be used. To change the setting, just set the flag and compile the program again.

Basic Operations

All system calls start with the prefix usrsctp_ to distinguish them from the kernel variants. Some of them are changed to account for the different demands in the userland environment.

Differences to RFC 6458

usrsctp_init()

Every application has to start with usrsctp_init(). This function calls sctp_init() and reserves the memory necessary to administer the data transfer. The function prototype is

void usrsctp_init(uint16_t udp_port)

As it is not always possible to send data directly over SCTP because not all NAT boxes can process SCTP packets, the data can be sent over UDP. To encapsulate SCTP into UDP a UDP port has to be specified, to which the datagrams can be sent. This local UDP port is set with the parameter udp_port. The default value is 9899, the standard UDP encapsulation port. If UDP encapsulation is not necessary, the UDP port has to be set to 0.

usrsctp_finish()

At the end of the program usrsctp_finish() should be called to free all the memory that has been allocated before. The function prototype is

int usrsctp_finish(void)

The return code is 0 on success and -1 in case of an error.

usrsctp_socket()

A representation of an SCTP endpoint is a socket. Is it created with usrsctp_socket(). The function prototype is:

struct socket *
usrsctp_socket(int domain,
               int type,
               int protocol,
               int (*receive_cb)(struct socket *sock,
                                 union sctp_sockstore addr,
                                 void *data,
                                 size_t datalen,
                                 struct sctp_rcvinfo,
                                 int flags,
                                 void *ulp_info),
               int (*send_cb)(struct socket *sock,
                              uint32_t sb_free),
               uint32_t sb_threshold,
               void *ulp_info)

The arguments taken from RFC 6458 are:

  • domain: PF_INET or PF_INET6 can be used.
  • type: In case of a one-to-many style socket it is SOCK_SEQPACKET, in case of a one-to-one style socket it is SOCK_STREAM. For an explanation of the differences between the socket types please refer to RFC 6458.
  • protocol: Set IPPROTO_SCTP.

In usrsctp, a callback API can be used.

  • The function pointers of the receive and send callbacks are new arguments to the socket call. If no callback API is used, these must be NULL.
  • The sb_threshold specifies the amount of free space in the send socket buffer before the send function in the application is called. If a send callback function is specified and sb_threshold is 0, the function is called whenever there is room in the send socket buffer.
  • Additional data may be passed along within the ulp_info parameter. This value will be passed to the receive_cb when it is invoked.

On success usrsctp_socket() returns the pointer to the new socket in the struct socket data type. It will be needed in all other system calls. In case of a failure NULL is returned and errno is set to the appropriate error code.

usrsctp_close()

The function prototype of usrsctp_close() is

void usrsctp_close(struct socket *so)

Thus the only difference is the absence of a return code.

Same Functionality as RFC 6458

The following functions have the same functionality as their kernel pendants. There prototypes are described in the following subsections. For a detailed description please refer to RFC 6458.

usrsctp_bind()

int
usrsctp_bind(struct socket *so,
             struct sockaddr *addr,
             socklen_t addrlen)
  • so: Pointer to the socket as returned by usrsctp_socket().
  • addr: The address structure (struct sockaddr_in for an IPv4 address or struct sockaddr_in6 for an IPv6 address).
  • addrlen: The size of the address structure.

usrsctp_bind() returns 0 on success and -1 in case of an error.

usrsctp_listen()

int
usrsctp_listen(struct socket *so,
               int backlog)
  • so: Pointer to the socket as returned by usrsctp_socket().
  • backlog: If backlog is non-zero, enable listening, else disable listening.

usrsctp_listen() returns 0 on success and -1 in case of an error.

usrsctp_accept()

struct socket *
usrsctp_accept(struct socket *so,
               struct sockaddr * addr,
               socklen_t * addrlen)
  • so: Pointer to the socket as returned by usrsctp_socket().
  • addr: On return, the primary address of the peer (struct sockaddr_in for an IPv4 address or struct sockaddr_in6 for an IPv6 address).
  • addrlen: Size of the returned address structure.

usrsctp_accept() returns the accepted socket on success and NULL in case of an error.

usrsctp_connect()

int
usrsctp_connect(struct socket *so,
                struct sockaddr *name,
                socklen_t addrlen)
  • so: Pointer to the socket as returned by usrsctp_socket().
  • name: Address of the peer to connect to (struct sockaddr_in for an IPv4 address or struct sockaddr_in6 for an IPv6 address).
  • addrlen: Size of the peer's address.

usrsctp_connect() returns 0 on success and -1 in case of an error.

usrsctp_shutdown()

int
usrsctp_shutdown(struct socket *so, int how)
  • so: Pointer to the socket of the association to be closed
  • how: Specifies the type of shutdown. The values are as follows:
    • SHUT_RD: Disables further receive operations. No SCTP protocol action is taken.
    • SHUT_WR: Disables further send operations, and initiates the SCTP shutdown sequence.
    • SHUT_RDWR: Disables further send and receive operations, and initiates the SCTP shutdown sequence.

usrsctp_shutdown() returns 0 on success and -1 in case of an error.

Sending and Receiving Data

Since the publication of RFC 6458 there is only one function for sending and one for receiving that is not deprecated. Therefore, only these two are described here.

usrsctp_sendv()

ssize_t
usrsctp_sendv(struct socket *so,
              const void *data,
              size_t len,
              struct sockaddr *addrs,
              int addrcnt,
              void *info,
              socklen_t infolen,
              unsigned int infotype,
              int flags)
  • so: The socket to send data on.
  • data: As it is more convenient to send data in a buffer and not a struct iovec data structure, we chose to pass the data as a void pointer.
  • len: Length of the data.
  • addrs: In this version of usrsctp at most one destination address is supported. In the case of a connected socket, the parameter addrs can be set to NULL.
  • addrcnt: Number of addresses. As at most one address is supported, addrcnt is 0 if addrs is NULL and 1 otherwise.
  • info: Additional information for a message is stored in void *info. The data types struct sctp_sndinfo, struct sctp_prinfo, and struct sctp_sendv_spa are supported as defined in RFC 6458. Support for struct sctp_authinfo is not implemented yet, therefore, errno is set EINVAL and -1 will be returned, if it is used.
  • infolen: Length of info in bytes.
  • infotype: Identifies the type of the information provided in info. Possible values are
    • SCTP_SENDV_NOINFO
    • SCTP_SENDV_SNDINFO
    • SCTP_SENDV_PRINFO
    • SCTP_SENDV_SPA (For additional information please refer to RFC 6458.)
  • flags: Flags as described in RFC 6458.

usrsctp_sendv() returns the number of bytes sent, or -1 if an error occurred. The variable errno is then set appropriately.

usrsctp_recvv()

ssize_t
usrsctp_recvv(struct socket *so,
             void *dbuf,
             size_t len,
             struct sockaddr *from,
             socklen_t * fromlen,
             void *info,
             socklen_t *infolen,
             unsigned int *infotype,
             int *msg_flags)
  • so: The socket to receive data on.
  • dbuf: Analog to usrsctp_sendv() the data is returned in a buffer.
  • len: Length of the buffer in bytes.
  • from: A pointer to an address to be filled with the sender of the received message's address.
  • fromlen: An in/out parameter describing the from length.
  • info: A pointer to the buffer to hold the attributes of the received message. The structure type of info is determined by the infotype parameter. The attributes returned in info have to be handled in the same way as specified in RFC 6458.
  • infolen: An in/out parameter describing the size of the info buffer.
  • infotype: On return, *infotype is set to the type of the info buffer. The current defined values are
    • SCTP_RECVV_NOINFO
    • SCTP_RECVV_RCVINFO
    • SCTP_RECVV_NXTINFO
    • SCTP_RECVV_RN (A detailed description is given in RFC 6458)
  • flags: A pointer to an integer to be filled with any message flags (e.g., MSG_NOTIFICATION). Note that this field is an in/out parameter. Options for the receive may also be passed into the value (e.g., MSG_EOR). Returning from the call, the flags' value will differ from its original value.

usrsctp_recvv() returns the number of bytes received, or -1 if an error occurred. The variable errno is then set appropriately.

Socket Options

Socket options are used to change the default behavior of socket calls. Their behavior is specified in RFC 6458. The functions to get or set them are

int
usrsctp_getsockopt(struct socket *so,
                     int level,
                     int optname,
                     void *optval,
                     socklen_t *optlen)

and

int
usrsctp_setsockopt(struct socket *so,
                     int level,
                     int optname,
                     const void *optval,
                     socklen_t optlen)

and the arguments are

  • so: The socket of type struct socket.
  • level: Set to IPPROTO_SCTP for all SCTP options.
  • optname: The option name as specified in The Socket Options table below.
  • optval: The buffer to store the value of the option as specified in the second column of Socket Options below.
  • optlen: The size of the buffer (or the length of the option returned in case of usrsctp_getsockopt).

These functions return 0 on success and -1 in case of an error.

Socket Options supported by usrsctp

OptionDatatyper/w
SCTP_RTOINFOstruct sctp_rtoinfor/w
SCTP_ASSOCINFOstruct sctp_assocparamsr/w
SCTP_INITMSGstruct sctp_initmsgr/w
SCTP_NODELAYintr/w
SCTP_AUTOCLOSEintr/w
SCTP_PRIMARY_ADDRstruct sctp_setprimr/w
SCTP_ADAPTATION_LAYERstruct sctp_setadaptationr/w
SCTP_DISABLE_FRAGMENTSintr/w
SCTP_PEER_ADDR_PARAMSstruct sctp_paddrparamsr/w
SCTP_I_WANT_MAPPED_V4_ADDRintr/w
SCTP_MAXSEGstruct sctp_assoc_valuer/w
SCTP_DELAYED_SACKstruct sctp_sack_infor/w
SCTP_FRAGMENT_INTERLEAVEintr/w
SCTP_PARTIAL_DELIVERY_POINTintr/w
SCTP_HMAC_IDENTstruct sctp_hmacalgor/w
SCTP_AUTH_ACTIVE_KEYstruct sctp_authkeyidr/w
SCTP_AUTO_ASCONFintr/w
SCTP_MAX_BURSTstruct sctp_assoc_valuer/w
SCTP_CONTEXTstruct sctp_assoc_valuer/w
SCTP_EXPLICIT_EORintr/w
SCTP_REUSE_PORTintr/w
SCTP_EVENTstruct sctp_eventr/w
SCTP_RECVRCVINFOintr/w
SCTP_RECVNXTINFOintr/w
SCTP_DEFAULT_SNDINFOstruct sctp_sndinfor/w
SCTP_DEFAULT_PRINFOstruct sctp_default_prinfor/w
SCTP_REMOTE_UDP_ENCAPS_PORTintr/w
SCTP_ENABLE_STREAM_RESETstruct sctp_assoc_valuer/w
SCTP_STATUSstruct sctp_statusr
SCTP_GET_PEER_ADDR_INFOstruct sctp_paddrinfor
SCTP_PEER_AUTH_CHUNKSstruct sctp_authchunksr
SCTP_LOCAL_AUTH_CHUNKSstruct sctp_authchunksr
SCTP_GET_ASSOC_NUMBERuint32_tr
SCTP_GET_ASSOC_ID_LISTstruct sctp_assoc_idsr
SCTP_RESET_STREAMSstruct sctp_reset_streamsw
SCTP_RESET_ASSOCstruct sctp_assoc_tw
SCTP_ADD_STREAMSstruct sctp_add_streamsw

Further usage details are described in RFC 6458, RFC 6525, and draft-ietf-tsvwg-sctp-udp-encaps-03 (work in progress).

Sysctl variables

In kernel implementations like for instance FreeBSD, it is possible to change parameters in the operating system. These parameters are called sysctl variables.

In usrsctp applications can set or retrieve these variables with the functions

void usrsctp_sysctl_set_ ## (uint32_t value)

and

uint32_t usrsctp_sysctl_get_ ## (void)

respectively, where ## stands for the name of the variable.

In the following paragraphs a short description of the parameters will be given.

Manipulate Memory

usrsctp_sysctl_set_sctp_sendspace()

The space of the available send buffer can be changed from its default value of 262,144 bytes to a value between 0 and 2^32 - 1 bytes.

usrsctp_sysctl_set_sctp_recvspace()

The space of the available receive buffer can be changed from its default value of 262,144 bytes to a value between 0 and 2^32 - 1 bytes.

usrsctp_sysctl_set_sctp_hashtblsize()

The TCB (Thread Control Block) hash table sizes, i.e. the size of one TCB in the hash table, can be tuned between 1 and 2^32 - 1 bytes. The default value is 1,024 bytes. A TCB contains for instance pointers to the socket, the endpoint, information about the association and some statistic data.

usrsctp_sysctl_set_sctp_pcbtblsize()

The PCB (Protocol Control Block) hash table sizes, i.e. the size of one PCB in the hash table, can be tuned between 1 and 2^32 - 1 bytes. The default value is 256 bytes. The PCB contains all variables that characterize an endpoint.

usrsctp_sysctl_set_sctp_system_free_resc_limit()

This parameters tunes the maximum number of cached resources in the system. It can be set between 0 and 2^32 - 1. The default value is 1000.

usrsctp_sysctl_set_sctp_asoc_free_resc_limit()

This parameters tunes the maximum number of cached resources in an association. It can be set between 0 and 2^32 - 1. The default value is 10.

usrsctp_sysctl_set_sctp_mbuf_threshold_count()

Data is stored in mbufs. Several mbufs can be chained together. The maximum number of small mbufs in a chain can be set with this parameter, before an mbuf cluset is used. The default is 5.

usrsctp_sysctl_set_sctp_add_more_threshold()

TBD This parameter configures the threshold below which more space should be added to a socket send buffer. The default value is 1452 bytes.

Configure RTO

The retransmission timeout (RTO), i.e. the time that controls the retransmission of messages, has several parameters, that can be changed, for example to shorten the time, before a message is retransmitted. The range of these parameters is between 0 and 2^32 - 1ms.

usrsctp_sysctl_set_sctp_rto_max_default()

The default value for the maximum retransmission timeout in ms is 60,000 (60secs).

usrsctp_sysctl_set_sctp_rto_min_default()

The default value for the minimum retransmission timeout in ms is 1,000 (1sec).

usrsctp_sysctl_set_sctp_rto_initial_default()

The default value for the initial retransmission timeout in ms is 3,000 (3sec). This value is only needed before the first calculation of a round trip time took place.

usrsctp_sysctl_set_sctp_init_rto_max_default()

The default value for the maximum retransmission timeout for an INIT chunk in ms is 60,000 (60secs).

Set Timers

usrsctp_sysctl_set_sctp_valid_cookie_life_default()

A cookie has a specified life time. If it expires the cookie is not valid any more and an ABORT is sent. The default value in ms is 60,000 (60secs).

usrsctp_sysctl_set_sctp_heartbeat_interval_default()

Set the default time between two heartbeats. The default is 30,000ms.

usrsctp_sysctl_set_sctp_shutdown_guard_time_default()

If a SHUTDOWN is not answered with a SHUTDOWN-ACK while the shutdown guard timer is still running, the association will be aborted after the default of 180secs.

usrsctp_sysctl_set_sctp_pmtu_raise_time_default()

TBD To set the size of the packets to the highest value possible, the maximum transfer unit (MTU) of the complete path has to be known. The default time interval for the path mtu discovery is 600secs.

usrsctp_sysctl_set_sctp_secret_lifetime_default()

TBD The default secret lifetime of a server is 3600secs.

usrsctp_sysctl_set_sctp_vtag_time_wait()

TBD Vtag time wait time, 0 disables it. Default: 60secs

Set Failure Limits

Transmissions and retransmissions of messages might fail. To protect the system against too many retransmissions, limits have to be defined.

usrsctp_sysctl_set_sctp_init_rtx_max_default()

The default maximum number of retransmissions of an INIT chunks is 8, before an ABORT is sent.

usrsctp_sysctl_set_sctp_assoc_rtx_max_default()

This parameter sets the maximum number of failed retransmissions before the association is aborted. The default value is 10.

usrsctp_sysctl_set_sctp_path_rtx_max_default()

This parameter sets the maximum number of path failures before the association is aborted. The default value is 5. Notice that the number of paths multiplied by this value should be equal to sctp_assoc_rtx_max_default. That means that the default configuration is good for two paths.

usrsctp_sysctl_set_sctp_max_retran_chunk()

The parameter configures how many times an unlucky chunk can be retransmitted before the association aborts. The default is set to 30.

usrsctp_sysctl_set_sctp_path_pf_threshold()

TBD Default potentially failed threshold. Default: 65535

usrsctp_sysctl_set_sctp_abort_if_one_2_one_hits_limit()

TBD When one-2-one hits qlimit abort. Default: 0

Control the Sending of SACKs

usrsctp_sysctl_set_sctp_sack_freq_default()

The SACK frequency defines the number of packets that are awaited, before a SACK is sent. The default value is 2.

usrsctp_sysctl_set_sctp_delayed_sack_time_default()

As a SACK (Selective Acknowlegment) is sent after every other packet, a timer is set to send a SACK in case another packet does not arrive in due time. The default value for this timer is 200ms.

usrsctp_sysctl_set_sctp_strict_sacks()

TBD This is a flag to turn the controlling of the coherence of SACKs on or off. The default value is 1 (on).

usrsctp_sysctl_set_sctp_nr_sack_on_off()

If a slow hosts receives data on a lossy link it is possible that its receiver window is full and new data can only be accepted if one chunk with a higher TSN (Transmission Sequence Number) that has previously been acknowledged is dropped. As a consequence the sender has to store data, even if they have been acknowledged in case they have to be retransmitted. If this behavior is not necessary, non-renegable SACKs can be turned on. By default the use of non-renegable SACKs is turned off.

usrsctp_sysctl_set_sctp_enable_sack_immediately()

In some cases it is not desirable to wait for the SACK timer to expire before a SACK is sent. In these cases a bit called SACK-IMMEDIATELY (see draft-tuexen-tsvwg-sctp-sack-immediately-09) can be set to provoke the instant sending of a SACK. The default is to turn it off.

usrsctp_sysctl_set_sctp_L2_abc_variable()

TBD SCTP ABC max increase per SACK (L). Default: 1

Change Max Burst

Max burst defines the maximum number of packets that may be sent in one flight.

usrsctp_sysctl_set_sctp_max_burst_default()

The default value for max burst is 0, which means that the number of packets sent as a flight is not limited by this parameter, but may be by another one, see the next paragraph.

usrsctp_sysctl_set_sctp_use_cwnd_based_maxburst()

The use of max burst is based on the size of the congestion window (cwnd). This parameter is set by default.

usrsctp_sysctl_set_sctp_hb_maxburst()

Heartbeats are mostly used to verify a path. Their number can be limited. The default is 4.

usrsctp_sysctl_set_sctp_fr_max_burst_default()

In the state of fast retransmission the number of packet bursts can be limited. The default value is 4.

Handle Chunks

usrsctp_sysctl_set_sctp_peer_chunk_oh()

In order to keep track of the peer‘s advertised receiver window, the sender calculates the window by subtracting the amount of data sent. Yet, some OSs reduce the receiver window by the real space needed to store the data. This parameter sets the additional amount to debit the peer’s receiver window per chunk sent. The default value is 256, which is the value needed by FreeBSD.

usrsctp_sysctl_set_sctp_max_chunks_on_queue()

This parameter sets the maximum number of chunks that can be queued per association. The default value is 512.

usrsctp_sysctl_set_sctp_min_split_point()

TBD The minimum size when splitting a chunk is 2904 bytes by default.

usrsctp_sysctl_set_sctp_chunkscale()

TBD This parameter can be tuned for scaling of number of chunks and messages. The default is10.

usrsctp_sysctl_set_sctp_min_residual()

TBD This parameter configures the minimum size of the residual data chunk in the second part of the split. The default is 1452.

Calculate RTT

The calculation of the round trip time (RTT) depends on several parameters.

usrsctp_sysctl_set_sctp_rttvar_bw()

TBD Shift amount for bw smoothing on rtt calc. Default: 4

usrsctp_sysctl_set_sctp_rttvar_rtt()

TBD Shift amount for rtt smoothing on rtt calc. Default: 5

usrsctp_sysctl_set_sctp_rttvar_eqret()

TBD What to return when rtt and bw are unchanged. Default: 0

Influence the Congestion Control

The congestion control should protect the network against fast senders.

usrsctp_sysctl_set_sctp_ecn_enable

Explicit congestion notifications are turned on by default.

usrsctp_sysctl_set_sctp_default_cc_module()

This parameter sets the default algorithm for the congestion control. Default is 0, i.e. the one specified in RFC 4960.

usrsctp_sysctl_set_sctp_initial_cwnd()

Set the initial congestion window in MTUs. The default is 3.

usrsctp_sysctl_set_sctp_use_dccc_ecn()

TBD Enable for RTCC CC datacenter ECN. Default: 1

usrsctp_sysctl_set_sctp_steady_step()

TBD How many the sames it takes to try step down of cwnd. Default: 20

Configure AUTH and ADD-IP

An important extension of SCTP is the dynamic address reconfiguration (see RFC 5061), also known as ADD-IP, which allows the changing of addresses during the lifetime of an association. For this feature the AUTH extension (see RFC 4895) is necessary.

usrsctp_sysctl_set_sctp_auto_asconf()

If SCTP Auto-ASCONF is enabled, the peer is informed automatically when a new address is added or removed. This feature is enabled by default.

usrsctp_sysctl_set_sctp_multiple_asconfs()

By default the sending of multiple ASCONFs is disabled.

usrsctp_sysctl_set_sctp_auth_enable()

The use of AUTH, which is normally turned on, can be disabled by setting this parameter to 0.

usrsctp_sysctl_set_sctp_asconf_auth_nochk()

It is also possible to disable the requirement to use AUTH in conjunction with ADD-IP by setting this parameter to 1.

Concurrent Multipath Transfer (CMT)

A prominent feature of SCTP is the possibility to use several addresses for the same association. One is the primary path, and the others are needed in case of a path failure. Using CMT the data is sent on several paths to enhance the throughput.

usrsctp_sysctl_set_sctp_cmt_on_off()

To turn CMT on, this parameter has to be set to 1.

usrsctp_sysctl_set_sctp_cmt_use_dac()

To use delayed acknowledgments with CMT this parameter has to be set to 1.

usrsctp_sysctl_set_sctp_buffer_splitting()

For CMT it makes sense to split the send and receive buffer to have shares for each path. By default buffer splitting is turned off.

Network Address Translation (NAT)

To be able to pass NAT boxes, the boxes have to handle SCTP packets in a specific way.

usrsctp_sysctl_set_sctp_nat_friendly()

SCTP NAT friendly operation. Default:1

usrsctp_sysctl_set_sctp_inits_include_nat_friendly()

Enable sending of the nat-friendly SCTP option on INITs. Default: 0

usrsctp_sysctl_set_sctp_udp_tunneling_port()

Set the SCTP/UDP tunneling port. Default: 9899

SCTP Mobility

usrsctp_sysctl_set_sctp_mobility_base()

TBD Enable SCTP base mobility. Default: 0

usrsctp_sysctl_set_sctp_mobility_fasthandoff()

TBD Enable SCTP fast handoff. default: 0

Miscellaneous

usrsctp_sysctl_set_sctp_no_csum_on_loopback()

Calculating the checksum for packets sent on loopback is turned off by default. To turn it on, set this parameter to 0.

usrsctp_sysctl_set_sctp_nr_outgoing_streams_default()

The peer is notified about the number of outgoing streams in the INIT or INIT-ACK chunk. The default is 10.

usrsctp_sysctl_set_sctp_do_drain()

Determines whether SCTP should respond to the drain calls. Default: 1

usrsctp_sysctl_set_sctp_strict_data_order()

TBD Enforce strict data ordering, abort if control inside data. Default: 0

usrsctp_sysctl_set_sctp_default_ss_module()

Set the default stream scheduling module. Implemented modules are:

  • SCTP_SS_DEFAULT
  • SCTP_SS_ROUND_ROBIN
  • SCTP_SS_ROUND_ROBIN_PACKET
  • SCTP_SS_PRIORITY
  • SCTP_SS_FAIR_BANDWITH
  • SCTP_SS_FIRST_COME

usrsctp_sysctl_set_sctp_default_frag_interleave()

TBD Default fragment interleave level. Default: 1

usrsctp_sysctl_set_sctp_blackhole()

TBD Enable SCTP blackholing. Default: 0

usrsctp_sysctl_set_sctp_logging_level()

Set the logging level. The default is 0.

usrsctp_sysctl_set_sctp_debug_on()

Turn debug output on or off. It is disabled by default. To obtain debug output, SCTP_DEBUG has to be set as a compile flag.

sysctl variables supported by usrsctp

ParameterMeaningDefault Value
sctp_sendspaceSend buffer space1864135
sctp_recvspaceReceive buffer space1864135
sctp_hashtblsizeTunable for TCB hash table sizes1024
sctp_pcbtblsizeTunable for PCB hash table sizes256
sctp_system_free_resc_limitCached resources in the system1000
sctp_asoc_free_resc_limitCashed resources in an association10
sctp_rto_max_defaultDefault value for RTO_max60000ms
sctp_rto_min_defaultDefault value for RTO_min1000ms
sctp_rto_initial_defaultDefault value for RTO_initial3000ms
sctp_init_rto_max_defaultDefault value for the maximum RTO for sending an INIT60000ms
sctp_valid_cookie_life_defaultValid cookie life time60000ms
sctp_init_rtx_max_defaultMaximum number of INIT retransmissions8
sctp_assoc_rtx_max_defaultMaximum number of failed retransmissions before the association is aborted10
sctp_path_rtx_max_defaultMaximum number of failed retransmissions before a path fails5
sctp_ecn_enableEnabling explicit congestion notifications1
sctp_strict_sacksControl the coherence of SACKs1
sctp_delayed_sack_time_defaultDefault delayed SACK timer200ms
sctp_sack_freq_defaultDefault SACK frequency2
sctp_nr_sack_on_offTurn non-renegable SACKs on or off0
sctp_enable_sack_immediatelyEnable sending of the SACK-IMMEDIATELY bit0
sctp_no_csum_on_loopbackEnable the compilation of the checksum on packets sent on loopback1
sctp_peer_chunk_ohAmount to debit peers rwnd per chunk sent256
sctp_max_burst_defaultDefault max burst for SCTP endpoints0
sctp_use_cwnd_based_maxburstUse max burst based on the size of the congestion window1
sctp_hb_maxburstConfirmation Heartbeat max burst4
sctp_max_chunks_on_queueDefault max chunks on queue per asoc512
sctp_min_split_pointMinimum size when splitting a chunk2904
sctp_chunkscaleTunable for Scaling of number of chunks and messages10
sctp_mbuf_threshold_countMaximum number of small mbufs in a chain5
sctp_heartbeat_interval_defaultDeafult time between two Heartbeats30000ms
sctp_pmtu_raise_time_defaultDefault PMTU raise timer600secs
sctp_shutdown_guard_time_defaultDefault shutdown guard timer180secs
sctp_secret_lifetime_defaultDefault secret lifetime3600secs
sctp_add_more_thresholdThreshold when more space should be added to a socket send buffer1452
sctp_nr_outgoing_streams_defaultDefault number of outgoing streams10
sctp_cmt_on_offTurn CMT on or off.0
sctp_cmt_use_dacUse delayed acknowledgment for CMT0
sctp_fr_max_burst_defaultDefault max burst for SCTP endpoints when fast retransmitting4
sctp_auto_asconfEnable SCTP Auto-ASCONF1
sctp_multiple_asconfsEnable SCTP Muliple-ASCONFs0
sctp_asconf_auth_nochkDisable SCTP ASCONF AUTH requirement0
sctp_auth_disableDisable SCTP AUTH function0
sctp_nat_friendlySCTP NAT friendly operation1
sctp_inits_include_nat_friendlyEnable sending of the nat-friendly SCTP option on INITs.0
sctp_udp_tunneling_portSet the SCTP/UDP tunneling port9899
sctp_do_drainDetermines whether SCTP should respond to the drain calls1
sctp_abort_if_one_2_one_hits_limitWhen one-2-one hits qlimit abort0
sctp_strict_data_orderEnforce strict data ordering, abort if control inside data0
sctp_min_residualMinimum residual data chunk in second part of split1452
sctp_max_retran_chunkMaximum times an unlucky chunk can be retransmitted before the association aborts30
sctp_default_cc_moduleDefault congestion control module0
sctp_default_ss_moduleDefault stream scheduling module0
sctp_default_frag_interleaveDefault fragment interleave level1
sctp_mobility_baseEnable SCTP base mobility0
sctp_mobility_fasthandoffEnable SCTP fast handoff0
sctp_L2_abc_variableSCTP ABC max increase per SACK (L)1
sctp_vtag_time_waitVtag time wait time, 0 disables it.60secs
sctp_blackholeEnable SCTP blackholing0
sctp_path_pf_thresholdDefault potentially failed threshold65535
sctp_rttvar_bwShift amount for bw smoothing on rtt calc4
sctp_rttvar_rttShift amount for rtt smoothing on rtt calc5
sctp_rttvar_eqretWhat to return when rtt and bw are unchanged0
sctp_steady_stepHow many the sames it takes to try step down of cwnd20
sctp_use_dccc_ecnEnable for RTCC CC datacenter ECN1
sctp_buffer_splittingEnable send/receive buffer splitting0
sctp_initial_cwndInitial congestion window in MTUs3
sctp_logging_levelLogging level0
sctp_debug_onTurns debug output on or off.0

Examples

See https://github.com/sctplab/usrsctp/tree/master/programs

References

SCTP

R. Stewart: Stream Control Transmission Protocol. RFC 4960, September 2007.

auth

M. Tüxen, R. Stewart, P. Lei, and E. Rescorla: Authenticated Chunks for the Stream Control Transmission Protocol (SCTP). RFC 4895, August 2007.

addip

R. Stewart, Q. Xie, M. Tüxen, S. Maruyama, and M. Kozuka: Stream Control Transmission Protocol (SCTP) Dynamic Address Reconfiguration. RFC 5061, September 2007.

socketAPI

R. Stewart, M. Tüxen, K. Poon, and V. Yasevich: Sockets API Extensions for the Stream Control Transmission Protocol (SCTP). RFC 6458, Dezember 2011.

streamReset

R. Stewart, M. Tüxen, and P. Lei: Stream Control Transmission Protocol (SCTP) Stream Reconfiguration. RFC 6525, February 2012.

udpencaps

M. Tüxen and R. Stewart UDP Encapsulation of Stream Control Transmission Protocol (SCTP) Packets for End-Host to End-Host Communication RFC 6951, May 2013.

sack-imm

M. Tüxen, I. Rüngeler, and R. Stewart: SACK-IMMEDIATELY Extension for the Stream Control Transmission Protocol RFC 7053, November 2013.