/share/man/man4/sctp.4
https://bitbucket.org/freebsd/freebsd-head/ · Forth · 425 lines · 425 code · 0 blank · 0 comment · 10 complexity · 3db49a57985e42e4c275943a32258797 MD5 · raw file
- .\" 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. All advertising materials mentioning features or use of this software
- .\" must display the following acknowledgement:
- .\" This product includes software developed by the University of
- .\" California, Berkeley and its contributors.
- .\" 4. 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