1SCTP(7) Linux Programmer's Manual SCTP(7)
2
6 sctp - SCTP protocol.
7
9 #include <sys/socket.h>
10 #include <netinet/in.h>
11 #include <netinet/sctp.h>
12 sctp_socket = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
14 sctp_socket = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
15
17 This is an implementation of the SCTP protocol as defined in RFC2960
18 and RFC3309. It is a message oriented, reliable transport protocol with
19 direct support for multihoming that runs on top of ip(7), and supports
20 both v4 and v6 versions.
21 Like TCP, SCTP provides reliable, connection oriented data delivery
23 with congestion control. Unlike TCP, SCTP also provides message bound‐
24 ary preservation, ordered and unordered message delivery, multi-stream‐
25 ing and multi-homing. Detection of data corruption, loss of data and
26 duplication of data is achieved by using checksums and sequence num‐
27 bers. A selective retransmission mechanism is applied to correct loss
28 or corruption of data.
29 This implementation supports a mapping of SCTP into sockets API as
31 defined in the draft-ietf-tsvwg-sctpsocket-10.txt(Sockets API exten‐
32 sions for SCTP). Two styles of interfaces are supported.
33 A one-to-many style interface with 1 to MANY relationship between
35 socket and associations where the outbound association setup is
36 implicit. The syntax of a one-to-many style socket() call is
37 sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
39 A typical server in this style uses the following socket calls in
41 sequence to prepare an endpoint for servicing requests.
42 1. socket()
44 2. bind()
45 3. listen()
46 4. recvmsg()
47 5. sendmsg()
48 6. close()
49 A typical client uses the following calls in sequence to setup an asso‐
51 ciation with a server to request services.
52 1. socket()
54 2. sendmsg()
55 3. recvmsg()
56 4. close()
57 A one-to-one style interface with a 1 to 1 relationship between socket
59 and association which enables existing TCP applications to be ported to
60 SCTP with very little effort. The syntax of a one-to-one style socket()
61 call is
62 sd = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
64 A typical server in one-to-one style uses the following system call
66 sequence to prepare an SCTP endpoint for servicing requests:
67 1. socket()
69 2. bind()
70 3. listen()
71 4. accept()
72 The accept() call blocks until a new association is set up. It returns
74 with a new socket descriptor. The server then uses the new socket
75 descriptor to communicate with the client, using recv() and send()
76 calls to get requests and send back responses. Then it calls
77 5. close()
79 to terminate the association. A typical client uses the following sys‐
81 tem call sequence to setup an association with a server to request ser‐
82 vices:
83 1. socket()
85 2. connect()
86 After returning from connect(), the client uses send() and recv() calls
88 to send out requests and receive responses from the server. The client
89 calls
90 3. close()
92 to terminate this association when done.
94
96 SCTP is built on top of IP (see ip(7)). The address formats defined by
97 ip(7) apply to SCTP. SCTP only supports point-to-point communication;
98 broadcasting and multicasting are not supported.
99
101 These variables can be accessed by the /proc/sys/net/sctp/* files or
102 with the sysctl(2) interface. In addition, most IP sysctls also apply
103 to SCTP. See ip(7).
104 addip_enable
106 Enable SCTP ADDIP(Dynamic Address Reconfiguration) Support. This
107 is off by default.
108 association_max_retrans
110 Maximum number of consecutive retransmissions to a peer before
111 an endpoint considers that the peer is unreachable and closes
112 the association. The default value is 10.
113 cookie_preserve_enable
115 Handle COOKIE PRESERVATIVE parameter in the INIT chunk. This is
116 on by default.
117 hb_interval
119 This is the interval when a HEARTBEAT chunk is sent to a desti‐
120 nation transport address to monitor the reachability of an idle
121 destination transport address. The default is 30 seconds and is
122 maintained in msecs.
123 max_burst
125 Maximum number of new data packets that can be sent in a burst.
126 The default value is 4.
127 max_init_retransmits
129 Maximum number of times an INIT chunk or a COOKIE ECHO chunk is
130 retransmitted before an endpoint aborts the initialization
131 process and closes the association. The default value is 8.
132 path_max_retrans
134 Maximum number of consecutive retransmissions over a destination
135 transport address of a peer endpoint before it is marked as
136 inactive. The default value is 5.
137 prsctp_enable
139 Enable PR-SCTP. This is on by default.
140 rcvbuf_policy
142 This controls the socket receive buffer accounting policy. The
143 default value is 0 and indicates that all the associations
144 belonging to a socket share the same receive buffer space. When
145 set to 1, each association will have its own receive buffer
146 space.
147 rto_alpha_exp_divisor
149 This is the RTO.Alpha value when expressed in right shifts and
150 is used in RTO calculations. The default value is 3.
151 rto_beta_exp_divisor
153 This is the RTO.Beta value when expressed in right shifts and is
154 used in RTO calculations. The default value is 2.
155 rto_initial
157 This is the initial value of RTO(retransmission timeout) that is
158 used in RTO calculations. The default value is 3 seconds and is
159 maintained in msecs.
160 rto_max
162 This is the maximum value of RTO(retransmission timeout) that is
163 used in RTO calculations. The default value is 60 seconds and is
164 maintained in msecs.
165 rto_min
167 This is the minimum value of RTO(retransmission timeout) that is
168 used in RTO calculations. The default value is 1 second and is
169 maintained in msecs.
170 sack_timeout
172 Delayed SACK timeout. The default value is 200msecs.
173 sndbuf_policy
175 This controls the socket sendbuffer accounting policy. The
176 default value is 0 and indicates that all the associations
177 belonging to a socket share the same send buffer space. When set
178 to 1, each association will have its own send buffer space.
179 valid_cookie_life
181 This is the maximum lifespan of the Cookie sent in an INIT ACK
182 chunk. The default value is 60 secs and is maintained in msecs.
183
185 These variables can be accessed by the /proc/net/sctp/* files.
186 assocs Displays the following information about the active associa‐
188 tions. assoc ptr, sock ptr, socket style, sock state, associa‐
189 tion state, hash bucket, association id, bytes in transmit
190 queue, bytes in receive queue, user id, inode, local port,
191 remote port, local addresses and remote addresses.
192 eps Displays the following information about the active endpoints.
194 endpoint ptr, sock ptr, socket style, sock state, hash bucket,
195 local port, user id, inode and local addresses.
196 snmp Displays the following statistics related to SCTP states, pack‐
198 ets and chunks.
199 SctpCurrEstab
202 The number of associations for which the current state is
203 either ESTABLISHED, SHUTDOWN-RECEIVED or SHUTDOWN-PEND‐
204 ING.
205 SctpActiveEstabs
207 The number of times that associations have made a direct
208 transition to the ESTABLISHED state from the COOKIE-
209 ECHOED state. The upper layer initiated the association
210 attempt.
211 SctpPassiveEstabs
213 The number of times that associations have made a direct
214 transition to the ESTABLISHED state from the CLOSED
215 state. The remote endpoint initiated the association
216 attempt.
217 SctpAborteds
219 The number of times that associations have made a direct
220 transition to the CLOSED state from any state using the
221 primitive 'ABORT'. Ungraceful termination of the associa‐
222 tion.
223 SctpShutdowns
225 The number of times that associations have made a direct
226 transition to the CLOSED state from either the SHUTDOWN-
227 SENT state or the SHUTDOWN-ACK-SENT state. Graceful ter‐
228 mination of the association.
229 SctpOutOfBlues
231 The number of out of the blue packets received by the
232 host. An out of the blue packet is an SCTP packet cor‐
233 rectly formed, including the proper checksum, but for
234 which the receiver was unable to identify an appropriate
235 association.
236 SctpChecksumErrors
238 The number of SCTP packets received with an invalid
239 checksum.
240 SctpOutCtrlChunks
242 The number of SCTP control chunks sent (retransmissions
243 are not included). Control chunks are those chunks dif‐
244 ferent from DATA.
245 SctpOutOrderChunks
247 The number of SCTP ordered data chunks sent (retransmis‐
248 sions are not included).
249 SctpOutUnorderChunks
251 The number of SCTP unordered chunks(data chunks in which
252 the U bit is set to 1) sent (retransmissions are not
253 included).
254 SctpInCtrlChunks
256 The number of SCTP control chunks received (no duplicate
257 chunks included).
258 SctpInOrderChunks
260 The number of SCTP ordered data chunks received (no
261 duplicate chunks included).
262 SctpInUnorderChunks
264 The number of SCTP unordered chunks(data chunks in which
265 the U bit is set to 1) received (no duplicate chunks
266 included).
267 SctpFragUsrMsgs
269 The number of user messages that have to be fragmented
270 because of the MTU.
271 SctpReasmUsrMsgs
273 The number of user messages reassembled, after conversion
274 into DATA chunks.
275 SctpOutSCTPPacks
277 The number of SCTP packets sent. Retransmitted DATA
278 chunks are included.
279 SctpInSCTPPacks
281 The number of SCTP packets received. Duplicates are
282 included.
283
285 To set or get a SCTP socket option, call getsockopt(2) to read
286 or setsockopt(2) to write the option with the option level argu‐
287 ment set to SOL_SCTP.
288 SCTP_RTOINFO.
290 This option is used to get or set the protocol parameters
291 used to initialize and bound retransmission timout(RTO).
292 The structure sctp_rtoinfo defined in
293 /usr/include/netinet/sctp.h is used to access and modify
294 these parameters.
295 SCTP_ASSOCINFO
297 This option is used to both examine and set various asso‐
298 ciation and endpoint parameters. The sturcture
299 sctp_assocparams defined in /usr/include/netinet/sctp.h
300 is used to access and modify these parameters.
301 SCTP_INITMSG
303 This option is used to get or set the protocol parameters
304 for the default association initialization. The structure
305 sctp_initmsg defined in /usr/include/netinet/sctp.h is
306 used to access and modify these parameters.
307 Setting initialization parameters is effective only on an
309 unconnected socket (for one-to-many style sockets only
310 future associations are effected by the change). With
311 one-to-one style sockets, this option is inherited by
312 sockets derived from a listener socket.
313 SCTP_NODELAY
315 Turn on/off any Nagle-like algorithm. This means that
316 packets are generally sent as soon as possible and no
317 unnecessary delays are introduced, at the cost of more
318 packets in the network. Expects an integer boolean flag.
319 SCTP_AUTOCLOSE
321 This socket option is applicable to the one-to-many style
322 socket only. When set it will cause associations that are
323 idle for more than the specified number of seconds to
324 automatically close. An association being idle is defined
325 an association that has NOT sent or received user data.
326 The special value of 0 indicates that no automatic close
327 of any associations should be performed. The option
328 expects an integer defining the number of seconds of idle
329 time before an association is closed.
330 SCTP_SET_PEER_PRIMARY_ADDR
332 Requests that the peer mark the enclosed address as the
333 association primary. The enclosed address must be one of
334 the association's locally bound addresses. The structure
335 sctp_setpeerprim defined in /usr/include/netinet/sctp.h
336 is used to make a set peer primary request.
337 SCTP_PRIMARY_ADDR
339 Requests that the local SCTP stack use the enclosed peer
340 address as the association primary. The enclosed address
341 must be one of the association peer's addresses. The
342 structure sctp_prim defined in
343 /usr/include/netinet/sctp.h is used to make a get/set
344 primary request.
345 SCTP_DISABLE_FRAGMENTS
347 This option is a on/off flag and is passed an integer
348 where a non-zero is on and a zero is off. If enabled no
349 SCTP message fragmentation will be performed. Instead if
350 a message being sent exceeds the current PMTU size, the
351 message will NOT be sent and an error will be indicated
352 to the user.
353 SCTP_PEER_ADDR_PARAMS
355 Using this option, applications can enable or disable
356 heartbeats for any peer address of an association, modify
357 an address's heartbeat interval, force a heartbeat to be
358 sent immediately, and adjust the address's maximum number
359 of retransmissions sent before an address is considered
360 unreachable. The structure sctp_paddrparams defined in
361 /usr/include/netinet/sctp.h is used to access and modify
362 an address's parameters.
363 SCTP_DEFAULT_SEND_PARAM
365 Applications that wish to use the sendto() system call
366 may wish to specify a default set of parameters that
367 would normally be supplied through the inclusion of
368 ancillary data. This socket option allows such an appli‐
369 cation to set the default sctp_sndrcvinfo structure. The
370 application that wishes to use this socket option simply
371 passes in to this call the sctp_sndrcvinfo structure
372 defined in /usr/include/netinet/sctp.h. The input parame‐
373 ters accepted by this call include sinfo_stream,
374 sinfo_flags, sinfo_ppid, sinfo_context, sinfo_timetolive.
375 The user must set the sinfo_assoc_id field to identify
376 the
377 association to affect if the caller is using the one-to-
378 many style.
379 SCTP_EVENTS
381 This socket option is used to specify various notifica‐
382 tions and ancillary data the user wishes to receive. The
383 structure sctp_event_subscribe defined in
384 /usr/include/netinet/sctp.h is used to access or modify
385 the events of interest to the user.
386 SCTP_I_WANT_MAPPED_V4_ADDR
388 This socket option is a boolean flag which turns on or
389 off mapped V4 addresses. If this option is turned on and
390 the socket is type PF_INET6, then IPv4 addresses will be
391 mapped to V6 representation. If this option is turned
392 off, then no mapping will be done of V4 addresses and a
393 user will receive both PF_INET6 and PF_INET type
394 addresses on the socket.
395 By default this option is turned on and expects an inte‐
397 ger to be passed where non-zero turns on the option and
398 zero turns off the option.
399 SCTP_MAXSEG
401 This socket option specifies the maximum size to put in
402 any outgoing SCTP DATA chunk. If a message is larger than
403 this size it will be fragmented by SCTP into the speci‐
404 fied size. Note that the underlying SCTP implementation
405 may fragment into smaller sized chunks when the PMTU of
406 the underlying association is smaller than the value set
407 by the user. The option expects an integer.
408 The default value for this option is 0 which indicates
410 the user is NOT limiting fragmentation and only the PMTU
411 will effect SCTP's choice of DATA chunk size.
412 SCTP_STATUS
414 Applications can retrieve current status information
415 about an association, including association state, peer
416 receiver window size, number of unacked data chunks, and
417 number of data chunks pending receipt. This information
418 is read-only. The structure sctp_status defined in
419 /usr/include/netinet/sctp.h is used to access this infor‐
420 mation.
421 SCTP_GET_PEER_ADDR_INFO
423 Applications can retrieve information about a specific
424 peer address of an association, including its reachabil‐
425 ity state, congestion window, and retransmission timer
426 values. This information is read-only. The structure
427 sctp_paddr_info defined in /usr/include/netinet/sctp.h is
428 used to access this information.
429
431 Sridhar Samudrala <sri@us.ibm.com>
432
434 socket(7), socket(2), ip(7), bind(2), listen(2), accept(2), con‐
435 nect(2), sendmsg(2), recvmsg(2), sysctl(2), getsockopt(2),
436 sctp_bindx(3), sctp_connectx(3), sctp_sendmsg(3), sctp_send(3),
437 sctp_recvmsg(3), sctp_peeloff(3), sctp_getladdrs(3), sctp_get‐
438 paddrs(3), sctp_opt_info(3).
439 RFC2960, RFC3309 for the SCTP specification.
441Linux Man Page 2005-10-25 SCTP(7)