sctp

SCTP(7)                    Linux Programmer's Manual                   SCTP(7)

NAME
       sctp - SCTP protocol.

SYNOPSIS
       #include <sys/socket.h>
       #include <netinet/in.h>
       #include <netinet/sctp.h>

       sctp_socket = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);
       sctp_socket = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);

DESCRIPTION
       This  is  an  implementation of the SCTP protocol as defined in RFC2960
       and RFC3309. It is a message oriented, reliable transport protocol with
       direct  support for multihoming that runs on top of ip(7), and supports
       both v4 and v6 versions.

       Like TCP, SCTP provides reliable,  connection  oriented  data  delivery
       with  congestion control. Unlike TCP, SCTP also provides message bound-
       ary preservation, ordered and unordered message delivery, multi-stream-
       ing  and  multi-homing.  Detection of data corruption, loss of data and
       duplication of data is achieved by using checksums  and  sequence  num-
       bers.  A  selective retransmission mechanism is applied to correct loss
       or corruption of data.

       This implementation supports a mapping of  SCTP  into  sockets  API  as
       defined  in  the  draft-ietf-tsvwg-sctpsocket-10.txt(Sockets API exten-
       sions for SCTP).  Two styles of interfaces are supported.

       A one-to-many style interface  with  1  to  MANY  relationship  between
       socket  and  associations  where  the  outbound  association  setup  is
       implicit. The syntax of a one-to-many style socket() call is

       sd = socket(PF_INET, SOCK_SEQPACKET, IPPROTO_SCTP);

       A typical server in this style  uses  the  following  socket  calls  in
       sequence to prepare an endpoint for servicing requests.

            1. socket()
            2. bind()
            3. listen()
            4. recvmsg()
            5. sendmsg()
            6. close()

       A typical client uses the following calls in sequence to setup an asso-
       ciation with a server to request services.

            1. socket()
            2. sendmsg()
            3. recvmsg()
            4. close()

       A one-to-one style interface with a 1 to 1 relationship between  socket
       and association which enables existing TCP applications to be ported to
       SCTP with very little effort. The syntax of a one-to-one style socket()
       call is

       sd = socket(PF_INET, SOCK_STREAM, IPPROTO_SCTP);

       A  typical  server  in  one-to-one style uses the following system call
       sequence to prepare an SCTP endpoint for servicing requests:

            1. socket()
            2. bind()
            3. listen()
            4. accept()

       The accept() call blocks until a new association is set up. It  returns
       with  a  new  socket  descriptor.  The  server then uses the new socket
       descriptor to communicate with the  client,  using  recv()  and  send()
       calls to get requests and send back responses. Then it calls

            5. close()

       to  terminate the association. A typical client uses the following sys-
       tem call sequence to setup an association with a server to request ser-
       vices:

            1. socket()
            2. connect()

       After returning from connect(), the client uses send() and recv() calls
       to send out requests and receive responses from the server. The  client
       calls

            3. close()

       to terminate this association when done.

ADDRESS FORMATS
       SCTP is built on top of IP (see ip(7)).  The address formats defined by
       ip(7) apply to SCTP.  SCTP only supports point-to-point  communication;
       broadcasting and multicasting are not supported.

