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

     #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
     Internet 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
     connections to passive sockets.  By default, SCTP sockets are created
     active; 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 incom-
     ing connections.  Only active sockets may use the connect(2) call to ini-
     tiate connections.

     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 abstrac-
     tion 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	accept 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 host.

     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 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):

     SCTP_NODELAY  Under most circumstances, SCTP sends	data when it is	pre-
		   sented; when	outstanding data has not yet been acknowl-
		   edged, it gathers small amounts of output to	be sent	in a
		   single packet once an acknowledgement is received.  For
		   some	clients, such as window	systems	that send a stream of
		   mouse events	which receive no replies, this packetization
		   may cause significant delays.  The boolean option
		   SCTP_NODELAY	defeats	this algorithm.

     SCTP_RTOINFO  This	option returns specific	information about an associa-
		   tions ``Retransmission Time Out''.  It can also be used to
		   change the default values.

		   This	option returns specific	information about the
		   requested association.

     SCTP_INITMSG  This	option allows you to get or set	the default sending
		   parameters when an association is implicitly	setup.	It
		   allows you to change	such things as the maximum number of
		   streams allowed inbound 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 gracefully 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 extension, this call will fail.
		   Note	the caller must	provide	a valid	local address that the
		   peer	has been told about during association setup or	dynam-

		   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, reassemble the pieces into a single user mes-
		   sage.  If this option is enabled instead, any send that
		   exceeds the path maximum transfer 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 parameters.

		   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 information is pro-
		   vided by the	sender (i.e., the non-extended API is used).

     SCTP_EVENTS   SCTP	has non-data events that it can	communicate to its
		   application.	 By default these are all disabled since they
		   arrive in the data path with	a special flag
		   MSG_NOTIFICATION set	upon the received 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 address family of AF_INET.	 If this is
		   undesirable,	then this option can be	enabled	which will
		   then	convert	all V4 addresses into mapped V6	representa-

     SCTP_MAXSEG   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 milliseconds.

		   SCTP	at times may need to start delivery of a very large
		   message before the entire message has arrived.  By default
		   SCTP	waits until 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 message is	read.  However this means
		   other messages may have arrived and be ready	for delivery
		   and be blocked behind the message being partially deliv-
		   ered.  If this option is enabled, when a partial delivery
		   message has no more data to be received, then a subsequent
		   read	may return a different message that is ready for
		   delivery.  By default this option is	off since the user
		   must	be using 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 authenti-
		   cated.  This	option lets a user request an additional chunk
		   be authenticated 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	algo-
		   rithms used to authenticate peers.  Note that the HMAC val-
		   ues are in priority order where the first HMAC identifier
		   is the most preferred and the last is the least preferred.

		   This	option allows you to make a key	active for the genera-
		   tion	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
		   information structure to be used.  The extended structure
		   includes additional 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 admin-
		   istrator has	enables	automatic dynamic addresses, the SCTP
		   stack will automatically 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

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

     SCTP_CONTEXT  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 gen-
		   erates 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 returned.

     SCTP_STATUS   This	option is a read-only option that returns various sta-
		   tus information about the specified association.

		   This	read-only option returns information about a peer

		   This	read-only option returns a list	of the chunks the peer
		   requires 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 num-
		   ber 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
	     default 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.

	     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),

FreeBSD	Ports 11.2	       October 10, 2018		    FreeBSD Ports 11.2


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

home | help