1 .\" Copyright (c) 2006, Randall Stewart.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
11 .\" 3. Neither the name of the University nor the names of its contributors
12 .\" may be used to endorse or promote products derived from this software
13 .\" without specific prior written permission.
15 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .Nd Internet Stream Control Transmission Protocol
40 .Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP
42 .Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP
46 protocol provides reliable, flow-controlled, two-way
48 It is a message oriented protocol and can
56 Internet address format and, in addition, provides a per-host
58 .Dq "port addresses" .
59 Thus, each address is composed of an Internet address specifying
60 the host and network, with a specific
62 port on the host identifying the peer entity.
64 There are two models of programming in SCTP.
68 In this abstraction sockets utilizing the
74 Active sockets initiate connections to passive
78 sockets are created active; to create a
81 system call must be used after binding the socket with the
86 Only passive sockets may use the
88 call to accept incoming connections.
89 Only active sockets may use the
91 call to initiate connections.
97 mode of operation in that the user may send to an address
98 (using any of the valid send calls that carry a
99 socket address) and an association will be setup
100 implicitly by the underlying
103 This abstraction is the only one capable of sending data on the
104 third leg of the four-way handshake.
105 A user must still call
107 to allow the socket to accept connections.
110 however does not restrict the user from still initiating
111 implicit connections to other peers.
115 protocol directly supports multi-homing.
116 So when binding a socket with the
122 stack will inform the peer about all of the local addresses
123 that are deemed in scope of the peer.
124 The peer will then possibly have multiple paths to reach the local host.
128 transport protocol is also multi-streamed.
129 Multi-streaming refers to the ability to send sub-ordered flows of
131 A user performs this by specifying a specific stream in one of the
132 extended send calls such as the
135 Sending messages on different streams will allow parallel delivery
136 of data i.e., a message loss in stream 1 will not block the delivery
137 of messages sent in stream 2.
141 transport protocol also provides a unordered service as well.
142 The unordered service allows a message to be sent and delivered
143 with no regard to the ordering of any other message.
145 The FreeBSD implementation of
147 also supports the following extensions:
148 .Bl -tag -width "sctp partial reliability"
149 .It "sctp partial reliability"
150 This extension allows one to have message be skipped and
151 not delivered based on some user specified parameters.
152 .It "sctp dynamic addressing"
153 This extension allows addresses to be added and deleted
154 dynamically from an existing association.
155 .It "sctp authentication"
156 This extension allows the user to authenticate specific
157 peer chunks (including data) to validate that the peer
158 who sent the message is in fact the peer who setup the
160 A shared key option is also provided for
161 so that two stacks can pre-share keys.
163 Some routers support a special satellite protocol that
164 will report losses due to corruption.
165 This allows retransmissions without subsequent loss in bandwidth
168 This extension allows a user on either side to reset the
169 stream sequence numbers used by any or all streams.
173 supports a number of socket options which can be set with
178 .Xr sctp_opt_info 3 :
181 Under most circumstances,
183 sends data when it is presented; when outstanding data has not
184 yet been acknowledged, it gathers small amounts of output to be
185 sent in a single packet once an acknowledgement is received.
186 For some clients, such as window systems that send a stream of
187 mouse events which receive no replies, this packetization may
188 cause significant delays.
191 defeats this algorithm.
193 This option returns specific information about an associations
194 .Dq "Retransmission Time Out" .
195 It can also be used to change the default values.
196 .It Dv SCTP_ASSOCINFO
197 This option returns specific information about the requested
200 This option allows you to get or set the default sending
201 parameters when an association is implicitly setup.
202 It allows you to change such things as the maximum number of
203 streams allowed inbound and the number of streams requested
205 .It Dv SCTP_AUTOCLOSE
206 For the one-to-many model
207 .Dv ( SOCK_SEQPACKET )
208 associations are setup implicitly.
209 This option allows the user to specify a default number of idle
210 seconds to allow the association be maintained.
211 After the idle timer (where no user message have been sent or have
212 been received from the peer) the association will be gracefully
214 The default for this value is 0, or unlimited (i.e., no automatic
216 .It Dv SCTP_SET_PEER_PRIMARY_ADDR
217 The dynamic address extension allows a peer to also request a
218 particular address of its be made into the primary address.
219 This option allows the caller to make such a request to a peer.
220 Note that if the peer does not also support the dynamic address
221 extension, this call will fail.
222 Note the caller must provide a valid local address that the peer has
223 been told about during association setup or dynamically.
224 .It Dv SCTP_PRIMARY_ADDR
225 This option allows the setting of the primary address
226 that the caller wishes to send to.
227 The caller provides the address of a peer that is to be made primary.
228 .It Dv SCTP_ADAPTATION_LAYER
229 The dynamic address extension also allows a user to
230 pass a 32 bit opaque value upon association setup.
231 This option allows a user to set or get this value.
232 .It Dv SCTP_DISABLE_FRAGMENTS
235 will fragment user messages into multiple pieces that
236 will fit on the network and then later, upon reception, reassemble
237 the pieces into a single user message.
238 If this option is enabled instead, any send that exceeds the path
239 maximum transfer unit (P-MTU) will fail and the message will NOT be
241 .It Dv SCTP_PEER_ADDR_PARAMS
242 This option will allow a user to set or get specific
243 peer address parameters.
244 .It Dv SCTP_DEFAULT_SEND_PARAM
245 When a user does not use one of the extended send
248 a set of default values apply to each send.
249 These values include things like the stream number to send
250 to as well as the per-protocol id.
251 This option lets a caller both get and set these values.
252 If the user changes these default values, then these new values will
253 be used as the default whenever no information is provided by the
254 sender (i.e., the non-extended API is used).
257 has non-data events that it can communicate
259 By default these are all disabled since they arrive in the data path
262 set upon the received message.
263 This option lets a caller
264 both get what events are current being received
265 as well as set different events that they may be interested
267 .It Dv SCTP_I_WANT_MAPPED_V4_ADDR
269 supports both IPV4 and IPV6.
270 An association may span both IPV4 and IPV6 addresses since
273 By default, when opening an IPV6 socket, when
274 data arrives on the socket from a peer's
275 V4 address the V4 address will be presented with an address family
277 If this is undesirable, then this option
278 can be enabled which will then convert all V4 addresses
279 into mapped V6 representations.
283 chooses its message fragmentation point
284 based upon the smallest P-MTU of the peer.
285 This option lets the caller set it to a smaller value.
286 Note that while the user can change this value, if the P-MTU
287 is smaller than the value set by the user, then the P-MTU
288 value will override any user setting.
289 .It Dv SCTP_DELAYED_ACK_TIME
290 This option lets the user both set and get the
291 delayed ack time (in milliseconds) that
294 The default is 200 milliseconds.
295 .It Dv SCTP_PARTIAL_DELIVERY_POINT
297 at times may need to start delivery of a
298 very large message before the entire message has
300 By default SCTP waits until the incoming
301 message is larger than one fourth of the receive
303 This option allows the stacks value
304 to be overridden with a smaller value.
305 .It Dv SCTP_FRAGMENT_INTERLEAVE
307 at times will start partial delivery (as mentioned above).
308 In the normal case successive reads will continue to return
309 the rest of the message, blocking if needed, until all of
310 that message is read.
311 However this means other messages may have arrived and be ready
312 for delivery and be blocked behind the message being partially
314 If this option is enabled, when a partial delivery
315 message has no more data to be received, then a subsequent
316 read may return a different message that is ready for delivery.
317 By default this option is off since the user must be using the
318 extended API's to be able to tell the difference between
319 messages (via the stream and stream sequence number).
320 .It Dv SCTP_AUTH_CHUNK
321 By default only the dynamic addressing chunks are
323 This option lets a user request an
324 additional chunk be authenticated as well.
325 Note that successive calls to this option will work and continue
326 to add more chunks that require authentication.
327 Note that this option only effects future associations and
330 This option allows a user to specify a shared
331 key that can be later used to authenticate
333 .It Dv SCTP_HMAC_IDENT
334 This option will let you get or set the list of
335 HMAC algorithms used to authenticate peers.
336 Note that the HMAC values are in priority order where
337 the first HMAC identifier is the most preferred
338 and the last is the least preferred.
339 .It Dv SCTP_AUTH_ACTIVE_KEY
340 This option allows you to make a key active for
341 the generation of authentication information.
342 Note that the peer must have the same key or else the
343 data will be discarded.
344 .It Dv SCTP_AUTH_DELETE_KEY
345 This option allows you to delete an old key.
346 .It Dv SCTP_USE_EXT_RECVINFO
347 The sockets api document allows an extended
348 send/receive information structure to be used.
349 The extended structure includes additional fields
350 related to the next message to be received (after the
351 current receive completes) if such information is known.
352 By default the system will not pass this information.
353 This option allows the user to request this information.
354 .It Dv SCTP_AUTO_ASCONF
355 By default when bound to all address and the system administrator has
356 enables automatic dynamic addresses, the
358 stack will automatically generate address changes into add and
359 delete requests to any peers by setting this option to
361 This option allows an endpoint to disable that behavior.
365 implements micro-burst control so that as the congestion window
366 opens up no large burst of packets can be generated.
367 The default burst limit is four.
368 This option lets the user change this value.
370 Many sctp extended calls have a context field.
371 The context field is a 32 bit opaque value that will be returned in
373 This option lets the caller set the default
374 context value to use when none is provided by the user.
375 .It Dv SCTP_EXPLICIT_EOR
376 By default, a single send is a complete message.
378 generates an implied record boundary.
379 If this option is enabled, then all sends are part of the same message
380 until the user indicates an end of record with the
383 passed in the sctp_sndrcvinfo flags field.
384 This effectively makes all sends part of the same message
385 until the user specifies differently.
386 This means that a caller must NOT change the stream number until
391 else an error will be returned.
393 This option is a read-only option that returns
394 various status information about the specified association.
395 .It Dv SCTP_GET_PEER_ADDR_INFO
396 This read-only option returns information about a peer
398 .It Dv SCTP_PEER_AUTH_CHUNKS
399 This read-only option returns a list of the chunks
400 the peer requires to be authenticated.
401 .It Dv SCTP_LOCAL_AUTH_CHUNKS
402 This read-only option returns a list of the locally
403 required chunks that must be authenticated.
404 .It Dv SCTP_RESET_STREAMS
405 This socket option is used to cause a stream sequence
406 number or all stream sequence numbers to be reset.
409 endpoint must also support the stream reset extension
415 protocol implements a number of variables in the
421 .It Sy Congestion Control
422 .Bl -tag -width indent
423 .It Va default_cc_module
424 Default congestion control module.
426 The minimum is 0, and the maximum is 3.
427 A value of 0 enables the default congestion control algorithm.
428 A value of 1 enables the High Speed congestion control algorithm.
429 A value of 2 enables the HTCP congestion control algorithm.
430 A value of 3 enables the data center congestion control (DCCC) algorithm.
432 Defines the initial congestion window size in MTUs.
434 Use congestion control instead of 'blind' logic to limit maximum burst when sending.
435 Default value is 1. May be set to 0 or 1.
437 Enable Explicit Congestion Notification (ECN).
438 Default value is 1. May be set to 0 or 1.
439 .It Va rttvar_steady_step
440 Number of identical bandwidth measurements DCCC takes to try step down the congestion window.
442 The minimum is 0, and the maximum is 65535.
444 Whether DCCC reduces the congestion window size when round-trip time and bandwidth remain unchanged.
446 May be set to 0 or 1.
448 Shift amount DCCC uses for bandwidth smoothing on round-trip-time calculation.
450 The minimum is 0, and the maximum is 32.
452 Shift amount DCCC uses for round-trip-time smoothing on round-trip-time calculation.
454 The minimum is 0, and the maximum is 32.
456 Enable ECN when using DCCC.
458 May be set to 0 or 1.
461 .Bl -tag -width indent
463 Get the ucred of a SCTP connection.
465 List of active SCTP associations.
467 SCTP statistics (struct sctp_stat).
468 .It Va diag_info_code
469 Diagnostic information error cause code.
471 Enable SCTP blackholing.
475 .It Va buffer_splitting
476 Enable send/receive buffer splitting.
477 .It Va vtag_time_wait
478 Vtag wait time in seconds, 0 to disable.
479 .It Va nat_friendly_init
480 Enable sending of the NAT-friendly SCTP option on INITs.
481 .It Va enable_sack_immediately
482 Enable sending of the SACK-IMMEDIATELY bit.
483 .It Va udp_tunneling_port
484 Set the SCTP/UDP tunneling port.
485 .It Va mobility_fasthandoff
486 Enable SCTP fast handoff.
488 Enable SCTP base mobility
489 .It Va default_frag_interleave
490 Default fragment interleave level.
491 .It Va default_ss_module
492 Default stream scheduling module.
494 Ltrace/KTR trace logging level.
495 .It Va max_retran_chunk
496 Number of retransmissions of a DATA chunk before an association is aborted.
498 Minimum residual data chunk in second part of split.
499 .It Va strict_data_order
500 Enforce strict data ordering, abort if control inside data.
501 .It Va abort_at_limit
502 Abort when one-to-one hits qlimit.
504 Confirmation heartbeat max burst.
506 Flush chunks in receive queues with TSN higher than the cumulative TSN if the
507 system is low on mbufs.
508 .It Va max_chained_mbufs
509 Default max number of small mbufs on a chain.
511 SCTP ABC max increase per SACK (L).
513 SCTP NAT friendly operation.
518 .It Va outgoing_streams
519 Default number of outgoing streams.
520 .It Va incoming_streams
521 Default number of incoming streams.
522 .It Va add_more_on_output
523 When space-wise is it worthwhile to try to add more to a socket send buffer.
524 .It Va path_pf_threshold
525 Default potentially failed threshold.
527 Default maximum of retransmissions per path.
529 Default maximum number of retransmissions per association.
531 Default maximum number of retransmissions for INIT chunks.
532 .It Va valid_cookie_life
533 Default cookie lifetime in seconds.
535 Default maximum retransmission timeout during association setup in ms.
537 Default initial retransmission timeout in ms.
539 Default minimum retransmission timeout in ms.
541 Default maximum retransmission timeout in ms.
542 .It Va secret_lifetime
543 Default secret lifetime in seconds.
544 .It Va shutdown_guard_time
545 Shutdown guard timer in seconds (0 means 5 times RTO.Max).
546 .It Va pmtu_raise_time
547 Default PMTU raise timer in seconds.
548 .It Va heartbeat_interval
549 Default heartbeat interval in ms.
551 Max number of cached resources in an association.
553 Max number of cached resources in the system.
555 Default SACK frequency.
556 .It Va delayed_sack_time
557 Default delayed SACK timer in ms.
559 Tunable for scaling of number of chunks and messages.
560 .It Va min_split_point
561 Minimum size when splitting a chunk.
563 Tunable for PCB hash table sizes.
565 Tunable for TCB hash table sizes.
567 Default max chunks on queue per association.
569 Default max burst for SCTP endpoints when fast retransmitting.
571 Default max burst for SCTP endpoints.
573 Amount to debit peers rwnd per chunk sent.
575 Enable SCTP Strict SACK checking.
576 .It Va pktdrop_enable
580 .It Va reconfig_enable
581 Enable SCTP RE-CONFIG.
589 Enable SCTP Auto-ASCONF.
591 Maximum incoming SCTP buffer size.
593 Maximum outgoing SCTP buffer size.
603 .Xr sctp_connectx 3 ,
604 .Xr sctp_opt_info 3 ,