]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man4/sctp.4
MFC r363079, r363080, r363129, r363133:
[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 July 9, 2020
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 -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_ACK_TIME
303 This option lets the user both set and get the
304 delayed ack time (in milliseconds) that
305 .Tn SCTP
306 is using.
307 The default is 200 milliseconds.
308 .It Dv SCTP_PARTIAL_DELIVERY_POINT
309 .Tn SCTP
310 at times may need to start delivery of a
311 very large message before the entire message has
312 arrived.
313 By default SCTP waits until the incoming
314 message is larger than one fourth of the receive
315 buffer.
316 This option allows the stacks value
317 to be overridden with a smaller value.
318 .It Dv SCTP_FRAGMENT_INTERLEAVE
319 .Tn SCTP
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
326 delivered.
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
335 authenticated.
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
341 not existing ones.
342 .It Dv SCTP_AUTH_KEY
343 This option allows a user to specify a shared
344 key that can be later used to authenticate
345 a peer.
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
370 .Tn SCTP
371 stack will automatically generate address changes into add and
372 delete requests to any peers by setting this option to
373 true.
374 This option allows an endpoint to disable that behavior.
375 .It Dv SCTP_MAXBURST
376 By default
377 .Tn SCTP
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.
382 .It Dv SCTP_CONTEXT
383 Many sctp extended calls have a context field.
384 The context field is a 32 bit opaque value that will be returned in
385 send failures.
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.
390 .Tn SCTP
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
394 special flag
395 .Dv SCTP_EOR
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
400 after the
401 .Dv SCTP_EOR
402 is passed to
403 .Tn SCTP
404 else an error will be returned.
405 .It Dv SCTP_STATUS
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
410 address.
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.
420 Note that the peer
421 .Tn SCTP
422 endpoint must also support the stream reset extension
423 as well.
424 .El
425 .Ss MIB Variables
426 The
427 .Tn SCTP
428 protocol implements a number of variables in the
429 .Va net.inet.sctp
430 branch of the
431 .Xr sysctl 3
432 MIB.
433 .Bl -ohang
434 .It Sy Congestion Control
435 .Bl -tag -width indent
436 .It Va default_cc_module
437 Default congestion control module.
438 Default value is 0.
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.
444 .It Va initial_cwnd
445 Defines the initial congestion window size in MTUs.
446 .It Va cwnd_maxburst
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.
449 .It Va ecn_enable
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.
454 Default value is 20.
455 The minimum is 0, and the maximum is 65535.
456 .It Va rttvar_eqret
457 Whether DCCC reduces the congestion window size when round-trip time and bandwidth remain unchanged.
458 Default value is 0.
459 May be set to 0 or 1.
460 .It Va rttvar_bw
461 Shift amount DCCC uses for bandwidth smoothing on round-trip-time calculation.
462 Default value is 4.
463 The minimum is 0, and the maximum is 32.
464 .It Va rttvar_rtt
465 Shift amount DCCC uses for round-trip-time smoothing on round-trip-time calculation.
466 Default value is 5.
467 The minimum is 0, and the maximum is 32.
468 .It Va use_dcccecn
469 Enable ECN when using DCCC.
470 Default value is 1.
471 May be set to 0 or 1.
472 .El
473 .It Sy Misc
474 .Bl -tag -width indent
475 .It Va getcred
476 Get the ucred of a SCTP connection.
477 .It Va assoclist
478 List of active SCTP associations.
479 .It Va stats
480 SCTP statistics (struct sctp_stat).
481 .It Va diag_info_code
482 Diagnostic information error cause code.
483 .It Va blackhole
484 Enable SCTP blackholing.
485 See
486 .Xr blackhole 4
487 for more details.
488 .It Va sendall_limit
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.
502 .It Va mobility_base
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.
508 .It Va log_level
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.
512 .It Va min_residual
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.
518 .It Va hb_max_burst
519 Confirmation heartbeat max burst.
520 .It Va do_sctp_drain
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.
525 .It Va abc_l_var
526 SCTP ABC max increase per SACK (L).
527 .It Va nat_friendly
528 SCTP NAT friendly operation.
529 .It Va cmt_use_dac
530 CMT DAC on/off flag.
531 .It Va cmt_on_off
532 CMT settings.
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.
541 .It Va path_rtx_max
542 Default maximum of retransmissions per path.
543 .It Va assoc_rtx_max
544 Default maximum number of retransmissions per association.
545 .It Va init_rtx_max
546 Default maximum number of retransmissions for INIT chunks.
547 .It Va valid_cookie_life
548 Default cookie lifetime in seconds.
549 .It Va init_rto_max
550 Default maximum retransmission timeout during association setup in ms.
551 .It Va rto_initial
552 Default initial retransmission timeout in ms.
553 .It Va rto_min
554 Default minimum retransmission timeout in ms.
555 .It Va rto_max
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.
565 .It Va asoc_resource
566 Max number of cached resources in an association.
567 .It Va sys_resource
568 Max number of cached resources in the system.
569 .It Va sack_freq
570 Default SACK frequency.
571 .It Va delayed_sack_time
572 Default delayed SACK timer in ms.
573 .It Va chunkscale
574 Tunable for scaling of number of chunks and messages.
575 .It Va min_split_point
576 Minimum size when splitting a chunk.
577 .It Va pcbhashsize
578 Tunable for PCB hash table sizes.
579 .It Va tcbhashsize
580 Tunable for TCB hash table sizes.
581 .It Va maxchunks
582 Default max chunks on queue per association.
583 .It Va fr_maxburst
584 Default max burst for SCTP endpoints when fast retransmitting.
585 .It Va maxburst
586 Default max burst for SCTP endpoints.
587 .It Va peer_chkoh
588 Amount to debit peers rwnd per chunk sent.
589 .It Va strict_sacks
590 Enable SCTP Strict SACK checking.
591 .It Va pktdrop_enable
592 Enable SCTP PKTDROP.
593 .It Va nrsack_enable
594 Enable SCTP NR-SACK.
595 .It Va reconfig_enable
596 Enable SCTP RE-CONFIG.
597 .It Va asconf_enable
598 Enable SCTP ASCONF.
599 .It Va auth_enable
600 Enable SCTP AUTH.
601 .It Va pr_enable
602 Enable PR-SCTP.
603 .It Va auto_asconf
604 Enable SCTP Auto-ASCONF.
605 .It Va recvspace
606 Maximum incoming SCTP buffer size.
607 .It Va sendspace
608 Maximum outgoing SCTP buffer size.
609 .El
610 .El
611 .Sh SEE ALSO
612 .Xr accept 2 ,
613 .Xr bind 2 ,
614 .Xr connect 2 ,
615 .Xr listen 2 ,
616 .Xr sctp_bindx 3 ,
617 .Xr sctp_connectx 3 ,
618 .Xr sctp_opt_info 3 ,
619 .Xr sctp_recvmsg 3 ,
620 .Xr sctp_sendmsg 3 ,
621 .Xr blackhole 4
622 .Sh BUGS
623 The
624 .Nm
625 kernel module cannot be unloaded.