diff options
Diffstat (limited to 'share/man/man4/sctp.4')
| -rw-r--r-- | share/man/man4/sctp.4 | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/share/man/man4/sctp.4 b/share/man/man4/sctp.4 new file mode 100644 index 0000000..880e808 --- /dev/null +++ b/share/man/man4/sctp.4 @@ -0,0 +1,421 @@ +.\" Copyright (c) 2006, Randall Stewart. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 15, 2006 +.Dt SCTP 4 +.Os +.Sh NAME +.Nm sctp +.Nd Internet Stream Control Transmission Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP +.Ft int +.Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP +.Sh DESCRIPTION +The +.Tn SCTP +protocol provides reliable, flow-controlled, two-way +transmission of data. +It is a message oriented protocol and can +support the +.Dv SOCK_STREAM +and +.Dv SOCK_SEQPACKET +abstractions. +.Tn SCTP +uses the standard +Internet address format and, in addition, provides a per-host +collection of +.Dq "port addresses" . +Thus, each address is composed of an Internet address specifying +the host and network, with a specific +.Tn SCTP +port on the host identifying the peer entity. +.Pp +There are two models of programming in SCTP. +The first uses the +.Dv SOCK_STREAM +abstraction. +In this abstraction sockets utilizing the +.Tn SCTP +protocol are either +.Dq active +or +.Dq passive . +Active sockets initiate connections to passive +sockets. +By default, +.Tn SCTP +sockets are created active; to create a +passive socket, the +.Xr listen 2 +system call must be used after binding the socket with the +.Xr bind 2 +or +.Xr sctp_bindx 3 +system calls. +Only passive sockets may use the +.Xr accept 2 +call to accept incoming connections. +Only active sockets may use the +.Xr connect 2 +call to initiate connections. +.Pp +The other abstraction +.Dv SOCK_SEQPACKET +provides a +.Dq connectionless +mode of operation in that the user may send to an address +(using any of the valid send calls that carry a +socket address) and an association will be setup +implicitly by the underlying +.Tn SCTP +transport stack. +This abstraction is the only one capable of sending data on the +third leg of the four-way handshake. +A user must still call +.Xr listen 2 +to allow the socket to accept connections. +Calling +.Xr listen 2 +however does not restrict the user from still initiating +implicit connections to other peers. +.Pp +The +.Tn SCTP +protocol directly supports multi-homing. +So when binding a socket with the +.Dq wildcard +address +.Dv INADDR_ANY , +the +.Tn SCTP +stack will inform the peer about all of the local addresses +that are deemed in scope of the peer. +The peer will then possibly have multiple paths to reach the local host. +.Pp +The +.Tn SCTP +transport protocol is also multi-streamed. +Multi-streaming refers to the ability to send sub-ordered flows of +messages. +A user performs this by specifying a specific stream in one of the +extended send calls such as the +.Xr sctp_send 3 +function call. +Sending messages on different streams will allow parallel delivery +of data i.e., a message loss in stream 1 will not block the delivery +of messages sent in stream 2. +.Pp +The +.Tn SCTP +transport protocol also provides a unordered service as well. +The unordered service allows a message to be sent and delivered +with no regard to the ordering of any other message. +.Ss Extensions +The FreeBSD implementation of +.Tn SCTP +also supports the following extensions: +.Bl -hang -width indent +.It "sctp partial reliability" +This extension allows one to have message be skipped and +not delivered based on some user specified parameters. +.It "sctp dynamic addressing" +This extension allows addresses to be added and deleted +dynamically from an existing association. +.It "sctp authentication" +This extension allows the user to authenticate specific +peer chunks (including data) to validate that the peer +who sent the message is in fact the peer who setup the +association. +A shared key option is also provided for +so that two stacks can pre-share keys. +.It "packet drop" +Some routers support a special satellite protocol that +will report losses due to corruption. +This allows retransmissions without subsequent loss in bandwidth +utilization. +.It "stream reset" +This extension allows a user on either side to reset the +stream sequence numbers used by any or all streams. +.El +.Pp +.Tn SCTP +supports a number of socket options which can be set with +.Xr setsockopt 2 +and tested with +.Xr getsockopt 2 +or +.Xr sctp_opt_info 3 : +.Bl -tag -width ".Dv SCTP_SET_PEER_PRIMARY_ADDR" +.It Dv SCTP_NODELAY +Under most circumstances, +.Tn SCTP +sends data when it is presented; when outstanding data has not +yet been acknowledged, it gathers small amounts of output to be +sent in a single packet once an acknowledgement is received. +For some clients, such as window systems that send a stream of +mouse events which receive no replies, this packetization may +cause significant delays. +The boolean option +.Dv SCTP_NODELAY +defeats this algorithm. +.It Dv SCTP_RTOINFO +This option returns specific information about an associations +.Dq "Retransmission Time Out" . +It can also be used to change the default values. +.It Dv SCTP_ASSOCINFO +This option returns specific information about the requested +association. +.It Dv SCTP_INITMSG +This option allows you to get or set the default sending +parameters when an association is implicitly setup. +It allows you to change such things as the maximum number of +streams allowed inbound and the number of streams requested +of the peer. +.It Dv SCTP_AUTOCLOSE +For the one-to-many model +.Dv ( SOCK_SEQPACKET ) +associations are setup implicitly. +This option allows the user to specify a default number of idle +seconds to allow the association be maintained. +After the idle timer (where no user message have been sent or have +been received from the peer) the association will be gracefully +closed. +The default for this value is 0, or unlimited (i.e., no automatic +close). +.It Dv SCTP_SET_PEER_PRIMARY_ADDR +The dynamic address extension allows a peer to also request a +particular address of its be made into the primary address. +This option allows the caller to make such a request to a peer. +Note that if the peer does not also support the dynamic address +extension, this call will fail. +Note the caller must provide a valid local address that the peer has +been told about during association setup or dynamically. +.It Dv SCTP_PRIMARY_ADDR +This option allows the setting of the primary address +that the caller wishes to send to. +The caller provides the address of a peer that is to be made primary. +.It Dv SCTP_ADAPTATION_LAYER +The dynamic address extension also allows a user to +pass a 32 bit opaque value upon association setup. +This option allows a user to set or get this value. +.It Dv SCTP_DISABLE_FRAGMENTS +By default +.Tn SCTP +will fragment user messages into multiple pieces that +will fit on the network and then later, upon reception, reassemble +the pieces into a single user message. +If this option is enabled instead, any send that exceeds the path +maximum transfer unit (P-MTU) will fail and the message will NOT be +sent. +.It Dv SCTP_PEER_ADDR_PARAMS +This option will allow a user to set or get specific +peer address parameters. +.It Dv SCTP_DEFAULT_SEND_PARAM +When a user does not use one of the extended send +calls (e.g., +.Xr sctp_sendmsg 3 ) +a set of default values apply to each send. +These values include things like the stream number to send +to as well as the per-protocol id. +This option lets a caller both get and set these values. +If the user changes these default values, then these new values will +be used as the default whenever no information is provided by the +sender (i.e., the non-extended API is used). +.It Dv SCTP_EVENTS +.Tn SCTP +has non-data events that it can communicate +to its application. +By default these are all disabled since they arrive in the data path +with a special flag +.Dv MSG_NOTIFICATION +set upon the received message. +This option lets a caller +both get what events are current being received +as well as set different events that they may be interested +in receiving. +.It Dv SCTP_I_WANT_MAPPED_V4_ADDR +.Tn SCTP +supports both IPV4 and IPV6. +An association may span both IPV4 and IPV6 addresses since +.Tn SCTP +is multi-homed. +By default, when opening an IPV6 socket, when +data arrives on the socket from a peer's +V4 address the V4 address will be presented with an address family +of AF_INET. +If this is undesirable, then this option +can be enabled which will then convert all V4 addresses +into mapped V6 representations. +.It Dv SCTP_MAXSEG +By default +.Tn SCTP +chooses its message fragmentation point +based upon the smallest P-MTU of the peer. +This option lets the caller set it to a smaller value. +Note that while the user can change this value, if the P-MTU +is smaller than the value set by the user, then the P-MTU +value will override any user setting. +.It Dv SCTP_DELAYED_ACK_TIME +This option lets the user both set and get the +delayed ack time (in milliseconds) that +.Tn SCTP +is using. +The default is 200 milliseconds. +.It Dv SCTP_PARTIAL_DELIVERY_POINT +.Tn SCTP +at times may need to start delivery of a +very large message before the entire message has +arrived. +By default SCTP waits until the incoming +message is larger than one fourth of the receive +buffer. +This option allows the stacks value +to be overridden with a smaller value. +.It Dv SCTP_FRAGMENT_INTERLEAVE +.Tn SCTP +at times will start partial delivery (as mentioned above). +In the normal case successive reads will continue to return +the rest of the message, blocking if needed, until all of +that message is read. +However this means other messages may have arrived and be ready +for delivery and be blocked behind the message being partially +delivered. +If this option is enabled, when a partial delivery +message has no more data to be received, then a subsequent +read may return a different message that is ready for delivery. +By default this option is off since the user must be using the +extended API's to be able to tell the difference between +messages (via the stream and stream sequence number). +.It Dv SCTP_AUTH_CHUNK +By default only the dynamic addressing chunks are +authenticated. +This option lets a user request an +additional chunk be authenticated as well. +Note that successive calls to this option will work and continue +to add more chunks that require authentication. +Note that this option only effects future associations and +not existing ones. +.It Dv SCTP_AUTH_KEY +This option allows a user to specify a shared +key that can be later used to authenticate +a peer. +.It Dv SCTP_HMAC_IDENT +This option will let you get or set the list of +HMAC algorithms used to authenticate peers. +Note that the HMAC values are in priority order where +the first HMAC identifier is the most preferred +and the last is the least preferred. +.It Dv SCTP_AUTH_ACTIVE_KEY +This option allows you to make a key active for +the generation of authentication information. +Note that the peer must have the same key or else the +data will be discarded. +.It Dv SCTP_AUTH_DELETE_KEY +This option allows you to delete an old key. +.It Dv SCTP_USE_EXT_RECVINFO +The sockets api document allows an extended +send/receive information structure to be used. +The extended structure includes additional fields +related to the next message to be received (after the +current receive completes) if such information is known. +By default the system will not pass this information. +This option allows the user to request this information. +.It Dv SCTP_AUTO_ASCONF +By default when bound to all address and the system administrator has +enables automatic dynamic addresses, the +.Tn SCTP +stack will automatically generate address changes into add and +delete requests to any peers by setting this option to +true. +This option allows an endpoint to disable that behavior. +.It Dv SCTP_MAXBURST +By default +.Tn SCTP +implements micro-burst control so that as the congestion window +opens up no large burst of packets can be generated. +The default burst limit is four. +This option lets the user change this value. +.It Dv SCTP_CONTEXT +Many sctp extended calls have a context field. +The context field is a 32 bit opaque value that will be returned in +send failures. +This option lets the caller set the default +context value to use when none is provided by the user. +.It Dv SCTP_EXPLICIT_EOR +By default, a single send is a complete message. +.Tn SCTP +generates an implied record boundary. +If this option is enabled, then all sends are part of the same message +until the user indicates an end of record with the +special flag +.Dv SCTP_EOR +passed in the sctp_sndrcvinfo flags field. +This effectively makes all sends part of the same message +until the user specifies differently. +This means that a caller must NOT change the stream number until +after the +.Dv SCTP_EOR +is passed to +.Tn SCTP +else an error will be returned. +.It Dv SCTP_STATUS +This option is a read only option that returns +various status information about the specified association. +.It Dv SCTP_GET_PEER_ADDR_INFO +This read only option returns information about a peer +address. +.It Dv SCTP_PEER_AUTH_CHUNKS +This read only option returns a list of the chunks +the peer requires to be authenticated. +.It Dv SCTP_LOCAL_AUTH_CHUNKS +This read only option returns a list of the locally +required chunks that must be authenticated. +.It Dv SCTP_RESET_STREAMS +This socket option is used to cause a stream sequence +number or all stream sequence numbers to be reset. +Note that the peer +.Tn SCTP +endpoint must also support the stream reset extension +as well. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr listen 2 , +.Xr sctp_bindx 3 , +.Xr sctp_connectx 3 , +.Xr sctp_opt_info 3 , +.Xr sctp_recvmsg 3 , +.Xr sctp_sendmsg 3 |