SYSCTLS
       These  variables  can  be accessed by the /proc/sys/net/sctp/* files or
       with the sysctl(2) interface.  In addition, most IP sysctls also  apply
       to SCTP. See ip(7).

       addip_enable
              Enable SCTP ADDIP(Dynamic Address Reconfiguration) Support. This
              is off by default.

       association_max_retrans
              Maximum number of consecutive retransmissions to a  peer  before
              an  endpoint  considers  that the peer is unreachable and closes
              the association. The default value is 10.

       cookie_preserve_enable
              Handle COOKIE PRESERVATIVE parameter in the INIT chunk. This  is
              on by default.

       hb_interval
              This  is the interval when a HEARTBEAT chunk is sent to a desti-
              nation transport address to monitor the reachability of an  idle
              destination transport address.  The default is 30 seconds and is
              maintained in msecs.

       max_burst
              Maximum number of new data packets that can be sent in a  burst.
              The default value is 4.

       max_init_retransmits
              Maximum  number of times an INIT chunk or a COOKIE ECHO chunk is
              retransmitted  before  an  endpoint  aborts  the  initialization
              process and closes the association.  The default value is 8.

       path_max_retrans
              Maximum number of consecutive retransmissions over a destination
              transport address of a peer endpoint  before  it  is  marked  as
              inactive. The default value is 5.

       prsctp_enable
              Enable PR-SCTP. This is on by default.

       rcvbuf_policy
              This  controls  the socket receive buffer accounting policy. The
              default value is 0  and  indicates  that  all  the  associations
              belonging  to a socket share the same receive buffer space. When
              set to 1, each association will  have  its  own  receive  buffer
              space.

       rto_alpha_exp_divisor
              This  is  the RTO.Alpha value when expressed in right shifts and
              is used in RTO calculations. The default value is 3.

       rto_beta_exp_divisor
              This is the RTO.Beta value when expressed in right shifts and is
              used in RTO calculations. The default value is 2.

       rto_initial
              This is the initial value of RTO(retransmission timeout) that is
              used in RTO calculations. The default value is 3 seconds and  is
              maintained in msecs.

       rto_max
              This is the maximum value of RTO(retransmission timeout) that is
              used in RTO calculations. The default value is 60 seconds and is
              maintained in msecs.

       rto_min
              This is the minimum value of RTO(retransmission timeout) that is
              used in RTO calculations. The default value is 1 second  and  is
              maintained in msecs.

       sack_timeout
              Delayed SACK timeout. The default value is 200msecs.

       sndbuf_policy
              This  controls  the  socket  sendbuffer  accounting  policy. The
              default value is 0  and  indicates  that  all  the  associations
              belonging to a socket share the same send buffer space. When set
              to 1, each association will have its own send buffer space.

       valid_cookie_life
              This is the maximum lifespan of the Cookie sent in an  INIT  ACK
              chunk. The default value is 60 secs and is maintained in msecs.

STATISTICS
       These variables can be accessed by the /proc/net/sctp/* files.

       assocs Displays  the  following  information  about the active associa-
              tions.  assoc ptr, sock ptr, socket style, sock state,  associa-
              tion  state,  hash  bucket,  association  id,  bytes in transmit
              queue, bytes in receive  queue,  user  id,  inode,  local  port,
              remote port, local addresses and remote addresses.

       eps    Displays  the  following information about the active endpoints.
              endpoint ptr, sock ptr, socket style, sock state,  hash  bucket,
              local port, user id, inode and local addresses.

       snmp   Displays  the following statistics related to SCTP states, pack-
              ets and chunks.

       SctpCurrEstab
              The number of associations for which the current state is either
              ESTABLISHED, SHUTDOWN-RECEIVED or SHUTDOWN-PENDING.

       SctpActiveEstabs
              The number of times that associations have made a direct transi-
              tion to the ESTABLISHED state from the COOKIE-ECHOED state.  The
              upper layer initiated the association attempt.

       SctpPassiveEstabs
              The number of times that associations have made a direct transi-
              tion to the ESTABLISHED state from the CLOSED state. The  remote
              endpoint initiated the association attempt.

       SctpAborteds
              The number of times that associations have made a direct transi-
              tion to the CLOSED state from  any  state  using  the  primitive
              'ABORT'. Ungraceful termination of the association.

       SctpShutdowns
              The number of times that associations have made a direct transi-
              tion to the CLOSED state from either the SHUTDOWN-SENT state  or
              the SHUTDOWN-ACK-SENT state. Graceful termination of the associ-
              ation.

       SctpOutOfBlues
              The number of out of the blue packets received by the  host.  An
              out  of  the  blue  packet  is  an SCTP packet correctly formed,
              including the proper checksum, but for which  the  receiver  was
              unable to identify an appropriate association.

       SctpChecksumErrors
              The number of SCTP packets received with an invalid checksum.

       SctpOutCtrlChunks
              The  number of SCTP control chunks sent (retransmissions are not
              included).  Control chunks are those chunks different from DATA.

       SctpOutOrderChunks
              The number of SCTP ordered data chunks sent (retransmissions are
              not included).

       SctpOutUnorderChunks
              The  number  of SCTP unordered chunks(data chunks in which the U
              bit is set to 1) sent (retransmissions are not included).

       SctpInCtrlChunks
              The number of SCTP control chunks received (no duplicate  chunks
              included).

       SctpInOrderChunks
              The  number  of  SCTP ordered data chunks received (no duplicate
              chunks included).

       SctpInUnorderChunks
              The number of SCTP unordered chunks(data chunks in which  the  U
              bit is set to 1) received (no duplicate chunks included).

       SctpFragUsrMsgs
              The  number  of user messages that have to be fragmented because
              of the MTU.

       SctpReasmUsrMsgs
              The number of user messages reassembled, after  conversion  into
              DATA chunks.

       SctpOutSCTPPacks
              The  number  of SCTP packets sent. Retransmitted DATA chunks are
              included.

       SctpInSCTPPacks
              The number of SCTP packets received. Duplicates are included.

SOCKET OPTIONS
       To set or get a SCTP socket option, call getsockopt(2) to read or  set-
       sockopt(2)  to  write  the option with the option level argument set to
       SOL_SCTP.

       SCTP_RTOINFO.
              This option is used to get or set the protocol  parameters  used
              to  initialize  and bound retransmission timout(RTO). The struc-
              ture sctp_rtoinfo defined in /usr/include/netinet/sctp.h is used
              to access and modify these parameters.

       SCTP_ASSOCINFO
              This  option is used to both examine and set various association
              and endpoint parameters. The sturcture sctp_assocparams  defined
              in  /usr/include/netinet/sctp.h  is  used  to  access and modify
              these parameters.

       SCTP_INITMSG
              This option is used to get or set the  protocol  parameters  for
              the    default   association   initialization.   The   structure
              sctp_initmsg defined in /usr/include/netinet/sctp.h is  used  to
              access and modify these parameters.

              Setting initialization parameters is effective only on an uncon-
              nected socket (for one-to-many style sockets only future associ-
              ations  are effected by the change). With one-to-one style sock-
              ets, this option is inherited by sockets derived from a listener
              socket.

       SCTP_NODELAY
              Turn  on/off  any  Nagle-like algorithm. This means that packets
              are generally sent as soon as possible and no unnecessary delays
              are  introduced,  at  the  cost  of more packets in the network.
              Expects an integer boolean flag.

       SCTP_AUTOCLOSE
              This socket option is applicable to the one-to-many style socket
              only. When set it will cause associations that are idle for more
              than the specified number of seconds to automatically close.  An
              association  being  idle  is defined an association that has NOT
              sent or received user data. The special  value  of  0  indicates
              that no automatic close of any associations should be performed.
              The option expects an integer defining the number of seconds  of
              idle time before an association is closed.

       SCTP_SET_PEER_PRIMARY_ADDR
              Requests that the peer mark the enclosed address as the associa-
              tion primary. The enclosed address must be one of  the  associa-
              tion's  locally  bound addresses. The structure sctp_setpeerprim
              defined in /usr/include/netinet/sctp.h is used  to  make  a  set
              peer primary request.

       SCTP_PRIMARY_ADDR
              Requests that the local SCTP stack use the enclosed peer address
              as the association primary. The enclosed address must be one  of
              the   association  peer's  addresses.  The  structure  sctp_prim
              defined in /usr/include/netinet/sctp.h is used to make a get/set
              primary request.

       SCTP_DISABLE_FRAGMENTS
              This  option  is  a on/off flag and is passed an integer where a
              non-zero is on and a zero is off. If  enabled  no  SCTP  message
              fragmentation  will  be  performed.   Instead if a message being
              sent exceeds the current PMTU size, the message will NOT be sent
              and an error will be indicated to the user.

       SCTP_PEER_ADDR_PARAMS
              Using this option, applications can enable or disable heartbeats
              for any peer address of  an  association,  modify  an  address's
              heartbeat  interval,  force  a heartbeat to be sent immediately,
              and adjust the address's maximum number of retransmissions  sent
              before  an  address  is  considered  unreachable.  The structure
              sctp_paddrparams defined in /usr/include/netinet/sctp.h is  used
              to access and modify an address's parameters.

       SCTP_DEFAULT_SEND_PARAM
              Applications  that wish to use the sendto() system call may wish
              to specify a default set of parameters that  would  normally  be
              supplied  through  the  inclusion of ancillary data. This socket
              option allows such an application to set the default  sctp_sndr-
              cvinfo structure. The application that wishes to use this socket
              option simply passes in to this call the sctp_sndrcvinfo  struc-
              ture  defined  in /usr/include/netinet/sctp.h. The input parame-
              ters accepted by this call  include  sinfo_stream,  sinfo_flags,
              sinfo_ppid,  sinfo_context,  sinfo_timetolive. The user must set
              the sinfo_assoc_id field to identify the
               association to affect if the caller is  using  the  one-to-many
              style.

       SCTP_EVENTS
              This  socket option is used to specify various notifications and
              ancillary  data  the  user  wishes  to  receive.  The  structure
              sctp_event_subscribe  defined  in /usr/include/netinet/sctp.h is
              used to access or modify the events of interest to the user.

       SCTP_I_WANT_MAPPED_V4_ADDR
              This socket option is a boolean  flag  which  turns  on  or  off
              mapped  V4 addresses. If this option is turned on and the socket
              is type PF_INET6, then IPv4 addresses will be mapped to V6  rep-
              resentation.  If this option is turned off, then no mapping will
              be done of V4 addresses and a user will  receive  both  PF_INET6
              and PF_INET type addresses on the socket.

              By default this option is turned on and expects an integer to be
              passed where non-zero turns on the option and zero turns off the
              option.

       SCTP_MAXSEG
              This socket option specifies the maximum size to put in any out-
              going SCTP DATA chunk. If a message is larger than this size  it
              will  be  fragmented  by SCTP into the specified size. Note that
              the underlying SCTP implementation  may  fragment  into  smaller
              sized  chunks  when  the  PMTU  of the underlying association is
              smaller than the value set by the user. The  option  expects  an
              integer.

              The  default value for this option is 0 which indicates the user
              is NOT limiting fragmentation and  only  the  PMTU  will  effect
              SCTP's choice of DATA chunk size.

       SCTP_STATUS
              Applications  can  retrieve  current status information about an
              association, including association state, peer  receiver  window
              size,  number  of unacked data chunks, and number of data chunks
              pending receipt.  This information is read-only.  The  structure
              sctp_status  defined  in  /usr/include/netinet/sctp.h is used to
              access this information.

       SCTP_GET_PEER_ADDR_INFO
              Applications can retrieve  information  about  a  specific  peer
              address  of  an  association,  including its reachability state,
              congestion window, and retransmission timer values.  This infor-
              mation  is  read-only.  The structure sctp_paddr_info defined in
              /usr/include/netinet/sctp.h is used to access this information.

       SCTP_GET_ASSOC_STATS
              Applications can retrieve current statistics about  an  associa-
              tion,  including  SACKs sent and received, SCTP packets sent and
              received.    The    complete    list    can    be    found    in
              /usr/include/netinet/sctp.h in struct sctp_assoc_stats.

AUTHORS
       Sridhar Samudrala <sri@us.ibm.com>

SEE ALSO
       socket(7), socket(2), ip(7), bind(2), listen(2), accept(2), connect(2),
       sendmsg(2),  recvmsg(2),   sysctl(2),   getsockopt(2),   sctp_bindx(3),
       sctp_connectx(3),   sctp_sendmsg(3),   sctp_send(3),   sctp_recvmsg(3),
       sctp_peeloff(3),         sctp_getladdrs(3),          sctp_getpaddrs(3),
       sctp_opt_info(3).

       RFC2960, RFC3309 for the SCTP specification.

Linux Man Page                    2005-10-25                           SCTP(7)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2021 Hurricane Electric. All Rights Reserved.