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
37 .Cd "options SCTP_SUPPORT"
43 .Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP
45 .Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP
49 protocol provides reliable, flow-controlled, two-way
51 It is a message oriented protocol and can
59 Internet address format and, in addition, provides a per-host
61 .Dq "port addresses" .
62 Thus, each address is composed of an Internet address specifying
63 the host and network, with a specific
65 port on the host identifying the peer entity.
67 There are two models of programming in SCTP.
71 In this abstraction sockets utilizing the
77 Active sockets initiate connections to passive
81 sockets are created active; to create a
84 system call must be used after binding the socket with the
89 Only passive sockets may use the
91 call to accept incoming connections.
92 Only active sockets may use the
94 call to initiate connections.
100 mode of operation in that the user may send to an address
101 (using any of the valid send calls that carry a
102 socket address) and an association will be setup
103 implicitly by the underlying
106 This abstraction is the only one capable of sending data on the
107 third leg of the four-way handshake.
108 A user must still call
110 to allow the socket to accept connections.
113 however does not restrict the user from still initiating
114 implicit connections to other peers.
118 protocol directly supports multi-homing.
119 So when binding a socket with the
125 stack will inform the peer about all of the local addresses
126 that are deemed in scope of the peer.
127 The peer will then possibly have multiple paths to reach the local host.
131 transport protocol is also multi-streamed.
132 Multi-streaming refers to the ability to send sub-ordered flows of
134 A user performs this by specifying a specific stream in one of the
135 extended send calls such as the
138 Sending messages on different streams will allow parallel delivery
139 of data i.e., a message loss in stream 1 will not block the delivery
140 of messages sent in stream 2.
144 transport protocol also provides a unordered service as well.
145 The unordered service allows a message to be sent and delivered
146 with no regard to the ordering of any other message.
150 kernel implementation may either be compiled into the kernel, or loaded
151 dynamically as a module.
152 To support dynamic loading of the stack, the kernel must be compiled
154 .Cd "options SCTP_SUPPORT" .
160 also supports the following extensions:
161 .Bl -tag -width "sctp partial reliability"
162 .It "sctp partial reliability"
163 This extension allows one to have message be skipped and
164 not delivered based on some user specified parameters.
165 .It "sctp dynamic addressing"
166 This extension allows addresses to be added and deleted
167 dynamically from an existing association.
168 .It "sctp authentication"
169 This extension allows the user to authenticate specific
170 peer chunks (including data) to validate that the peer
171 who sent the message is in fact the peer who setup the
173 A shared key option is also provided for
174 so that two stacks can pre-share keys.
176 Some routers support a special satellite protocol that
177 will report losses due to corruption.
178 This allows retransmissions without subsequent loss in bandwidth
181 This extension allows a user on either side to reset the
182 stream sequence numbers used by any or all streams.
186 supports a number of socket options which can be set with
191 .Xr sctp_opt_info 3 :
192 .Bl -tag -width indent
194 Under most circumstances,
196 sends data when it is presented; when outstanding data has not
197 yet been acknowledged, it gathers small amounts of output to be
198 sent in a single packet once an acknowledgement is received.
199 For some clients, such as window systems that send a stream of
200 mouse events which receive no replies, this packetization may
201 cause significant delays.
204 defeats this algorithm.
206 This option returns specific information about an associations
207 .Dq "Retransmission Time Out" .
208 It can also be used to change the default values.
209 .It Dv SCTP_ASSOCINFO
210 This option returns specific information about the requested
213 This option allows you to get or set the default sending
214 parameters when an association is implicitly setup.
215 It allows you to change such things as the maximum number of
216 streams allowed inbound and the number of streams requested
218 .It Dv SCTP_AUTOCLOSE
219 For the one-to-many model
220 .Dv ( SOCK_SEQPACKET )
221 associations are setup implicitly.
222 This option allows the user to specify a default number of idle
223 seconds to allow the association be maintained.
224 After the idle timer (where no user message have been sent or have
225 been received from the peer) the association will be gracefully
227 The default for this value is 0, or unlimited (i.e., no automatic
229 .It Dv SCTP_SET_PEER_PRIMARY_ADDR
230 The dynamic address extension allows a peer to also request a
231 particular address of its be made into the primary address.
232 This option allows the caller to make such a request to a peer.
233 Note that if the peer does not also support the dynamic address
234 extension, this call will fail.
235 Note the caller must provide a valid local address that the peer has
236 been told about during association setup or dynamically.
237 .It Dv SCTP_PRIMARY_ADDR
238 This option allows the setting of the primary address
239 that the caller wishes to send to.
240 The caller provides the address of a peer that is to be made primary.
241 .It Dv SCTP_ADAPTATION_LAYER
242 The dynamic address extension also allows a user to
243 pass a 32 bit opaque value upon association setup.
244 This option allows a user to set or get this value.
245 .It Dv SCTP_DISABLE_FRAGMENTS
248 will fragment user messages into multiple pieces that
249 will fit on the network and then later, upon reception, reassemble
250 the pieces into a single user message.
251 If this option is enabled instead, any send that exceeds the path
252 maximum transfer unit (P-MTU) will fail and the message will NOT be
254 .It Dv SCTP_PEER_ADDR_PARAMS
255 This option will allow a user to set or get specific
256 peer address parameters.
257 .It Dv SCTP_DEFAULT_SEND_PARAM
258 When a user does not use one of the extended send
261 a set of default values apply to each send.
262 These values include things like the stream number to send
263 to as well as the per-protocol id.
264 This option lets a caller both get and set these values.
265 If the user changes these default values, then these new values will
266 be used as the default whenever no information is provided by the
267 sender (i.e., the non-extended API is used).
270 has non-data events that it can communicate
272 By default these are all disabled since they arrive in the data path
275 set upon the received message.
276 This option lets a caller
277 both get what events are current being received
278 as well as set different events that they may be interested
280 .It Dv SCTP_I_WANT_MAPPED_V4_ADDR
282 supports both IPV4 and IPV6.
283 An association may span both IPV4 and IPV6 addresses since
286 By default, when opening an IPV6 socket, when
287 data arrives on the socket from a peer's
288 V4 address the V4 address will be presented with an address family
290 If this is undesirable, then this option
291 can be enabled which will then convert all V4 addresses
292 into mapped V6 representations.
296 chooses its message fragmentation point
297 based upon the smallest P-MTU of the peer.
298 This option lets the caller set it to a smaller value.
299 Note that while the user can change this value, if the P-MTU
300 is smaller than the value set by the user, then the P-MTU
301 value will override any user setting.
302 .It Dv SCTP_DELAYED_SACK
303 This option lets the user both set and get the
304 delayed ack time (in milliseconds) and the ack frequency that
307 The default delayed ack time is 200 milliseconds and the default
309 .It Dv SCTP_PARTIAL_DELIVERY_POINT
311 at times may need to start delivery of a
312 very large message before the entire message has
314 By default SCTP waits until the incoming
315 message is larger than one fourth of the receive
317 This option allows the stacks value
318 to be overridden with a smaller value.
319 .It Dv SCTP_FRAGMENT_INTERLEAVE
321 at times will start partial delivery (as mentioned above).
322 In the normal case successive reads will continue to return
323 the rest of the message, blocking if needed, until all of
324 that message is read.
325 However this means other messages may have arrived and be ready
326 for delivery and be blocked behind the message being partially
328 If this option is enabled, when a partial delivery
329 message has no more data to be received, then a subsequent
330 read may return a different message that is ready for delivery.
331 By default this option is off since the user must be using the
332 extended API's to be able to tell the difference between
333 messages (via the stream and stream sequence number).
334 .It Dv SCTP_AUTH_CHUNK
335 By default only the dynamic addressing chunks are
337 This option lets a user request an
338 additional chunk be authenticated as well.
339 Note that successive calls to this option will work and continue
340 to add more chunks that require authentication.
341 Note that this option only effects future associations and
344 This option allows a user to specify a shared
345 key that can be later used to authenticate
347 .It Dv SCTP_HMAC_IDENT
348 This option will let you get or set the list of
349 HMAC algorithms used to authenticate peers.
350 Note that the HMAC values are in priority order where
351 the first HMAC identifier is the most preferred
352 and the last is the least preferred.
353 .It Dv SCTP_AUTH_ACTIVE_KEY
354 This option allows you to make a key active for
355 the generation of authentication information.
356 Note that the peer must have the same key or else the
357 data will be discarded.
358 .It Dv SCTP_AUTH_DELETE_KEY
359 This option allows you to delete an old key.
360 .It Dv SCTP_USE_EXT_RECVINFO
361 The sockets api document allows an extended
362 send/receive information structure to be used.
363 The extended structure includes additional fields
364 related to the next message to be received (after the
365 current receive completes) if such information is known.
366 By default the system will not pass this information.
367 This option allows the user to request this information.
368 .It Dv SCTP_AUTO_ASCONF
369 By default when bound to all address and the system administrator has
370 enables automatic dynamic addresses, the
372 stack will automatically generate address changes into add and
373 delete requests to any peers by setting this option to
375 This option allows an endpoint to disable that behavior.
379 implements micro-burst control so that as the congestion window
380 opens up no large burst of packets can be generated.
381 The default burst limit is four.
382 This option lets the user change this value.
384 Many sctp extended calls have a context field.
385 The context field is a 32 bit opaque value that will be returned in
387 This option lets the caller set the default
388 context value to use when none is provided by the user.
389 .It Dv SCTP_EXPLICIT_EOR
390 By default, a single send is a complete message.
392 generates an implied record boundary.
393 If this option is enabled, then all sends are part of the same message
394 until the user indicates an end of record with the
397 passed in the sctp_sndrcvinfo flags field.
398 This effectively makes all sends part of the same message
399 until the user specifies differently.
400 This means that a caller must NOT change the stream number until
405 else an error will be returned.
407 This option is a read-only option that returns
408 various status information about the specified association.
409 .It Dv SCTP_GET_PEER_ADDR_INFO
410 This read-only option returns information about a peer
412 .It Dv SCTP_PEER_AUTH_CHUNKS
413 This read-only option returns a list of the chunks
414 the peer requires to be authenticated.
415 .It Dv SCTP_LOCAL_AUTH_CHUNKS
416 This read-only option returns a list of the locally
417 required chunks that must be authenticated.
418 .It Dv SCTP_RESET_STREAMS
419 This socket option is used to cause a stream sequence
420 number or all stream sequence numbers to be reset.
423 endpoint must also support the stream reset extension
429 protocol implements a number of variables in the
435 .It Sy Congestion Control
436 .Bl -tag -width indent
437 .It Va default_cc_module
438 Default congestion control module.
440 The minimum is 0, and the maximum is 3.
441 A value of 0 enables the default congestion control algorithm.
442 A value of 1 enables the High Speed congestion control algorithm.
443 A value of 2 enables the HTCP congestion control algorithm.
444 A value of 3 enables the data center congestion control (DCCC) algorithm.
446 Defines the initial congestion window size in MTUs.
448 Use congestion control instead of 'blind' logic to limit maximum burst when sending.
449 Default value is 1. May be set to 0 or 1.
451 Enable Explicit Congestion Notification (ECN).
452 Default value is 1. May be set to 0 or 1.
453 .It Va rttvar_steady_step
454 Number of identical bandwidth measurements DCCC takes to try step down the congestion window.
456 The minimum is 0, and the maximum is 65535.
458 Whether DCCC reduces the congestion window size when round-trip time and bandwidth remain unchanged.
460 May be set to 0 or 1.
462 Shift amount DCCC uses for bandwidth smoothing on round-trip-time calculation.
464 The minimum is 0, and the maximum is 32.
466 Shift amount DCCC uses for round-trip-time smoothing on round-trip-time calculation.
468 The minimum is 0, and the maximum is 32.
470 Enable ECN when using DCCC.
472 May be set to 0 or 1.
475 .Bl -tag -width indent
477 Get the ucred of a SCTP connection.
479 List of active SCTP associations.
481 SCTP statistics (struct sctp_stat).
482 .It Va diag_info_code
483 Diagnostic information error cause code.
485 Enable SCTP blackholing.
490 Maximum message size (in bytes) that can be transmitted with SCTP_SENDALL flags set.
491 .It Va buffer_splitting
492 Enable send/receive buffer splitting.
493 .It Va vtag_time_wait
494 Vtag wait time in seconds, 0 to disable.
495 .It Va nat_friendly_init
496 Enable sending of the NAT-friendly SCTP option on INITs.
497 .It Va enable_sack_immediately
498 Enable sending of the SACK-IMMEDIATELY bit.
499 .It Va udp_tunneling_port
500 Set the SCTP/UDP tunneling port.
501 .It Va mobility_fasthandoff
502 Enable SCTP fast handoff.
504 Enable SCTP base mobility
505 .It Va default_frag_interleave
506 Default fragment interleave level.
507 .It Va default_ss_module
508 Default stream scheduling module.
510 Ltrace/KTR trace logging level.
511 .It Va max_retran_chunk
512 Number of retransmissions of a DATA chunk before an association is aborted.
514 Minimum residual data chunk in second part of split.
515 .It Va strict_data_order
516 Enforce strict data ordering, abort if control inside data.
517 .It Va abort_at_limit
518 Abort when one-to-one hits qlimit.
520 Confirmation heartbeat max burst.
522 Flush chunks in receive queues with TSN higher than the cumulative TSN if the
523 system is low on mbufs.
524 .It Va max_chained_mbufs
525 Default max number of small mbufs on a chain.
527 SCTP ABC max increase per SACK (L).
529 SCTP NAT friendly operation.
534 .It Va outgoing_streams
535 Default number of outgoing streams.
536 .It Va incoming_streams
537 Default number of incoming streams.
538 .It Va add_more_on_output
539 When space-wise is it worthwhile to try to add more to a socket send buffer.
540 .It Va path_pf_threshold
541 Default potentially failed threshold.
543 Default maximum of retransmissions per path.
545 Default maximum number of retransmissions per association.
547 Default maximum number of retransmissions for INIT chunks.
548 .It Va valid_cookie_life
549 Default cookie lifetime in seconds.
551 Default maximum retransmission timeout during association setup in ms.
553 Default initial retransmission timeout in ms.
555 Default minimum retransmission timeout in ms.
557 Default maximum retransmission timeout in ms.
558 .It Va secret_lifetime
559 Default secret lifetime in seconds.
560 .It Va shutdown_guard_time
561 Shutdown guard timer in seconds (0 means 5 times RTO.Max).
562 .It Va pmtu_raise_time
563 Default PMTU raise timer in seconds.
564 .It Va heartbeat_interval
565 Default heartbeat interval in ms.
567 Max number of cached resources in an association.
569 Max number of cached resources in the system.
571 Default SACK frequency.
572 .It Va delayed_sack_time
573 Default delayed SACK timer in ms.
575 Tunable for scaling of number of chunks and messages.
576 .It Va min_split_point
577 Minimum size when splitting a chunk.
579 Tunable for PCB hash table sizes.
581 Tunable for TCB hash table sizes.
583 Default max chunks on queue per association.
585 Default max burst for SCTP endpoints when fast retransmitting.
587 Default max burst for SCTP endpoints.
589 Amount to debit peers rwnd per chunk sent.
591 Enable SCTP Strict SACK checking.
592 .It Va pktdrop_enable
596 .It Va reconfig_enable
597 Enable SCTP RE-CONFIG.
605 Enable SCTP Auto-ASCONF.
607 Maximum incoming SCTP buffer size.
609 Maximum outgoing SCTP buffer size.
618 .Xr sctp_connectx 3 ,
619 .Xr sctp_opt_info 3 ,
626 kernel module cannot be unloaded.