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 Please check kernel documentation for this, at Documentation/network‐
106 ing/ip-sysctl.txt.
107
109 These variables can be accessed by the /proc/net/sctp/* files.
110 assocs Displays the following information about the active associa‐
112 tions. assoc ptr, sock ptr, socket style, sock state, associa‐
113 tion state, hash bucket, association id, bytes in transmit
114 queue, bytes in receive queue, user id, inode, local port,
115 remote port, local addresses and remote addresses.
116 eps Displays the following information about the active endpoints.
118 endpoint ptr, sock ptr, socket style, sock state, hash bucket,
119 local port, user id, inode and local addresses.
120 snmp Displays the following statistics related to SCTP states, pack‐
122 ets and chunks.
123 SctpCurrEstab
126 The number of associations for which the current state is
127 either ESTABLISHED, SHUTDOWN-RECEIVED or SHUTDOWN-PEND‐
128 ING.
129 SctpActiveEstabs
131 The number of times that associations have made a direct
132 transition to the ESTABLISHED state from the COOKIE-
133 ECHOED state. The upper layer initiated the association
134 attempt.
135 SctpPassiveEstabs
137 The number of times that associations have made a direct
138 transition to the ESTABLISHED state from the CLOSED
139 state. The remote endpoint initiated the association
140 attempt.
141 SctpAborteds
143 The number of times that associations have made a direct
144 transition to the CLOSED state from any state using the
145 primitive 'ABORT'. Ungraceful termination of the associa‐
146 tion.
147 SctpShutdowns
149 The number of times that associations have made a direct
150 transition to the CLOSED state from either the SHUTDOWN-
151 SENT state or the SHUTDOWN-ACK-SENT state. Graceful ter‐
152 mination of the association.
153 SctpOutOfBlues
155 The number of out of the blue packets received by the
156 host. An out of the blue packet is an SCTP packet cor‐
157 rectly formed, including the proper checksum, but for
158 which the receiver was unable to identify an appropriate
159 association.
160 SctpChecksumErrors
162 The number of SCTP packets received with an invalid
163 checksum.
164 SctpOutCtrlChunks
166 The number of SCTP control chunks sent (retransmissions
167 are not included). Control chunks are those chunks dif‐
168 ferent from DATA.
169 SctpOutOrderChunks
171 The number of SCTP ordered data chunks sent (retransmis‐
172 sions are not included).
173 SctpOutUnorderChunks
175 The number of SCTP unordered chunks(data chunks in which
176 the U bit is set to 1) sent (retransmissions are not
177 included).
178 SctpInCtrlChunks
180 The number of SCTP control chunks received (no duplicate
181 chunks included).
182 SctpInOrderChunks
184 The number of SCTP ordered data chunks received (no
185 duplicate chunks included).
186 SctpInUnorderChunks
188 The number of SCTP unordered chunks(data chunks in which
189 the U bit is set to 1) received (no duplicate chunks
190 included).
191 SctpFragUsrMsgs
193 The number of user messages that have to be fragmented
194 because of the MTU.
195 SctpReasmUsrMsgs
197 The number of user messages reassembled, after conversion
198 into DATA chunks.
199 SctpOutSCTPPacks
201 The number of SCTP packets sent. Retransmitted DATA
202 chunks are included.
203 SctpInSCTPPacks
205 The number of SCTP packets received. Duplicates are
206 included.
207
209 To set or get a SCTP socket option, call getsockopt(2) to read
210 or setsockopt(2) to write the option with the option level argu‐
211 ment set to SOL_SCTP.
212 SCTP_RTOINFO.
214 This option is used to get or set the protocol parameters
215 used to initialize and bound retransmission timout(RTO).
216 The structure sctp_rtoinfo defined in
217 /usr/include/netinet/sctp.h is used to access and modify
218 these parameters.
219 SCTP_ASSOCINFO
221 This option is used to both examine and set various asso‐
222 ciation and endpoint parameters. The sturcture
223 sctp_assocparams defined in /usr/include/netinet/sctp.h
224 is used to access and modify these parameters.
225 SCTP_INITMSG
227 This option is used to get or set the protocol parameters
228 for the default association initialization. The structure
229 sctp_initmsg defined in /usr/include/netinet/sctp.h is
230 used to access and modify these parameters.
231 Setting initialization parameters is effective only on an
233 unconnected socket (for one-to-many style sockets only
234 future associations are effected by the change). With
235 one-to-one style sockets, this option is inherited by
236 sockets derived from a listener socket.
237 SCTP_NODELAY
239 Turn on/off any Nagle-like algorithm. This means that
240 packets are generally sent as soon as possible and no
241 unnecessary delays are introduced, at the cost of more
242 packets in the network. Expects an integer boolean flag.
243 SCTP_AUTOCLOSE
245 This socket option is applicable to the one-to-many style
246 socket only. When set it will cause associations that are
247 idle for more than the specified number of seconds to
248 automatically close. An association being idle is defined
249 an association that has NOT sent or received user data.
250 The special value of 0 indicates that no automatic close
251 of any associations should be performed. The option
252 expects an integer defining the number of seconds of idle
253 time before an association is closed.
254 SCTP_SET_PEER_PRIMARY_ADDR
256 Requests that the peer mark the enclosed address as the
257 association primary. The enclosed address must be one of
258 the association's locally bound addresses. The structure
259 sctp_setpeerprim defined in /usr/include/netinet/sctp.h
260 is used to make a set peer primary request.
261 SCTP_PRIMARY_ADDR
263 Requests that the local SCTP stack use the enclosed peer
264 address as the association primary. The enclosed address
265 must be one of the association peer's addresses. The
266 structure sctp_prim defined in
267 /usr/include/netinet/sctp.h is used to make a get/set
268 primary request.
269 SCTP_DISABLE_FRAGMENTS
271 This option is a on/off flag and is passed an integer
272 where a non-zero is on and a zero is off. If enabled no
273 SCTP message fragmentation will be performed. Instead if
274 a message being sent exceeds the current PMTU size, the
275 message will NOT be sent and an error will be indicated
276 to the user.
277 SCTP_PEER_ADDR_PARAMS
279 Using this option, applications can enable or disable
280 heartbeats for any peer address of an association, modify
281 an address's heartbeat interval, force a heartbeat to be
282 sent immediately, and adjust the address's maximum number
283 of retransmissions sent before an address is considered
284 unreachable. The structure sctp_paddrparams defined in
285 /usr/include/netinet/sctp.h is used to access and modify
286 an address's parameters.
287 SCTP_DEFAULT_SEND_PARAM
289 Applications that wish to use the sendto() system call
290 may wish to specify a default set of parameters that
291 would normally be supplied through the inclusion of
292 ancillary data. This socket option allows such an appli‐
293 cation to set the default sctp_sndrcvinfo structure. The
294 application that wishes to use this socket option simply
295 passes in to this call the sctp_sndrcvinfo structure
296 defined in /usr/include/netinet/sctp.h. The input parame‐
297 ters accepted by this call include sinfo_stream,
298 sinfo_flags, sinfo_ppid, sinfo_context, sinfo_timetolive.
299 The user must set the sinfo_assoc_id field to identify
300 the
301 association to affect if the caller is using the one-to-
302 many style.
303 SCTP_EVENTS
305 This socket option is used to specify various notifica‐
306 tions and ancillary data the user wishes to receive. The
307 structure sctp_event_subscribe defined in
308 /usr/include/netinet/sctp.h is used to access or modify
309 the events of interest to the user.
310 SCTP_I_WANT_MAPPED_V4_ADDR
312 This socket option is a boolean flag which turns on or
313 off mapped V4 addresses. If this option is turned on and
314 the socket is type PF_INET6, then IPv4 addresses will be
315 mapped to V6 representation. If this option is turned
316 off, then no mapping will be done of V4 addresses and a
317 user will receive both PF_INET6 and PF_INET type
318 addresses on the socket.
319 By default this option is turned on and expects an inte‐
321 ger to be passed where non-zero turns on the option and
322 zero turns off the option.
323 SCTP_MAXSEG
325 This socket option specifies the maximum size to put in
326 any outgoing SCTP DATA chunk. If a message is larger than
327 this size it will be fragmented by SCTP into the speci‐
328 fied size. Note that the underlying SCTP implementation
329 may fragment into smaller sized chunks when the PMTU of
330 the underlying association is smaller than the value set
331 by the user. The option expects an integer.
332 The default value for this option is 0 which indicates
334 the user is NOT limiting fragmentation and only the PMTU
335 will effect SCTP's choice of DATA chunk size.
336 SCTP_STATUS
338 Applications can retrieve current status information
339 about an association, including association state, peer
340 receiver window size, number of unacked data chunks, and
341 number of data chunks pending receipt. This information
342 is read-only. The structure sctp_status defined in
343 /usr/include/netinet/sctp.h is used to access this infor‐
344 mation.
345 SCTP_GET_PEER_ADDR_INFO
347 Applications can retrieve information about a specific
348 peer address of an association, including its reachabil‐
349 ity state, congestion window, and retransmission timer
350 values. This information is read-only. The structure
351 sctp_paddr_info defined in /usr/include/netinet/sctp.h is
352 used to access this information.
353 SCTP_GET_ASSOC_STATS
355 Applications can retrieve current statistics about an
356 association, including SACKs sent and received, SCTP
357 packets sent and received. The complete list can be found
358 in /usr/include/netinet/sctp.h in struct
359 sctp_assoc_stats.
360
362 Sridhar Samudrala <sri@us.ibm.com>
363
365 socket(7), socket(2), ip(7), bind(2), listen(2), accept(2), con‐
366 nect(2), sendmsg(2), recvmsg(2), sysctl(2), getsockopt(2),
367 sctp_bindx(3), sctp_connectx(3), sctp_sendmsg(3), sctp_sendv(3),
368 sctp_send(3), sctp_recvmsg(3), sctp_recvv(3), sctp_peeloff(3),
369 sctp_getladdrs(3), sctp_getpaddrs(3), sctp_opt_info(3).
370 RFC2960, RFC3309 for the SCTP specification.
372Linux Man Page 2005-10-25 SCTP(7)