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

FreeBSD Manual Pages

  
 
  

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

NAME
     sctp -- Internet Stream Control Transmission Protocol

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

     int
     socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP);

     int
     socket(AF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);

DESCRIPTION
     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
     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 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
     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.

   Extensions
     The FreeBSD implementation	of SCTP	also supports the following exten-
     sions:

     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-
			       tion.

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

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

     SCTP_ASSOCINFO
	     This option returns specific information about the	requested as-
	     sociation.

     SCTP_INITMSG
	     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.

     SCTP_AUTOCLOSE
	     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).

     SCTP_SET_PEER_PRIMARY_ADDR
	     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.

     SCTP_PRIMARY_ADDR
	     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.

     SCTP_ADAPTATION_LAYER
	     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.

     SCTP_DISABLE_FRAGMENTS
	     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.

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

     SCTP_DEFAULT_SEND_PARAM
	     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_EVENTS
	     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_I_WANT_MAPPED_V4_ADDR
	     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.

     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.

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

     SCTP_PARTIAL_DELIVERY_POINT
	     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_FRAGMENT_INTERLEAVE
	     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).

     SCTP_AUTH_CHUNK
	     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.

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

     SCTP_HMAC_IDENT
	     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.

     SCTP_AUTH_ACTIVE_KEY
	     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.

     SCTP_AUTH_DELETE_KEY
	     This option allows	you to delete an old key.

     SCTP_USE_EXT_RECVINFO
	     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.

     SCTP_AUTO_ASCONF
	     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.

     SCTP_MAXBURST
	     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.

     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.

     SCTP_EXPLICIT_EOR
	     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-
	     turned.

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

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

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

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

     SCTP_RESET_STREAMS
	     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_cc_module
	     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.

     initial_cwnd
	     Defines the initial congestion window size	in MTUs.

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

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

     rttvar_steady_step
	     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.

     rttvar_eqret
	     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.

     rttvar_bw
	     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.

     rttvar_rtt
	     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.

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

     Misc

     getcred
	     Get the ucred of a	SCTP connection.

     assoclist
	     List of active SCTP associations.

     stats   SCTP statistics (struct sctp_stat).

     diag_info_code
	     Diagnostic	information error cause	code.

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

     buffer_splitting
	     Enable send/receive buffer	splitting.

     vtag_time_wait
	     Vtag wait time in seconds,	0 to disable.

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

     enable_sack_immediately
	     Enable sending of the SACK-IMMEDIATELY bit.

     udp_tunneling_port
	     Set the SCTP/UDP tunneling	port.

     mobility_fasthandoff
	     Enable SCTP fast handoff.

     mobility_base
	     Enable SCTP base mobility

     default_frag_interleave
	     Default fragment interleave level.

     default_ss_module
	     Default stream scheduling module.

     log_level
	     Ltrace/KTR	trace logging level.

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

     min_residual
	     Minimum residual data chunk in second part	of split.

     strict_data_order
	     Enforce strict data ordering, abort if control inside data.

     abort_at_limit
	     Abort when	one-to-one hits	qlimit.

     hb_max_burst
	     Confirmation heartbeat max	burst.

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

     max_chained_mbufs
	     Default max number	of small mbufs on a chain.

     abc_l_var
	     SCTP ABC max increase per SACK (L).

     nat_friendly
	     SCTP NAT friendly operation.

     cmt_use_dac
	     CMT DAC on/off flag.

     cmt_on_off
	     CMT settings.

     outgoing_streams
	     Default number of outgoing	streams.

     incoming_streams
	     Default number of incoming	streams.

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

     path_pf_threshold
	     Default potentially failed	threshold.

     path_rtx_max
	     Default maximum of	retransmissions	per path.

     assoc_rtx_max
	     Default maximum number of retransmissions per association.

     init_rtx_max
	     Default maximum number of retransmissions for INIT	chunks.

     valid_cookie_life
	     Default cookie lifetime in	seconds.

     init_rto_max
	     Default maximum retransmission timeout during association setup
	     in	ms.

     rto_initial
	     Default initial retransmission timeout in ms.

     rto_min
	     Default minimum retransmission timeout in ms.

     rto_max
	     Default maximum retransmission timeout in ms.

     secret_lifetime
	     Default secret lifetime in	seconds.

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

     pmtu_raise_time
	     Default PMTU raise	timer in seconds.

     heartbeat_interval
	     Default heartbeat interval	in ms.

     asoc_resource
	     Max number	of cached resources in an association.

     sys_resource
	     Max number	of cached resources in the system.

     sack_freq
	     Default SACK frequency.

     delayed_sack_time
	     Default delayed SACK timer	in ms.

     chunkscale
	     Tunable for scaling of number of chunks and messages.

     min_split_point
	     Minimum size when splitting a chunk.

     pcbhashsize
	     Tunable for PCB hash table	sizes.

     tcbhashsize
	     Tunable for TCB hash table	sizes.

     maxchunks
	     Default max chunks	on queue per association.

     fr_maxburst
	     Default max burst for SCTP	endpoints when fast retransmitting.

     maxburst
	     Default max burst for SCTP	endpoints.

     peer_chkoh
	     Amount to debit peers rwnd	per chunk sent.

     strict_sacks
	     Enable SCTP Strict	SACK checking.

     pktdrop_enable
	     Enable SCTP PKTDROP.

     nrsack_enable
	     Enable SCTP NR-SACK.

     reconfig_enable
	     Enable SCTP RE-CONFIG.

     asconf_enable
	     Enable SCTP ASCONF.

     auth_enable
	     Enable SCTP AUTH.

     pr_enable
	     Enable PR-SCTP.

     auto_asconf
	     Enable SCTP Auto-ASCONF.

     recvspace
	     Maximum incoming SCTP buffer size.

     sendspace
	     Maximum outgoing SCTP buffer size.

SEE ALSO
     accept(2),	bind(2), connect(2), listen(2),	sctp_bindx(3),
     sctp_connectx(3), sctp_opt_info(3), sctp_recvmsg(3), sctp_sendmsg(3),
     blackhole(4)

BSD			       October 10, 2018				   BSD

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sctp&sektion=4&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help