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_ACK_TIME
303 This option lets the user both set and get the
304 delayed ack time (in milliseconds) that
307 The default is 200 milliseconds.
308 .It Dv SCTP_PARTIAL_DELIVERY_POINT
310 at times may need to start delivery of a
311 very large message before the entire message has
313 By default SCTP waits until the incoming
314 message is larger than one fourth of the receive
316 This option allows the stacks value
317 to be overridden with a smaller value.
318 .It Dv SCTP_FRAGMENT_INTERLEAVE
320 at times will start partial delivery (as mentioned above).
321 In the normal case successive reads will continue to return
322 the rest of the message, blocking if needed, until all of
323 that message is read.
324 However this means other messages may have arrived and be ready
325 for delivery and be blocked behind the message being partially
327 If this option is enabled, when a partial delivery
328 message has no more data to be received, then a subsequent
329 read may return a different message that is ready for delivery.
330 By default this option is off since the user must be using the
331 extended API's to be able to tell the difference between
332 messages (via the stream and stream sequence number).
333 .It Dv SCTP_AUTH_CHUNK
334 By default only the dynamic addressing chunks are
336 This option lets a user request an
337 additional chunk be authenticated as well.
338 Note that successive calls to this option will work and continue
339 to add more chunks that require authentication.
340 Note that this option only effects future associations and
343 This option allows a user to specify a shared
344 key that can be later used to authenticate
346 .It Dv SCTP_HMAC_IDENT
347 This option will let you get or set the list of
348 HMAC algorithms used to authenticate peers.
349 Note that the HMAC values are in priority order where
350 the first HMAC identifier is the most preferred
351 and the last is the least preferred.
352 .It Dv SCTP_AUTH_ACTIVE_KEY
353 This option allows you to make a key active for
354 the generation of authentication information.
355 Note that the peer must have the same key or else the
356 data will be discarded.
357 .It Dv SCTP_AUTH_DELETE_KEY
358 This option allows you to delete an old key.
359 .It Dv SCTP_USE_EXT_RECVINFO
360 The sockets api document allows an extended
361 send/receive information structure to be used.
362 The extended structure includes additional fields
363 related to the next message to be received (after the
364 current receive completes) if such information is known.
365 By default the system will not pass this information.
366 This option allows the user to request this information.
367 .It Dv SCTP_AUTO_ASCONF
368 By default when bound to all address and the system administrator has
369 enables automatic dynamic addresses, the
371 stack will automatically generate address changes into add and
372 delete requests to any peers by setting this option to
374 This option allows an endpoint to disable that behavior.
378 implements micro-burst control so that as the congestion window
379 opens up no large burst of packets can be generated.
380 The default burst limit is four.
381 This option lets the user change this value.
383 Many sctp extended calls have a context field.
384 The context field is a 32 bit opaque value that will be returned in
386 This option lets the caller set the default
387 context value to use when none is provided by the user.
388 .It Dv SCTP_EXPLICIT_EOR
389 By default, a single send is a complete message.
391 generates an implied record boundary.
392 If this option is enabled, then all sends are part of the same message
393 until the user indicates an end of record with the
396 passed in the sctp_sndrcvinfo flags field.
397 This effectively makes all sends part of the same message
398 until the user specifies differently.
399 This means that a caller must NOT change the stream number until
404 else an error will be returned.
406 This option is a read-only option that returns
407 various status information about the specified association.
408 .It Dv SCTP_GET_PEER_ADDR_INFO
409 This read-only option returns information about a peer
411 .It Dv SCTP_PEER_AUTH_CHUNKS
412 This read-only option returns a list of the chunks
413 the peer requires to be authenticated.
414 .It Dv SCTP_LOCAL_AUTH_CHUNKS
415 This read-only option returns a list of the locally
416 required chunks that must be authenticated.
417 .It Dv SCTP_RESET_STREAMS
418 This socket option is used to cause a stream sequence
419 number or all stream sequence numbers to be reset.
422 endpoint must also support the stream reset extension
428 protocol implements a number of variables in the
434 .It Sy Congestion Control
435 .Bl -tag -width indent
436 .It Va default_cc_module
437 Default congestion control module.
439 The minimum is 0, and the maximum is 3.
440 A value of 0 enables the default congestion control algorithm.
441 A value of 1 enables the High Speed congestion control algorithm.
442 A value of 2 enables the HTCP congestion control algorithm.
443 A value of 3 enables the data center congestion control (DCCC) algorithm.
445 Defines the initial congestion window size in MTUs.
447 Use congestion control instead of 'blind' logic to limit maximum burst when sending.
448 Default value is 1. May be set to 0 or 1.
450 Enable Explicit Congestion Notification (ECN).
451 Default value is 1. May be set to 0 or 1.
452 .It Va rttvar_steady_step
453 Number of identical bandwidth measurements DCCC takes to try step down the congestion window.
455 The minimum is 0, and the maximum is 65535.
457 Whether DCCC reduces the congestion window size when round-trip time and bandwidth remain unchanged.
459 May be set to 0 or 1.
461 Shift amount DCCC uses for bandwidth smoothing on round-trip-time calculation.
463 The minimum is 0, and the maximum is 32.
465 Shift amount DCCC uses for round-trip-time smoothing on round-trip-time calculation.
467 The minimum is 0, and the maximum is 32.
469 Enable ECN when using DCCC.
471 May be set to 0 or 1.
474 .Bl -tag -width indent
476 Get the ucred of a SCTP connection.
478 List of active SCTP associations.
480 SCTP statistics (struct sctp_stat).
481 .It Va diag_info_code
482 Diagnostic information error cause code.
484 Enable SCTP blackholing.
489 Maximum message size (in bytes) that can be transmitted with SCTP_SENDALL flags set.
490 .It Va buffer_splitting
491 Enable send/receive buffer splitting.
492 .It Va vtag_time_wait
493 Vtag wait time in seconds, 0 to disable.
494 .It Va nat_friendly_init
495 Enable sending of the NAT-friendly SCTP option on INITs.
496 .It Va enable_sack_immediately
497 Enable sending of the SACK-IMMEDIATELY bit.
498 .It Va udp_tunneling_port
499 Set the SCTP/UDP tunneling port.
500 .It Va mobility_fasthandoff
501 Enable SCTP fast handoff.
503 Enable SCTP base mobility
504 .It Va default_frag_interleave
505 Default fragment interleave level.
506 .It Va default_ss_module
507 Default stream scheduling module.
509 Ltrace/KTR trace logging level.
510 .It Va max_retran_chunk
511 Number of retransmissions of a DATA chunk before an association is aborted.
513 Minimum residual data chunk in second part of split.
514 .It Va strict_data_order
515 Enforce strict data ordering, abort if control inside data.
516 .It Va abort_at_limit
517 Abort when one-to-one hits qlimit.
519 Confirmation heartbeat max burst.
521 Flush chunks in receive queues with TSN higher than the cumulative TSN if the
522 system is low on mbufs.
523 .It Va max_chained_mbufs
524 Default max number of small mbufs on a chain.
526 SCTP ABC max increase per SACK (L).
528 SCTP NAT friendly operation.
533 .It Va outgoing_streams
534 Default number of outgoing streams.
535 .It Va incoming_streams
536 Default number of incoming streams.
537 .It Va add_more_on_output
538 When space-wise is it worthwhile to try to add more to a socket send buffer.
539 .It Va path_pf_threshold
540 Default potentially failed threshold.
542 Default maximum of retransmissions per path.
544 Default maximum number of retransmissions per association.
546 Default maximum number of retransmissions for INIT chunks.
547 .It Va valid_cookie_life
548 Default cookie lifetime in seconds.
550 Default maximum retransmission timeout during association setup in ms.
552 Default initial retransmission timeout in ms.
554 Default minimum retransmission timeout in ms.
556 Default maximum retransmission timeout in ms.
557 .It Va secret_lifetime
558 Default secret lifetime in seconds.
559 .It Va shutdown_guard_time
560 Shutdown guard timer in seconds (0 means 5 times RTO.Max).
561 .It Va pmtu_raise_time
562 Default PMTU raise timer in seconds.
563 .It Va heartbeat_interval
564 Default heartbeat interval in ms.
566 Max number of cached resources in an association.
568 Max number of cached resources in the system.
570 Default SACK frequency.
571 .It Va delayed_sack_time
572 Default delayed SACK timer in ms.
574 Tunable for scaling of number of chunks and messages.
575 .It Va min_split_point
576 Minimum size when splitting a chunk.
578 Tunable for PCB hash table sizes.
580 Tunable for TCB hash table sizes.
582 Default max chunks on queue per association.
584 Default max burst for SCTP endpoints when fast retransmitting.
586 Default max burst for SCTP endpoints.
588 Amount to debit peers rwnd per chunk sent.
590 Enable SCTP Strict SACK checking.
591 .It Va pktdrop_enable
595 .It Va reconfig_enable
596 Enable SCTP RE-CONFIG.
604 Enable SCTP Auto-ASCONF.
606 Maximum incoming SCTP buffer size.
608 Maximum outgoing SCTP buffer size.
617 .Xr sctp_connectx 3 ,
618 .Xr sctp_opt_info 3 ,
625 kernel module cannot be unloaded.