ACE/performance-tests/SCTP/README.SCTP_in_ACE

   1 Release 1.1 - June 2003
   2
   3 Overview of SCTP sockets
   4 ------------------------
   5
   6 In order to support multiple implementations of SCTP, we had to standardize
   7 on a set of semantics.
   8
   9 The IETF sockets draft states that service type SOCK_SEQPACKET indicates a UDP
  10 style socket (i.e. connection-less), while service type SOCK_STREAM indicates
  11 a TCP style socket.  However, this conflicts with the POSIX definition for
  12 SOCK_SEQPACKET as connection-oriented.
  13
  14 In ACE we choose to support the standard POSIX definition. In doing so, certain
  15 socket semantics will be guaranteed regardless of implementation.
  16
  17         [1] SOCK_SEQPACKET sockets will always be message-based,
  18             connection-oriented, and reliable.
  19
  20         [2] SOCK_STREAM sockets will be message-based or byte-stream based,
  21             connection-oriented, and reliable.
  22
  23
  24 SCTP Features Accessible Within ACE
  25 -----------------------------------
  26
  27  * SOCK_STREAM (byte stream oriented or msg oriented) data transport service
  28
  29  * SOCK_SEQPACKET (message oriented) data transport service (this is
  30    the service used by TAO's SCIOP pluggable protocol)
  31
  32  * Explicit control of binding network interfaces (all, one, or any
  33    subset) to server-side passive- and active- mode sockets on
  34    multi-homed machines. (for SOCK_SEQPACKET service only.  The
  35    SOCK_STREAM service may only bind one or all interfaces because we
  36    avoided changing the interface of ACE_SOCK_Acceptor.)
  37
  38  * Setting and getting of all parameters exposed by SCTP
  39    (e.g. retransmission timeout (RTO)) via ACE_SOCK::set_option(...)
  40    and ACE_SOCK::get_option(...) for both SOCK_STREAM and
  41    SOCK_SEQPACKET sockets.  You must set the socket level appropriately.
  42
  43  * Multiplexing of lightweight "SCTP Streams" (over the SOCK_STREAM
  44    and SOCK_SEQPACKET services) via ACE_SOCK::set_option(...)
  45
  46  * Network path multiplexing (provided opaquely by the protocol---no
  47    explicit support required in ACE other than the ability to
  48    configure various parameters and the set of interfaces as described
  49    above)
  50
  51
  52 Supported SCTP Implementations
  53 ------------------------------
  54
  55  * OpenSS7's Linux Implementation (Berkeley UNIX Network API)
  56    Linux 2.4.18 patch available at: http://www.openss7.org/linux-sctp-0.2.14.tgz
  57    (as of April 2003)
  58
  59  * The LKSCTP Linux Kernel Implementation (IETF Sockets Draft API compliant)
  60    Available in the Linux 2.5 kernels (http://www.kernel.org/)
  61    Tools/Libs available at http://lksctp.sourceforge.net/
  62      (All socket interfaces are message-based -- please see README.LKSCTP)
  63
  64
  65 BUGS
  66 ----
  67
  68  * OpenSS7 BUGS
  69
  70     - protocol crashes when transmitting message sizes greater than
  71       PATH MTU in the presence of network failures (message size
  72       includes SCTP and IP headers and data.)
  73
  74  * LKSCTP BUGS
  75
  76     - certain combinations of SCTP parameters will cause a kernel panic
  77       (ie. setting rto_initial, rto_max, or rto_min to 0)
  78
  79
  80 TO-DO
  81 ----
  82
  83  * Provide explicit control of binding network interfaces to
  84    client-side active-mode sockets on multi-homed machines. Current
  85    implementation supports all interfaces but not restriction to one
  86    or to an arbitrary subset. (This will be done for SOCK_SEQPACKET
  87    service only. We want to avoid changing the existing interfaces for
  88    the SOCK_STREAM service).
  89
  90  * Integrate management and use of "SCTP Streams" into the
  91    ACE_SOCK_SEQPACK_* wrapper-facade. (currently they can only be
  92    accessed indirectly through ACE_SOCK::set_option(...))
  93
  94  * Support SOCK_RDM service (connection-less) within ACE for OpenSS7.
  95
  96  * Convert ATL's histogram utility (located under
  97    performance-tests/SCTP) into a ACE utility and integrate with other
  98    ACE provided statistics classes.
  99
 100  * Support Draft API msg notifications via sendmsg() and recvmsg().
 101
 102
 103 USAGE
 104 -----
 105
 106  SOCK_STREAM - Use the ACE_SOCK_Connector, ACE_SOCK_Stream and
 107                ACE_SOCK_Acceptor classes. In ACE_SOCK_Connector pass
 108                the value IPPROTO_SCTP for the protocol parameter in
 109                either the constructor or the connect(...) method
 110                as shown in SOCK_STREAM_clt.cpp. In ACE_SOCK_Acceptor
 111                pass the value IPPROTO_SCTP for the protocol parameter
 112                in either the constructor or the open(...) method
 113                as shown in SOCK_STREAM_srv.cpp.
 114
 115                You must include the file sctp.h in order for
 116                IPPROTO_SCTP to be defined.  This file should be under
 117                /usr/include/netinet
 118
 119                Aside from these changes, the classes can be used as
 120                they are under TCP (the protocol they use by
 121                default). Be cautious to use SCTP protocol options when
 122                setting socket options on SCTP sockets (e.g., use
 123                SCTP_NODELAY, not TCP_NODELAY, to disable Nagle's
 124                algorithm on an SCTP socket.)
 125
 126  SOCK_SEQPACKET - Use the ACE_SOCK_SEQPACK_Connector,
 127                   ACE_SOCK_SEQPACK_Association, and
 128                   ACE_SOCK_SEQPACK_Acceptor classes, which parallel
 129                   the familiar ACE_SOCK_Connector, ACE_SOCK_Stream,
 130                   and ACE_SOCK_Acceptor classes, respectively.  Please
 131                   see SOCK_SEQPACK_clt.cpp and SOCK_SEQPACK_srv.cpp for
 132                   more details.
 133
 134                   In the special case where you want to specify a set
 135                   of interfaces---other than one or all
 136                   interfaces---for an ACE_SOCK_SEQPACK_Acceptor, use
 137                   an ACE_Multihomed_INET_Addr in place of the familiar
 138                   ACE_INET_Addr.  (See SOCK_SEQPACK_srv.cpp for an
 139                   example.)
 140
 141                   SCTP associations may have more than one local and
 142                   more than one remote address bound to them.
 143                   Accordingly, ACE_SOCK_SEQPACK_Association provides
 144                   methods get_local_addrs(...) and
 145                   get_remote_addrs(...). These methods return the list
 146                   of local and remote addresses bound to an active
 147                   mode SCTP socket. Alternately, the familiar
 148                   ACE_SOCK::get_local_addr(...)  and
 149                   ACE_SOCK::get_remote_addr(...) methods will work
 150                   properly with an active mode SCTP socket, but each
 151                   will only return a single address. These functions
 152                   are only NOT available on ACE_SOCK_SEQPACK_Acceptor
 153                   even though that is an SCTP socket as well. This is
 154                   because the functions getpeername() and
 155                   getsockname() called on a passive SCTP acceptor
 156                   socket returns the same values as a TCP socket. As
 157                   such, the current ACE methods get_local_addr() and
 158                   get_remote_addr() defined in ACE_SOCK are sufficient.
 159
 160
 161 DESIGN
 162 ------
 163
 164 SCTP supports two types of network service: SOCK_STREAM and
 165 SOCK_SEQPACKET.  To integrate SCTP's SOCK_STREAM service into ACE we
 166 had to make a small modification to the current SOCK_STREAM wrapper
 167 facade. We had to add a protocol parameter to one constructor and one
 168 connect method of the ACE_SOCK_Connector class. After this
 169 modification the ACE SOCK_STREAM wrapper facade worked properly over
 170 both TCP and SCTP.
 171
 172 To integrate SCTP's SOCK_SEQPACKET service into ACE we had to create a
 173 new wrapper facade, which we refer to as SOCK_SEQPACK. We closely
 174 emulated the current SOCK_STREAM wrapper facade to develop our new
 175 SOCK_SEQPACK wrapper facade. SOCK_SEQPACK_wrapper_facade.jpg depicts
 176 the classes that implement this new wrapper facade. Also indicated are
 177 those methods that have a substantial change from their SOCK_STREAM
 178 wrapper façade counterparts. Not depicted in the figure but noteworthy
 179 is the removal of the QoS enabled constructor and accept method that
 180 were imported to SOCK_SEQPACK_Acceptor from SOCK_Acceptor and the
 181 removal of the QoS enabled constructor and connect method that were
 182 imported into SOCK_SEQPACK_Connector from SOCK_Connector. SOCK_SEQPACK
 183 association provides two methods to get the list of secondary
 184 addresses associated with the local and remote socket (explained in
 185 more detail in the usage section above).
 186
 187
 188 To enable the user to fully exploit the network path multiplexing
 189 features of SCTP we created a new subclass of ACE_INET_Addr called
 190 ACE_INET_Multihomed_Addr. This class enables applications to specify
 191 restricted subsets of network interfaces for inclusion on SCTP
 192 associations on the client and server side. Multihomed_INET_Addr
 193 provides a subset of the ACE_INET_Addr API with the addition of
 194 optional parameters for lists of secondary addresses or hostnames.  If
 195 just a primary address or hostname is provided
 196 ACE_Multihomed_INET_Addr behaves as an ACE_INET_Addr (in fact it just
 197 populates the base ACE_INET_Addr) This is also depicted in
 198 SOCK_SEQPACK_wrapper_facade.jpg. Multihomed_INET_Addr is only used by
 199 the SOCK_SEQPACK wrapper facade.
 200
 201
 202 All SCTP socket options can be read and written from the current
 203 socket options methods provided by ACE_SOCK.
 204
 205 Finally, our SOCK_SEQPACK wrapper facade does not yet support SCTP
 206 stream multiplexing.
 207
 208 Here are the files under $(ACE_ROOT) that were either modified or
 209 added. NO files were removed.
 210
 211 $(ACE_ROOT)/ace/ace_dll.dsp                                MODIFIED
 212 $(ACE_ROOT)/ace/OS.h                                       MODIFIED
 213 $(ACE_ROOT)/ace/Makefile.ace                               MODIFIED
 214 $(ACE_ROOT)/ace/SOCK_Connector.h                           MODIFIED
 215 $(ACE_ROOT)/ace/SOCK_Connector.cpp                         MODIFIED
 216
 217 $(ACE_ROOT)/ace/SOCK_SEQPACK_Acceptor.h                    ADDED
 218 $(ACE_ROOT)/ace/SOCK_SEQPACK_Acceptor.i                    ADDED
 219 $(ACE_ROOT)/ace/SOCK_SEQPACK_Acceptor.cpp                  ADDED
 220
 221 $(ACE_ROOT)/ace/SOCK_SEQPACK_Connector.h                   ADDED
 222 $(ACE_ROOT)/ace/SOCK_SEQPACK_Connector.i                   ADDED
 223 $(ACE_ROOT)/ace/SOCK_SEQPACK_Connector.cpp                 ADDED
 224
 225 $(ACE_ROOT)/ace/SOCK_SEQPACK_Association.h                 ADDED
 226 $(ACE_ROOT)/ace/SOCK_SEQPACK_Association.i                 ADDED
 227 $(ACE_ROOT)/ace/SOCK_SEQPACK_Association.cpp               ADDED
 228
 229 $(ACE_ROOT)/ace/Multihomed_INET_Addr.h                     ADDED
 230 $(ACE_ROOT)/ace/Multihomed_INET_Addr.i                     ADDED
 231 $(ACE_ROOT)/ace/Multihomed_INET_Addr.cpp                   ADDED
 232
 233 $(ACE_ROOT)/bin/PerlACE/Process_Unix.pm                    MODIFIED
 234 $(ACE_ROOT)/bin/PerlACE/Process_Win32.pm                   MODIFIED
 235
 236 $(ACE_ROOT)/include/makeinclude/wrapper_macros.GNU         MODIFIED
 237 $(ACE_ROOT)/include/makeinclude/platform_linux.GNU         MODIFIED
 238
 239 $(ACE_ROOT)/tests/Makefile                                 MODIFIED
 240 $(ACE_ROOT)/tests/Multihomed_INET_Addr_Test.cpp            ADDED
 241 $(ACE_ROOT)/tests/Multihomed_INET_Addr_Test.dsp            ADDED
 242 $(ACE_ROOT)/tests/SOCK_SEQPACK_Association_Test.cpp        ADDED
 243 $(ACE_ROOT)/tests/SOCK_SEQPACK_Association_Test.dsp        ADDED
 244 $(ACE_ROOT)/tests/run_test.lst                             MODIFIED
 245 $(ACE_ROOT)/tests/run_tests.bat                            MODIFIED
 246 $(ACE_ROOT)/tests/tests.dsw                                MODIFIED
 247
 248 $(ACE_ROOT)/performance-tests/SCTP/THANKS                  ADDED
 249 $(ACE_ROOT)/performance-tests/SCTP/README                  ADDED
 250 $(ACE_ROOT)/performance-tests/SCTP/README.SCTP             ADDED
 251 $(ACE_ROOT)/performance-tests/SCTP/README.SCTP_in_ACE      ADDED
 252 $(ACE_ROOT)/performance-tests/SCTP/README.SCTP_PERF_TEST   ADDED
 253 $(ACE_ROOT)/performance-tests/SCTP/README.OpenSS7          ADDED
 254 $(ACE_ROOT)/performance-tests/SCTP/README.LKSCTP           ADDED
 255
 256 $(ACE_ROOT)/performance-tests/SCTP/Makefile                ADDED
 257 $(ACE_ROOT)/performance-tests/SCTP/run_spectrum.pl         ADDED
 258
 259 $(ACE_ROOT)/performance-tests/SCTP/hist.h                  ADDED
 260 $(ACE_ROOT)/performance-tests/SCTP/hist.cpp                ADDED
 261
 262 $(ACE_ROOT)/performance-tests/SCTP/Options_Manager.h       ADDED
 263 $(ACE_ROOT)/performance-tests/SCTP/Options_Manager.cpp     ADDED
 264
 265 $(ACE_ROOT)/performance-tests/SCTP/SOCK_STREAM_clt.cpp     ADDED
 266 $(ACE_ROOT)/performance-tests/SCTP/SOCK_STREAM_srv.cpp     ADDED
 267
 268 $(ACE_ROOT)/performance-tests/SCTP/SOCK_SEQPACK_clt.cpp    ADDED
 269 $(ACE_ROOT)/performance-tests/SCTP/SOCK_SEQPACK_srv.cpp    ADDED