Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SCTP(4)		       FreeBSD Kernel Interfaces Manual		       SCTP(4)

     sctp -- Internet Stream Control Transmission Protocol

     options SCTP
     options SCTP_SUPPORT

     #include <sys/types.h>
     #include <sys/socket.h>
     #include <netinet/sctp.h>



     The SCTP protocol provides	reliable, flow-controlled, two-way transmis-
     sion of data.  It is a message oriented protocol and can support the
     SOCK_STREAM and SOCK_SEQPACKET abstractions.  SCTP	uses the standard In-
     ternet address format and,	in addition, provides a	per-host collection of
     "port addresses".	Thus, each address is composed of an Internet address
     specifying	the host and network, with a specific SCTP port	on the host
     identifying the peer entity.

     There are two models of programming in SCTP.  The first uses the
     SOCK_STREAM abstraction.  In this abstraction sockets utilizing the SCTP
     protocol are either "active" or "passive".	 Active	sockets	initiate con-
     nections to passive sockets.  By default, SCTP sockets are	created	ac-
     tive; to create a passive socket, the listen(2) system call must be used
     after binding the socket with the bind(2) or sctp_bindx(3)	system calls.
     Only passive sockets may use the accept(2)	call to	accept incoming	con-
     nections.	Only active sockets may	use the	connect(2) call	to initiate

     The other abstraction SOCK_SEQPACKET provides a "connectionless" mode of
     operation in that the user	may send to an address (using any of the valid
     send calls	that carry a socket address) and an association	will be	setup
     implicitly	by the underlying SCTP transport stack.	 This abstraction is
     the only one capable of sending data on the third leg of the four-way
     handshake.	 A user	must still call	listen(2) to allow the socket to ac-
     cept connections.	Calling	listen(2) however does not restrict the	user
     from still	initiating implicit connections	to other peers.

     The SCTP protocol directly	supports multi-homing.	So when	binding	a
     socket with the "wildcard"	address	INADDR_ANY, the	SCTP stack will	inform
     the peer about all	of the local addresses that are	deemed in scope	of the
     peer.  The	peer will then possibly	have multiple paths to reach the local

     The SCTP transport	protocol is also multi-streamed.  Multi-streaming
     refers to the ability to send sub-ordered flows of	messages.  A user per-
     forms this	by specifying a	specific stream	in one of the extended send
     calls such	as the sctp_send(3) function call.  Sending messages on	dif-
     ferent streams will allow parallel	delivery of data i.e., a message loss
     in	stream 1 will not block	the delivery of	messages sent in stream	2.

     The SCTP transport	protocol also provides a unordered service as well.
     The unordered service allows a message to be sent and delivered with no
     regard to the ordering of any other message.

     The SCTP kernel implementation may	either be compiled into	the kernel, or
     loaded dynamically	as a module.  To support dynamic loading of the	stack,
     the kernel	must be	compiled with options SCTP_SUPPORT.

     The FreeBSD implementation	of SCTP	also supports the following exten-

     sctp partial reliability  This extension allows one to have message be
			       skipped and not delivered based on some user
			       specified parameters.

     sctp dynamic addressing   This extension allows addresses to be added and
			       deleted dynamically from	an existing associa-

     sctp authentication       This extension allows the user to authenticate
			       specific	peer chunks (including data) to	vali-
			       date that the peer who sent the message is in
			       fact the	peer who setup the association.	 A
			       shared key option is also provided for so that
			       two stacks can pre-share	keys.

     packet drop	       Some routers support a special satellite	proto-
			       col that	will report losses due to corruption.
			       This allows retransmissions without subsequent
			       loss in bandwidth utilization.

     stream reset	       This extension allows a user on either side to
			       reset the stream	sequence numbers used by any
			       or all streams.

   Socket Options
     SCTP supports a number of socket options which can	be set with
     setsockopt(2) and tested with getsockopt(2) or sctp_opt_info(3):

	     Under most	circumstances, SCTP sends data when it is presented;
	     when outstanding data has not yet been acknowledged, it gathers
	     small amounts of output to	be sent	in a single packet once	an ac-
	     knowledgement is received.	 For some clients, such	as window sys-
	     tems that send a stream of	mouse events which receive no replies,
	     this packetization	may cause significant delays.  The boolean op-
	     tion SCTP_NODELAY defeats this algorithm.

	     This option returns specific information about an associations
	     "Retransmission Time Out".	 It can	also be	used to	change the de-
	     fault values.

	     This option returns specific information about the	requested as-

	     This option allows	you to get or set the default sending parame-
	     ters when an association is implicitly setup.  It allows you to
	     change such things	as the maximum number of streams allowed in-
	     bound and the number of streams requested of the peer.

	     For the one-to-many model (SOCK_SEQPACKET)	associations are setup
	     implicitly.  This option allows the user to specify a default
	     number of idle seconds to allow the association be	maintained.
	     After the idle timer (where no user message have been sent	or
	     have been received	from the peer) the association will be grace-
	     fully closed.  The	default	for this value is 0, or	unlimited
	     (i.e., no automatic close).

	     The dynamic address extension allows a peer to also request a
	     particular	address	of its be made into the	primary	address.  This
	     option allows the caller to make such a request to	a peer.	 Note
	     that if the peer does not also support the	dynamic	address	exten-
	     sion, this	call will fail.	 Note the caller must provide a	valid
	     local address that	the peer has been told about during associa-
	     tion setup	or dynamically.

	     This option allows	the setting of the primary address that	the
	     caller wishes to send to.	The caller provides the	address	of a
	     peer that is to be	made primary.

	     The dynamic address extension also	allows a user to pass a	32 bit
	     opaque value upon association setup.  This	option allows a	user
	     to	set or get this	value.

	     By	default	SCTP will fragment user	messages into multiple pieces
	     that will fit on the network and then later, upon reception, re-
	     assemble the pieces into a	single user message.  If this option
	     is	enabled	instead, any send that exceeds the path	maximum	trans-
	     fer unit (P-MTU) will fail	and the	message	will NOT be sent.

	     This option will allow a user to set or get specific peer address

	     When a user does not use one of the extended send calls (e.g.,
	     sctp_sendmsg(3)) a	set of default values apply to each send.
	     These values include things like the stream number	to send	to as
	     well as the per-protocol id.  This	option lets a caller both get
	     and set these values.  If the user	changes	these default values,
	     then these	new values will	be used	as the default whenever	no in-
	     formation is provided by the sender (i.e.,	the non-extended API
	     is	used).

	     SCTP has non-data events that it can communicate to its applica-
	     tion.  By default these are all disabled since they arrive	in the
	     data path with a special flag MSG_NOTIFICATION set	upon the re-
	     ceived message.  This option lets a caller	both get what events
	     are current being received	as well	as set different events	that
	     they may be interested in receiving.

	     SCTP supports both	IPV4 and IPV6.	An association may span	both
	     IPV4 and IPV6 addresses since SCTP	is multi-homed.	 By default,
	     when opening an IPV6 socket, when data arrives on the socket from
	     a peer's V4 address the V4	address	 will be presented with	an ad-
	     dress family of AF_INET.  If this is undesirable, then this op-
	     tion can be enabled which will then convert all V4	addresses into
	     mapped V6 representations.

	     By	default	SCTP chooses its message fragmentation point based
	     upon the smallest P-MTU of	the peer.  This	option lets the	caller
	     set it to a smaller value.	 Note that while the user can change
	     this value, if the	P-MTU is smaller than the value	set by the
	     user, then	the P-MTU value	will override any user setting.

	     This option lets the user both set	and get	the delayed ack	time
	     (in milliseconds) that SCTP is using.  The	default	is 200 mil-

	     SCTP at times may need to start delivery of a very	large message
	     before the	entire message has arrived.  By	default	SCTP waits un-
	     til the incoming message is larger	than one fourth	of the receive
	     buffer.  This option allows the stacks value to be	overridden
	     with a smaller value.

	     SCTP at times will	start partial delivery (as mentioned above).
	     In	the normal case	successive reads will continue to return the
	     rest of the message, blocking if needed, until all	of that	mes-
	     sage is read.  However this means other messages may have arrived
	     and be ready for delivery and be blocked behind the message being
	     partially delivered.  If this option is enabled, when a partial
	     delivery message has no more data to be received, then a subse-
	     quent read	may return a different message that is ready for de-
	     livery.  By default this option is	off since the user must	be us-
	     ing the extended API's to be able to tell the difference between
	     messages (via the stream and stream sequence number).

	     By	default	only the dynamic addressing chunks are authenticated.
	     This option lets a	user request an	additional chunk be authenti-
	     cated as well.  Note that successive calls	to this	option will
	     work and continue to add more chunks that require authentication.
	     Note that this option only	effects	future associations and	not
	     existing ones.

	     This option allows	a user to specify a shared key that can	be
	     later used	to authenticate	a peer.

	     This option will let you get or set the list of HMAC algorithms
	     used to authenticate peers.  Note that the	HMAC values are	in
	     priority order where the first HMAC identifier is the most	pre-
	     ferred and	the last is the	least preferred.

	     This option allows	you to make a key active for the generation of
	     authentication information.  Note that the	peer must have the
	     same key or else the data will be discarded.

	     This option allows	you to delete an old key.

	     The sockets api document allows an	extended send/receive informa-
	     tion structure to be used.	 The extended structure	includes addi-
	     tional fields related to the next message to be received (after
	     the current receive completes) if such information	is known.  By
	     default the system	will not pass this information.	 This option
	     allows the	user to	request	this information.

	     By	default	when bound to all address and the system administrator
	     has enables automatic dynamic addresses, the SCTP stack will au-
	     tomatically generate address changes into add and delete requests
	     to	any peers by setting this option to true.  This	option allows
	     an	endpoint to disable that behavior.

	     By	default	SCTP implements	micro-burst control so that as the
	     congestion	window opens up	no large burst of packets can be gen-
	     erated.  The default burst	limit is four.	This option lets the
	     user change this value.

	     Many sctp extended	calls have a context field.  The context field
	     is	a 32 bit opaque	value that will	be returned in send failures.
	     This option lets the caller set the default context value to use
	     when none is provided by the user.

	     By	default, a single send is a complete message.  SCTP generates
	     an	implied	record boundary.  If this option is enabled, then all
	     sends are part of the same	message	until the user indicates an
	     end of record with	the special flag SCTP_EOR passed in the
	     sctp_sndrcvinfo flags field.  This	effectively makes all sends
	     part of the same message until the	user specifies differently.
	     This means	that a caller must NOT change the stream number	until
	     after the SCTP_EOR	is passed to SCTP else an error	will be	re-

	     This option is a read-only	option that returns various status in-
	     formation about the specified association.

	     This read-only option returns information about a peer address.

	     This read-only option returns a list of the chunks	the peer re-
	     quires to be authenticated.

	     This read-only option returns a list of the locally required
	     chunks that must be authenticated.

	     This socket option	is used	to cause a stream sequence number or
	     all stream	sequence numbers to be reset.  Note that the peer SCTP
	     endpoint must also	support	the stream reset extension as well.

   MIB Variables
     The SCTP protocol implements a number of variables	in the net.inet.sctp
     branch of the sysctl(3) MIB.

     Congestion	Control

	     Default congestion	control	module.	 Default value is 0.  The min-
	     imum is 0,	and the	maximum	is 3.  A value of 0 enables the	de-
	     fault congestion control algorithm.  A value of 1 enables the
	     High Speed	congestion control algorithm.  A value of 2 enables
	     the HTCP congestion control algorithm.  A value of	3 enables the
	     data center congestion control (DCCC) algorithm.

	     Defines the initial congestion window size	in MTUs.

	     Use congestion control instead of 'blind' logic to	limit maximum
	     burst when	sending.  Default value	is 1. May be set to 0 or 1.

	     Enable Explicit Congestion	Notification (ECN).  Default value is
	     1.	May be set to 0	or 1.

	     Number of identical bandwidth measurements	DCCC takes to try step
	     down the congestion window.  Default value	is 20.	The minimum is
	     0,	and the	maximum	is 65535.

	     Whether DCCC reduces the congestion window	size when round-trip
	     time and bandwidth	remain unchanged.  Default value is 0.	May be
	     set to 0 or 1.

	     Shift amount DCCC uses for	bandwidth smoothing on round-trip-time
	     calculation.  Default value is 4.	The minimum is 0, and the max-
	     imum is 32.

	     Shift amount DCCC uses for	round-trip-time	smoothing on round-
	     trip-time calculation.  Default value is 5.  The minimum is 0,
	     and the maximum is	32.

	     Enable ECN	when using DCCC.  Default value	is 1.  May be set to 0
	     or	1.


	     Get the ucred of a	SCTP connection.

	     List of active SCTP associations.

     stats   SCTP statistics (struct sctp_stat).

	     Diagnostic	information error cause	code.

	     Enable SCTP blackholing.  See blackhole(4)	for more details.

	     Maximum message size (in bytes) that can be transmitted with
	     SCTP_SENDALL flags	set.

	     Enable send/receive buffer	splitting.

	     Vtag wait time in seconds,	0 to disable.

	     Enable sending of the NAT-friendly	SCTP option on INITs.

	     Enable sending of the SACK-IMMEDIATELY bit.

	     Set the SCTP/UDP tunneling	port.

	     Enable SCTP fast handoff.

	     Enable SCTP base mobility

	     Default fragment interleave level.

	     Default stream scheduling module.

	     Ltrace/KTR	trace logging level.

	     Number of retransmissions of a DATA chunk before an association
	     is	aborted.

	     Minimum residual data chunk in second part	of split.

	     Enforce strict data ordering, abort if control inside data.

	     Abort when	one-to-one hits	qlimit.

	     Confirmation heartbeat max	burst.

	     Flush chunks in receive queues with TSN higher than the cumula-
	     tive TSN if the system is low on mbufs.

	     Default max number	of small mbufs on a chain.

	     SCTP ABC max increase per SACK (L).

	     SCTP NAT friendly operation.

	     CMT DAC on/off flag.

	     CMT settings.

	     Default number of outgoing	streams.

	     Default number of incoming	streams.

	     When space-wise is	it worthwhile to try to	add more to a socket
	     send buffer.

	     Default potentially failed	threshold.

	     Default maximum of	retransmissions	per path.

	     Default maximum number of retransmissions per association.

	     Default maximum number of retransmissions for INIT	chunks.

	     Default cookie lifetime in	seconds.

	     Default maximum retransmission timeout during association setup
	     in	ms.

	     Default initial retransmission timeout in ms.

	     Default minimum retransmission timeout in ms.

	     Default maximum retransmission timeout in ms.

	     Default secret lifetime in	seconds.

	     Shutdown guard timer in seconds (0	means 5	times RTO.Max).

	     Default PMTU raise	timer in seconds.

	     Default heartbeat interval	in ms.

	     Max number	of cached resources in an association.

	     Max number	of cached resources in the system.

	     Default SACK frequency.

	     Default delayed SACK timer	in ms.

	     Tunable for scaling of number of chunks and messages.

	     Minimum size when splitting a chunk.

	     Tunable for PCB hash table	sizes.

	     Tunable for TCB hash table	sizes.

	     Default max chunks	on queue per association.

	     Default max burst for SCTP	endpoints when fast retransmitting.

	     Default max burst for SCTP	endpoints.

	     Amount to debit peers rwnd	per chunk sent.

	     Enable SCTP Strict	SACK checking.

	     Enable SCTP PKTDROP.

	     Enable SCTP NR-SACK.

	     Enable SCTP RE-CONFIG.

	     Enable SCTP ASCONF.

	     Enable SCTP AUTH.

	     Enable PR-SCTP.

	     Enable SCTP Auto-ASCONF.

	     Maximum incoming SCTP buffer size.

	     Maximum outgoing SCTP buffer size.

     accept(2),	bind(2), connect(2), listen(2),	sctp_bindx(3),
     sctp_connectx(3), sctp_opt_info(3), sctp_recvmsg(3), sctp_sendmsg(3),

     The sctp kernel module cannot be unloaded.

FreeBSD	13.0			 July 9, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help