1SCTP(7)                    Linux Programmer's Manual                   SCTP(7)
2
3
4

NAME

6       sctp - SCTP protocol.
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <netinet/in.h>
11       #include <netinet/sctp.h>
12
13       sctp_socket = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
14       sctp_socket = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
15

DESCRIPTION

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
22       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
30       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
34       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
38       sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);
39
40       A typical server in this style  uses  the  following  socket  calls  in
41       sequence to prepare an endpoint for servicing requests.
42
43            1. socket()
44            2. bind()
45            3. listen()
46            4. recvmsg()
47            5. sendmsg()
48            6. close()
49
50       A typical client uses the following calls in sequence to setup an asso‐
51       ciation with a server to request services.
52
53            1. socket()
54            2. sendmsg()
55            3. recvmsg()
56            4. close()
57
58       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
63       sd = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
64
65       A  typical  server  in  one-to-one style uses the following system call
66       sequence to prepare an SCTP endpoint for servicing requests:
67
68            1. socket()
69            2. bind()
70            3. listen()
71            4. accept()
72
73       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
78            5. close()
79
80       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
84            1. socket()
85            2. connect()
86
87       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
91            3. close()
92
93       to terminate this association when done.
94

ADDRESS FORMATS

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

SYSCTLS

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
105       addip_enable
106              Enable SCTP ADDIP(Dynamic Address Reconfiguration) Support. This
107              is off by default.
108
109       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
114       cookie_preserve_enable
115              Handle COOKIE PRESERVATIVE parameter in the INIT chunk. This  is
116              on by default.
117
118       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
124       max_burst
125              Maximum number of new data packets that can be sent in a  burst.
126              The default value is 4.
127
128       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
133       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
138       prsctp_enable
139              Enable PR-SCTP. This is on by default.
140
141       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
148       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
152       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
156       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
161       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
166       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
171       sack_timeout
172              Delayed SACK timeout. The default value is 200msecs.
173
174       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
180       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

STATISTICS

185       These variables can be accessed by the /proc/net/sctp/* files.
186
187       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
193       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
197       snmp   Displays  the following statistics related to SCTP states, pack‐
198              ets and chunks.
199
200
201       SctpCurrEstab
202              The number of associations for which the current state is
203              either  ESTABLISHED,  SHUTDOWN-RECEIVED or SHUTDOWN-PEND‐
204              ING.
205
206       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
212       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
218       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
224       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
230       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
237       SctpChecksumErrors
238              The number of  SCTP  packets  received  with  an  invalid
239              checksum.
240
241       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
246       SctpOutOrderChunks
247              The  number of SCTP ordered data chunks sent (retransmis‐
248              sions are not included).
249
250       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
255       SctpInCtrlChunks
256              The number of SCTP control chunks received (no  duplicate
257              chunks included).
258
259       SctpInOrderChunks
260              The  number  of  SCTP  ordered  data  chunks received (no
261              duplicate chunks included).
262
263       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
268       SctpFragUsrMsgs
269              The number of user messages that have  to  be  fragmented
270              because of the MTU.
271
272       SctpReasmUsrMsgs
273              The number of user messages reassembled, after conversion
274              into DATA chunks.
275
276       SctpOutSCTPPacks
277              The number  of  SCTP  packets  sent.  Retransmitted  DATA
278              chunks are included.
279
280       SctpInSCTPPacks
281              The  number  of  SCTP  packets  received.  Duplicates are
282              included.
283

SOCKET OPTIONS

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
289       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
296       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
302       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
308              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
314       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
320       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
331       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
338       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
346       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
354       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
364       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
380       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
387       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
396              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
400       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
409              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
413       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
422       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
430       SCTP_GET_ASSOC_STATS
431              Applications  can  retrieve  current  statistics about an
432              association, including  SACKs  sent  and  received,  SCTP
433              packets sent and received. The complete list can be found
434              in      /usr/include/netinet/sctp.h       in       struct
435              sctp_assoc_stats.
436

AUTHORS

438       Sridhar Samudrala <sri@us.ibm.com>
439

SEE ALSO

441       socket(7), socket(2), ip(7), bind(2), listen(2), accept(2), con‐
442       nect(2),  sendmsg(2),  recvmsg(2),   sysctl(2),   getsockopt(2),
443       sctp_bindx(3),  sctp_connectx(3), sctp_sendmsg(3), sctp_send(3),
444       sctp_recvmsg(3), sctp_peeloff(3),  sctp_getladdrs(3),  sctp_get‐
445       paddrs(3), sctp_opt_info(3).
446
447       RFC2960, RFC3309 for the SCTP specification.
448
449
450
451Linux Man Page                    2005-10-25                           SCTP(7)
Impressum