427 lines
15 KiB
Groff
427 lines
15 KiB
Groff
.\" 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 Transmission Control 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
|
|
dynammically 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 2 :
|
|
.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 maxium 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 undesireable, 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 prefered
|
|
and the last is the least prefered.
|
|
.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 specifices 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 ERRORS
|
|
.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
|