usrsctp Documentation

Because many NAT boxes cannot process raw SCTP packets, it is often necessary to encapsulate SCTP packets within UDP datagrams.

Server Configuration

When running the discard_server, specify the local and remote encapsulation ports:

discard_server [local_encaps_port remote_encaps_port]

Example: ./discard_server 11111 22222

Client Configuration

When running the client, the encapsulation ports must match the server's configuration (the server's local_encaps_port is the client's remote_encaps_port, and vice versa). The client requires the remote address and port first:

client remote_addr remote_port [local_port local_encaps_port remote_encaps_port]

Example: ./client 127.0.0.1 9 0 22222 11111 (where 22222 is the server's local port and 11111 is the server's remote port).

# Server
$ ./discard_server 11111 22222

# Client
$ ./client 127.0.0.1 9 0 22222 11111

Depending on your operating system, use the following methods to build the libusrsctp library and the example programs located in the programs directory.

Unix-like Operating Systems

Run the following commands in the usrsctp directory:

1. ./bootstrap
2. ./configure
3. make

The library libusrsctp.la will be built in the usrsctplib subdirectory. To install the library to /usr/local/lib and headers to /usr/include, use sudo make install.

Windows

Use a compiler like Microsoft Visual Studio and run the following command in the usrsctp directory:

nmake -f Makefile.nmake

CMake

Create a build directory outside the usrsctp directory and run:

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

Note: By default, CMake generates a DEBUG build with verbose output.

# Unix-like
$ ./bootstrap
$ ./configure
$ make

# Windows
$ nmake -f Makefile.nmake

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

usrsctp provides sysctl-like functions to tune internal parameters. These functions follow the pattern usrsctp_sysctl_set_##(value) to set a value and usrsctp_sysctl_get_##() to retrieve it, where ## is the variable name.

Memory Management

• usrsctp_sysctl_set_sctp_sendspace(value): Sets the available send buffer (default: 262,144 bytes). Range: 0 to 2^32 - 1.
• usrsctp_sysctl_set_sctp_recvspace(value): Sets the available receive buffer (default: 262,144 bytes). Range: 0 to 2^32 - 1.
• usrsctp_sysctl_set_sctp_hashtblsize(value): Tunes the TCB hash table size (default: 1,024 bytes). Range: 1 to 2^32 - 1.
• usrsctp_sysctl_set_sctp_pcbtblsize(value): Tunes the PCB hash table size (default: 256 bytes). Range: 1 to 2^32 - 1.
• usrsctp_sysctl_set_sctp_system_free_resc_limit(value): Maximum number of cached system resources (default: 1000). Range: 0 to 2^32 - 1.
• usrsctp_sysctl_set_sctp_asoc_free_resc_limit(value): Maximum number of cached resources per association (default: 10). Range: 0 to 2^32 - 1.
• usrsctp_sysctl_set_sctp_mbuf_threshold_count(value): Max number of small mbufs in a chain before using an mbuf cluster (default: 5).
• usrsctp_sysctl_set_sctp_add_more_threshold(value): Threshold below which more space is added to a socket send buffer (default: 1452 bytes).

Retransmission Timeout (RTO) Configuration

Values are in milliseconds (ms). Range: 0 to 2^32 - 1.

• usrsctp_sysctl_set_sctp_rto_max_default(value): Default maximum RTO (default: 60,000ms).
• usrsctp_sysctl_set_sctp_rto_min_default(value): Default minimum RTO (default: 1,000ms).
• usrsctp_sysctl_set_sctp_rto_initial_default(value): Default initial RTO (default: 3,000ms).
• usrsctp_sysctl_set_sctp_init_rto_max_default(value): Default maximum RTO for an INIT chunk (default: 60,000ms).

Timers

• usrsctp_sysctl_set_sctp_valid_cookie_life_default(value): Cookie lifetime (default: 60,000ms).
• usrsctp_sysctl_set_sctp_heartbeat_interval_default(value): Interval between heartbeats (default: 30,000ms).
• usrsctp_sysctl_set_sctp_shutdown_guard_time_default(value): Time before aborting a SHUTDOWN if no SHUTDOWN-ACK is received (default: 180s).
• usrsctp_sysctl_set_sctp_pmtu_raise_time_default(value): Path MTU discovery interval (default: 600s).
• usrsctp_sysctl_set_sctp_secret_lifetime_default(value): Server secret lifetime (default: 3600s).
• usrsctp_sysctl_set_sctp_vtag_time_wait(value): Vtag time wait (default: 60s; 0 disables it).

Use usrsctp_sendv() to send data over an SCTP socket. This function follows RFC 6458 and allows sending data with optional additional information (like struct sctp_sndinfo or struct sctp_prinfo).

Parameters:

• so: The socket to send data on.
• data: Pointer to the data buffer.
• len: Length of the data.
• addrs: Destination address. Supports at most one address. For connected sockets, this can be NULL.
• addrcnt: Number of addresses. Set to 0 if addrs is NULL, otherwise 1.
• info: Pointer to additional message information (e.g., struct sctp_sndinfo, struct sctp_prinfo, or struct sctp_sendv_spa).
• infolen: Length of the info buffer.
• infotype: Identifies the type of info. Supported values:
  • SCTP_SENDV_NOINFO
  • SCTP_SENDV_SNDINFO
  • SCTP_SENDV_PRINFO
  • SCTP_SENDV_SPA
• flags: Flags as described in RFC 6458.

Returns: The number of bytes sent, or -1 on error (sets errno).

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)

Use usrsctp_recvv() to receive data from an SCTP socket. This function follows RFC 6458 and returns message attributes via the info parameter.

Parameters:

• so: The socket to receive data on.
• dbuf: Buffer to store received data.
• len: Length of the buffer.
• from: Pointer to be filled with the sender's address.
• fromlen: In/out parameter for the sender address length.
• info: Pointer to a buffer for message attributes. The structure type is determined by *infotype.
• infolen: In/out parameter for the info buffer size.
• infotype: In/out parameter. On return, it is set to the type of the info buffer. Current values:
  • SCTP_RECVV_NOINFO
  • SCTP_RECVV_RCVINFO
  • SCTP_RECVV_NXTINFO
  • SCTP_RECVV_RN
• msg_flags: In/out parameter. On return, it contains message flags (e.g., MSG_NOTIFICATION). You can pass receive options like MSG_EOR into this value.

Returns: The number of bytes received, or -1 on error (sets errno).

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)