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 de‐
31 fined in the draft-ietf-tsvwg-sctpsocket-10.txt(Sockets API extensions
32 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 im‐
36 plicit. 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 se‐
41 quence 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 se‐
66 quence 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 de‐
75 scriptor to communicate with the client, using recv() and send() calls
76 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, re‐
115 mote 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 either
127 ESTABLISHED, SHUTDOWN-RECEIVED or SHUTDOWN-PENDING.
128 SctpActiveEstabs
130 The number of times that associations have made a direct transi‐
131 tion to the ESTABLISHED state from the COOKIE-ECHOED state. The
132 upper layer initiated the association attempt.
133 SctpPassiveEstabs
135 The number of times that associations have made a direct transi‐
136 tion to the ESTABLISHED state from the CLOSED state. The remote
137 endpoint initiated the association attempt.
138 SctpAborteds
140 The number of times that associations have made a direct transi‐
141 tion to the CLOSED state from any state using the primitive
142 'ABORT'. Ungraceful termination of the association.
143 SctpShutdowns
145 The number of times that associations have made a direct transi‐
146 tion to the CLOSED state from either the SHUTDOWN-SENT state or
147 the SHUTDOWN-ACK-SENT state. Graceful termination of the associ‐
148 ation.
149 SctpOutOfBlues
151 The number of out of the blue packets received by the host. An
152 out of the blue packet is an SCTP packet correctly formed, in‐
153 cluding the proper checksum, but for which the receiver was un‐
154 able to identify an appropriate association.
155 SctpChecksumErrors
157 The number of SCTP packets received with an invalid checksum.
158 SctpOutCtrlChunks
160 The number of SCTP control chunks sent (retransmissions are not
161 included). Control chunks are those chunks different from DATA.
162 SctpOutOrderChunks
164 The number of SCTP ordered data chunks sent (retransmissions are
165 not included).
166 SctpOutUnorderChunks
168 The number of SCTP unordered chunks(data chunks in which the U
169 bit is set to 1) sent (retransmissions are not included).
170 SctpInCtrlChunks
172 The number of SCTP control chunks received (no duplicate chunks
173 included).
174 SctpInOrderChunks
176 The number of SCTP ordered data chunks received (no duplicate
177 chunks included).
178 SctpInUnorderChunks
180 The number of SCTP unordered chunks(data chunks in which the U
181 bit is set to 1) received (no duplicate chunks included).
182 SctpFragUsrMsgs
184 The number of user messages that have to be fragmented because
185 of the MTU.
186 SctpReasmUsrMsgs
188 The number of user messages reassembled, after conversion into
189 DATA chunks.
190 SctpOutSCTPPacks
192 The number of SCTP packets sent. Retransmitted DATA chunks are
193 included.
194 SctpInSCTPPacks
196 The number of SCTP packets received. Duplicates are included.
197
199 To set or get a SCTP socket option, call getsockopt(2) to read or set‐
200 sockopt(2) to write the option with the option level argument set to
201 SOL_SCTP.
202 SCTP_RTOINFO.
204 This option is used to get or set the protocol parameters used
205 to initialize and bound retransmission timeout(RTO). The struc‐
206 ture sctp_rtoinfo defined in /usr/include/netinet/sctp.h is used
207 to access and modify these parameters.
208 SCTP_ASSOCINFO
210 This option is used to both examine and set various association
211 and endpoint parameters. The structure sctp_assocparams defined
212 in /usr/include/netinet/sctp.h is used to access and modify
213 these parameters.
214 SCTP_INITMSG
216 This option is used to get or set the protocol parameters for
217 the default association initialization. The structure
218 sctp_initmsg defined in /usr/include/netinet/sctp.h is used to
219 access and modify these parameters.
220 Setting initialization parameters is effective only on an uncon‐
222 nected socket (for one-to-many style sockets only future associ‐
223 ations are effected by the change). With one-to-one style sock‐
224 ets, this option is inherited by sockets derived from a listener
225 socket.
226 SCTP_NODELAY
228 Turn on/off any Nagle-like algorithm. This means that packets
229 are generally sent as soon as possible and no unnecessary delays
230 are introduced, at the cost of more packets in the network. Ex‐
231 pects an integer boolean flag.
232 SCTP_AUTOCLOSE
234 This socket option is applicable to the one-to-many style socket
235 only. When set it will cause associations that are idle for more
236 than the specified number of seconds to automatically close. An
237 association being idle is defined an association that has NOT
238 sent or received user data. The special value of 0 indicates
239 that no automatic close of any associations should be performed.
240 The option expects an integer defining the number of seconds of
241 idle time before an association is closed.
242 SCTP_SET_PEER_PRIMARY_ADDR
244 Requests that the peer mark the enclosed address as the associa‐
245 tion primary. The enclosed address must be one of the associa‐
246 tion's locally bound addresses. The structure sctp_setpeerprim
247 defined in /usr/include/netinet/sctp.h is used to make a set
248 peer primary request.
249 SCTP_PRIMARY_ADDR
251 Requests that the local SCTP stack use the enclosed peer address
252 as the association primary. The enclosed address must be one of
253 the association peer's addresses. The structure sctp_prim de‐
254 fined in /usr/include/netinet/sctp.h is used to make a get/set
255 primary request.
256 SCTP_DISABLE_FRAGMENTS
258 This option is a on/off flag and is passed an integer where a
259 non-zero is on and a zero is off. If enabled no SCTP message
260 fragmentation will be performed. Instead if a message being
261 sent exceeds the current PMTU size, the message will NOT be sent
262 and an error will be indicated to the user.
263 SCTP_PEER_ADDR_PARAMS
265 Using this option, applications can enable or disable heartbeats
266 for any peer address of an association, modify an address's
267 heartbeat interval, force a heartbeat to be sent immediately,
268 and adjust the address's maximum number of retransmissions sent
269 before an address is considered unreachable. The structure
270 sctp_paddrparams defined in /usr/include/netinet/sctp.h is used
271 to access and modify an address's parameters.
272 SCTP_DEFAULT_SEND_PARAM
274 Applications that wish to use the sendto() system call may wish
275 to specify a default set of parameters that would normally be
276 supplied through the inclusion of ancillary data. This socket
277 option allows such an application to set the default sctp_sndr‐
278 cvinfo structure. The application that wishes to use this socket
279 option simply passes in to this call the sctp_sndrcvinfo struc‐
280 ture defined in /usr/include/netinet/sctp.h. The input parame‐
281 ters accepted by this call include sinfo_stream, sinfo_flags,
282 sinfo_ppid, sinfo_context, sinfo_timetolive. The user must set
283 the sinfo_assoc_id field to identify the association to affect
284 if the caller is using the one-to-many style.
285 SCTP_EVENTS
287 This socket option is used to specify various notifications and
288 ancillary data the user wishes to receive. The structure
289 sctp_event_subscribe defined in /usr/include/netinet/sctp.h is
290 used to access or modify the events of interest to the user.
291 SCTP_I_WANT_MAPPED_V4_ADDR
293 This socket option is a boolean flag which turns on or off
294 mapped V4 addresses. If this option is turned on and the socket
295 is type PF_INET6, then IPv4 addresses will be mapped to V6 rep‐
296 resentation. If this option is turned off, then no mapping will
297 be done of V4 addresses and a user will receive both PF_INET6
298 and PF_INET type addresses on the socket.
299 By default this option is turned on and expects an integer to be
301 passed where non-zero turns on the option and zero turns off the
302 option.
303 SCTP_MAXSEG
305 This socket option specifies the maximum size to put in any out‐
306 going SCTP DATA chunk. If a message is larger than this size it
307 will be fragmented by SCTP into the specified size. Note that
308 the underlying SCTP implementation may fragment into smaller
309 sized chunks when the PMTU of the underlying association is
310 smaller than the value set by the user. The option expects an
311 integer.
312 The default value for this option is 0 which indicates the user
314 is NOT limiting fragmentation and only the PMTU will effect
315 SCTP's choice of DATA chunk size.
316 SCTP_STATUS
318 Applications can retrieve current status information about an
319 association, including association state, peer receiver window
320 size, number of unacked data chunks, and number of data chunks
321 pending receipt. This information is read-only. The structure
322 sctp_status defined in /usr/include/netinet/sctp.h is used to
323 access this information.
324 SCTP_GET_PEER_ADDR_INFO
326 Applications can retrieve information about a specific peer ad‐
327 dress of an association, including its reachability state, con‐
328 gestion window, and retransmission timer values. This informa‐
329 tion is read-only. The structure sctp_paddrinfo defined in
330 /usr/include/netinet/sctp.h is used to access this information.
331 SCTP_GET_ASSOC_STATS
333 Applications can retrieve current statistics about an associa‐
334 tion, including SACKs sent and received, SCTP packets sent and
335 received. The complete list can be found in /usr/in‐
336 clude/netinet/sctp.h in struct sctp_assoc_stats.
337
339 Sridhar Samudrala <sri@us.ibm.com>
340
342 socket(7), socket(2), ip(7), bind(2), listen(2), accept(2), connect(2),
343 sendmsg(2), recvmsg(2), sysctl(2), getsockopt(2), sctp_bindx(3),
344 sctp_connectx(3), sctp_sendmsg(3), sctp_sendv(3), sctp_send(3),
345 sctp_recvmsg(3), sctp_recvv(3), sctp_peeloff(3), sctp_getladdrs(3),
346 sctp_getpaddrs(3), sctp_opt_info(3).
347 RFC2960, RFC3309 for the SCTP specification.
349Linux Man Page 2005-10-25 SCTP(7)