]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man4/sctp.4
Import device-tree files from Linux 6.3
[FreeBSD/FreeBSD.git] / share / man / man4 / sctp.4
1 .\" Copyright (c) 2006, Randall Stewart.
2 .\"
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
5 .\" are met:
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.
14 .\"
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
25 .\" SUCH DAMAGE.
26 .\"
27 .\" $FreeBSD$
28 .\"
29 .Dd June 21, 2023
30 .Dt SCTP 4
31 .Os
32 .Sh NAME
33 .Nm sctp
34 .Nd Internet Stream Control Transmission Protocol
35 .Sh SYNOPSIS
36 .Cd "options SCTP"
37 .Cd "options SCTP_SUPPORT"
38 .Pp
39 .In sys/types.h
40 .In sys/socket.h
41 .In netinet/sctp.h
42 .Ft int
43 .Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP
44 .Ft int
45 .Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP
46 .Sh DESCRIPTION
47 The
48 .Tn SCTP
49 protocol provides reliable, flow-controlled, two-way
50 transmission of data.
51 It is a message oriented protocol and can
52 support the
53 .Dv SOCK_STREAM
54 and
55 .Dv SOCK_SEQPACKET
56 abstractions.
57 .Tn SCTP
58 uses the standard
59 Internet address format and, in addition, provides a per-host
60 collection of
61 .Dq "port addresses" .
62 Thus, each address is composed of an Internet address specifying
63 the host and network, with a specific
64 .Tn SCTP
65 port on the host identifying the peer entity.
66 .Pp
67 There are two models of programming in SCTP.
68 The first uses the
69 .Dv SOCK_STREAM
70 abstraction.
71 In this abstraction sockets utilizing the
72 .Tn SCTP
73 protocol are either
74 .Dq active
75 or
76 .Dq passive .
77 Active sockets initiate connections to passive
78 sockets.
79 By default,
80 .Tn SCTP
81 sockets are created active; to create a
82 passive socket, the
83 .Xr listen 2
84 system call must be used after binding the socket with the
85 .Xr bind 2
86 or
87 .Xr sctp_bindx 3
88 system calls.
89 Only passive sockets may use the
90 .Xr accept 2
91 call to accept incoming connections.
92 Only active sockets may use the
93 .Xr connect 2
94 call to initiate connections.
95 .Pp
96 The other abstraction
97 .Dv SOCK_SEQPACKET
98 provides a
99 .Dq connectionless
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
104 .Tn SCTP
105 transport stack.
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
109 .Xr listen 2
110 to allow the socket to accept connections.
111 Calling
112 .Xr listen 2
113 however does not restrict the user from still initiating
114 implicit connections to other peers.
115 .Pp
116 The
117 .Tn SCTP
118 protocol directly supports multi-homing.
119 So when binding a socket with the
120 .Dq wildcard
121 address
122 .Dv INADDR_ANY ,
123 the
124 .Tn SCTP
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.
128 .Pp
129 The
130 .Tn SCTP
131 transport protocol is also multi-streamed.
132 Multi-streaming refers to the ability to send sub-ordered flows of
133 messages.
134 A user performs this by specifying a specific stream in one of the
135 extended send calls such as the
136 .Xr sctp_send 3
137 function call.
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.
141 .Pp
142 The
143 .Tn SCTP
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.
147 .Pp
148 The
149 .Tn SCTP
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
153 with
154 .Cd "options SCTP_SUPPORT" .
155 .Ss Extensions
156 The
157 .Fx
158 implementation of
159 .Tn SCTP
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
172 association.
173 A shared key option is also provided for
174 so that two stacks can pre-share keys.
175 .It "packet drop"
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
179 utilization.
180 .It "stream reset"
181 This extension allows a user on either side to reset the
182 stream sequence numbers used by any or all streams.
183 .El
184 .Ss Socket Options
185 .Tn SCTP
186 supports a number of socket options which can be set with
187 .Xr setsockopt 2
188 and tested with
189 .Xr getsockopt 2
190 or
191 .Xr sctp_opt_info 3 :
192 .Bl -tag -width indent
193 .It Dv SCTP_NODELAY
194 Under most circumstances,
195 .Tn SCTP
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.
202 The boolean option
203 .Dv SCTP_NODELAY
204 defeats this algorithm.
205 .It Dv SCTP_RTOINFO
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
211 association.
212 .It Dv SCTP_INITMSG
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
217 of the peer.
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
226 closed.
227 The default for this value is 0, or unlimited (i.e., no automatic
228 close).
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
246 By default
247 .Tn SCTP
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
253 sent.
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
259 calls (e.g.,
260 .Xr sctp_sendmsg 3 )
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).
268 .It Dv SCTP_EVENTS
269 .Tn SCTP
270 has non-data events that it can communicate
271 to its application.
272 By default these are all disabled since they arrive in the data path
273 with a special flag
274 .Dv MSG_NOTIFICATION
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
279 in receiving.
280 .It Dv SCTP_I_WANT_MAPPED_V4_ADDR
281 .Tn SCTP
282 supports both IPV4 and IPV6.
283 An association may span both IPV4 and IPV6 addresses since
284 .Tn SCTP
285 is multi-homed.
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
289 of AF_INET.
290 If this is undesirable, then this option
291 can be enabled which will then convert all V4 addresses
292 into mapped V6 representations.
293 .It Dv SCTP_MAXSEG
294 By default
295 .Tn SCTP
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
305 .Tn SCTP
306 is using.
307 The default delayed ack time is 200 milliseconds and the default
308 ack frequency is 2.
309 .It Dv SCTP_PARTIAL_DELIVERY_POINT
310 .Tn SCTP
311 at times may need to start delivery of a
312 very large message before the entire message has
313 arrived.
314 By default SCTP waits until the incoming
315 message is larger than one fourth of the receive
316 buffer.
317 This option allows the stacks value
318 to be overridden with a smaller value.
319 .It Dv SCTP_FRAGMENT_INTERLEAVE
320 .Tn SCTP
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
327 delivered.
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
336 authenticated.
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
342 not existing ones.
343 .It Dv SCTP_AUTH_KEY
344 This option allows a user to specify a shared
345 key that can be later used to authenticate
346 a peer.
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
371 .Tn SCTP
372 stack will automatically generate address changes into add and
373 delete requests to any peers by setting this option to
374 true.
375 This option allows an endpoint to disable that behavior.
376 .It Dv SCTP_MAXBURST
377 By default
378 .Tn SCTP
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.
383 .It Dv SCTP_CONTEXT
384 Many sctp extended calls have a context field.
385 The context field is a 32 bit opaque value that will be returned in
386 send failures.
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.
391 .Tn SCTP
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
395 special flag
396 .Dv SCTP_EOR
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
401 after the
402 .Dv SCTP_EOR
403 is passed to
404 .Tn SCTP
405 else an error will be returned.
406 .It Dv SCTP_STATUS
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
411 address.
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.
421 Note that the peer
422 .Tn SCTP
423 endpoint must also support the stream reset extension
424 as well.
425 .El
426 .Ss MIB Variables
427 The
428 .Tn SCTP
429 protocol implements a number of variables in the
430 .Va net.inet.sctp
431 branch of the
432 .Xr sysctl 3
433 MIB.
434 .Bl -ohang
435 .It Sy Congestion Control
436 .Bl -tag -width indent
437 .It Va default_cc_module
438 Default congestion control module.
439 Default value is 0.
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.
445 .It Va initial_cwnd
446 Defines the initial congestion window size in MTUs.
447 .It Va cwnd_maxburst
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.
450 .It Va ecn_enable
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.
455 Default value is 20.
456 The minimum is 0, and the maximum is 65535.
457 .It Va rttvar_eqret
458 Whether DCCC reduces the congestion window size when round-trip time and bandwidth remain unchanged.
459 Default value is 0.
460 May be set to 0 or 1.
461 .It Va rttvar_bw
462 Shift amount DCCC uses for bandwidth smoothing on round-trip-time calculation.
463 Default value is 4.
464 The minimum is 0, and the maximum is 32.
465 .It Va rttvar_rtt
466 Shift amount DCCC uses for round-trip-time smoothing on round-trip-time calculation.
467 Default value is 5.
468 The minimum is 0, and the maximum is 32.
469 .It Va use_dcccecn
470 Enable ECN when using DCCC.
471 Default value is 1.
472 May be set to 0 or 1.
473 .El
474 .It Sy Misc
475 .Bl -tag -width indent
476 .It Va getcred
477 Get the ucred of a SCTP connection.
478 .It Va assoclist
479 List of active SCTP associations.
480 .It Va stats
481 SCTP statistics (struct sctp_stat).
482 .It Va diag_info_code
483 Diagnostic information error cause code.
484 .It Va blackhole
485 Enable SCTP blackholing.
486 See
487 .Xr blackhole 4
488 for more details.
489 .It Va sendall_limit
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.
503 .It Va mobility_base
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.
509 .It Va log_level
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.
513 .It Va min_residual
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.
519 .It Va hb_max_burst
520 Confirmation heartbeat max burst.
521 .It Va do_sctp_drain
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.
526 .It Va abc_l_var
527 SCTP ABC max increase per SACK (L).
528 .It Va nat_friendly
529 SCTP NAT friendly operation.
530 .It Va cmt_use_dac
531 CMT DAC on/off flag.
532 .It Va cmt_on_off
533 CMT settings.
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.
542 .It Va path_rtx_max
543 Default maximum of retransmissions per path.
544 .It Va assoc_rtx_max
545 Default maximum number of retransmissions per association.
546 .It Va init_rtx_max
547 Default maximum number of retransmissions for INIT chunks.
548 .It Va valid_cookie_life
549 Default cookie lifetime in seconds.
550 .It Va init_rto_max
551 Default maximum retransmission timeout during association setup in ms.
552 .It Va rto_initial
553 Default initial retransmission timeout in ms.
554 .It Va rto_min
555 Default minimum retransmission timeout in ms.
556 .It Va rto_max
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.
566 .It Va asoc_resource
567 Max number of cached resources in an association.
568 .It Va sys_resource
569 Max number of cached resources in the system.
570 .It Va sack_freq
571 Default SACK frequency.
572 .It Va delayed_sack_time
573 Default delayed SACK timer in ms.
574 .It Va chunkscale
575 Tunable for scaling of number of chunks and messages.
576 .It Va min_split_point
577 Minimum size when splitting a chunk.
578 .It Va pcbhashsize
579 Tunable for PCB hash table sizes.
580 .It Va tcbhashsize
581 Tunable for TCB hash table sizes.
582 .It Va maxchunks
583 Default max chunks on queue per association.
584 .It Va fr_maxburst
585 Default max burst for SCTP endpoints when fast retransmitting.
586 .It Va maxburst
587 Default max burst for SCTP endpoints.
588 .It Va peer_chkoh
589 Amount to debit peers rwnd per chunk sent.
590 .It Va strict_sacks
591 Enable SCTP Strict SACK checking.
592 .It Va pktdrop_enable
593 Enable SCTP PKTDROP.
594 .It Va nrsack_enable
595 Enable SCTP NR-SACK.
596 .It Va reconfig_enable
597 Enable SCTP RE-CONFIG.
598 .It Va asconf_enable
599 Enable SCTP ASCONF.
600 .It Va auth_enable
601 Enable SCTP AUTH.
602 .It Va pr_enable
603 Enable PR-SCTP.
604 .It Va auto_asconf
605 Enable SCTP Auto-ASCONF.
606 .It Va recvspace
607 Maximum incoming SCTP buffer size.
608 .It Va sendspace
609 Maximum outgoing SCTP buffer size.
610 .El
611 .El
612 .Sh SEE ALSO
613 .Xr accept 2 ,
614 .Xr bind 2 ,
615 .Xr connect 2 ,
616 .Xr listen 2 ,
617 .Xr sctp_bindx 3 ,
618 .Xr sctp_connectx 3 ,
619 .Xr sctp_opt_info 3 ,
620 .Xr sctp_recvmsg 3 ,
621 .Xr sctp_sendmsg 3 ,
622 .Xr blackhole 4
623 .Sh BUGS
624 The
625 .Nm
626 kernel module cannot be unloaded.