/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

  1. .\" Copyright (c) 2006, Randall Stewart.
  2. .\"
  3. .\" Redistribution and use in source and binary forms, with or without
  4. .\" modification, are permitted provided that the following conditions
  5. .\" are met:
  6. .\" 1. Redistributions of source code must retain the above copyright
  7. .\" notice, this list of conditions and the following disclaimer.
  8. .\" 2. Redistributions in binary form must reproduce the above copyright
  9. .\" notice, this list of conditions and the following disclaimer in the
  10. .\" documentation and/or other materials provided with the distribution.
  11. .\" 3. All advertising materials mentioning features or use of this software
  12. .\" must display the following acknowledgement:
  13. .\" This product includes software developed by the University of
  14. .\" California, Berkeley and its contributors.
  15. .\" 4. Neither the name of the University nor the names of its contributors
  16. .\" may be used to endorse or promote products derived from this software
  17. .\" without specific prior written permission.
  18. .\"
  19. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29. .\" SUCH DAMAGE.
  30. .\"
  31. .\" $FreeBSD$
  32. .\"
  33. .Dd December 15, 2006
  34. .Dt SCTP 4
  35. .Os
  36. .Sh NAME
  37. .Nm sctp
  38. .Nd Internet Stream Control Transmission Protocol
  39. .Sh SYNOPSIS
  40. .In sys/types.h
  41. .In sys/socket.h
  42. .In netinet/sctp.h
  43. .Ft int
  44. .Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP
  45. .Ft int
  46. .Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP
  47. .Sh DESCRIPTION
  48. The
  49. .Tn SCTP
  50. protocol provides reliable, flow-controlled, two-way
  51. transmission of data.
  52. It is a message oriented protocol and can
  53. support the
  54. .Dv SOCK_STREAM
  55. and
  56. .Dv SOCK_SEQPACKET
  57. abstractions.
  58. .Tn SCTP
  59. uses the standard
  60. Internet address format and, in addition, provides a per-host
  61. collection of
  62. .Dq "port addresses" .
  63. Thus, each address is composed of an Internet address specifying
  64. the host and network, with a specific
  65. .Tn SCTP
  66. port on the host identifying the peer entity.
  67. .Pp
  68. There are two models of programming in SCTP.
  69. The first uses the
  70. .Dv SOCK_STREAM
  71. abstraction.
  72. In this abstraction sockets utilizing the
  73. .Tn SCTP
  74. protocol are either
  75. .Dq active
  76. or
  77. .Dq passive .
  78. Active sockets initiate connections to passive
  79. sockets.
  80. By default,
  81. .Tn SCTP
  82. sockets are created active; to create a
  83. passive socket, the
  84. .Xr listen 2
  85. system call must be used after binding the socket with the
  86. .Xr bind 2
  87. or
  88. .Xr sctp_bindx 3
  89. system calls.
  90. Only passive sockets may use the
  91. .Xr accept 2
  92. call to accept incoming connections.
  93. Only active sockets may use the
  94. .Xr connect 2
  95. call to initiate connections.
  96. .Pp
  97. The other abstraction
  98. .Dv SOCK_SEQPACKET
  99. provides a
  100. .Dq connectionless
  101. mode of operation in that the user may send to an address
  102. (using any of the valid send calls that carry a
  103. socket address) and an association will be setup
  104. implicitly by the underlying
  105. .Tn SCTP
  106. transport stack.
  107. This abstraction is the only one capable of sending data on the
  108. third leg of the four-way handshake.
  109. A user must still call
  110. .Xr listen 2
  111. to allow the socket to accept connections.
  112. Calling
  113. .Xr listen 2
  114. however does not restrict the user from still initiating
  115. implicit connections to other peers.
  116. .Pp
  117. The
  118. .Tn SCTP
  119. protocol directly supports multi-homing.
  120. So when binding a socket with the
  121. .Dq wildcard
  122. address
  123. .Dv INADDR_ANY ,
  124. the
  125. .Tn SCTP
  126. stack will inform the peer about all of the local addresses
  127. that are deemed in scope of the peer.
  128. The peer will then possibly have multiple paths to reach the local host.
  129. .Pp
  130. The
  131. .Tn SCTP
  132. transport protocol is also multi-streamed.
  133. Multi-streaming refers to the ability to send sub-ordered flows of
  134. messages.
  135. A user performs this by specifying a specific stream in one of the
  136. extended send calls such as the
  137. .Xr sctp_send 3
  138. function call.
  139. Sending messages on different streams will allow parallel delivery
  140. of data i.e., a message loss in stream 1 will not block the delivery
  141. of messages sent in stream 2.
  142. .Pp
  143. The
  144. .Tn SCTP
  145. transport protocol also provides a unordered service as well.
  146. The unordered service allows a message to be sent and delivered
  147. with no regard to the ordering of any other message.
  148. .Ss Extensions
  149. The FreeBSD implementation of
  150. .Tn SCTP
  151. also supports the following extensions:
  152. .Bl -hang -width indent
  153. .It "sctp partial reliability"
  154. This extension allows one to have message be skipped and
  155. not delivered based on some user specified parameters.
  156. .It "sctp dynamic addressing"
  157. This extension allows addresses to be added and deleted
  158. dynamically from an existing association.
  159. .It "sctp authentication"
  160. This extension allows the user to authenticate specific
  161. peer chunks (including data) to validate that the peer
  162. who sent the message is in fact the peer who setup the
  163. association.
  164. A shared key option is also provided for
  165. so that two stacks can pre-share keys.
  166. .It "packet drop"
  167. Some routers support a special satellite protocol that
  168. will report losses due to corruption.
  169. This allows retransmissions without subsequent loss in bandwidth
  170. utilization.
  171. .It "stream reset"
  172. This extension allows a user on either side to reset the
  173. stream sequence numbers used by any or all streams.
  174. .El
  175. .Pp
  176. .Tn SCTP
  177. supports a number of socket options which can be set with
  178. .Xr setsockopt 2
  179. and tested with
  180. .Xr getsockopt 2
  181. or
  182. .Xr sctp_opt_info 3 :
  183. .Bl -tag -width ".Dv SCTP_SET_PEER_PRIMARY_ADDR"
  184. .It Dv SCTP_NODELAY
  185. Under most circumstances,
  186. .Tn SCTP
  187. sends data when it is presented; when outstanding data has not
  188. yet been acknowledged, it gathers small amounts of output to be
  189. sent in a single packet once an acknowledgement is received.
  190. For some clients, such as window systems that send a stream of
  191. mouse events which receive no replies, this packetization may
  192. cause significant delays.
  193. The boolean option
  194. .Dv SCTP_NODELAY
  195. defeats this algorithm.
  196. .It Dv SCTP_RTOINFO
  197. This option returns specific information about an associations
  198. .Dq "Retransmission Time Out" .
  199. It can also be used to change the default values.
  200. .It Dv SCTP_ASSOCINFO
  201. This option returns specific information about the requested
  202. association.
  203. .It Dv SCTP_INITMSG
  204. This option allows you to get or set the default sending
  205. parameters when an association is implicitly setup.
  206. It allows you to change such things as the maximum number of
  207. streams allowed inbound and the number of streams requested
  208. of the peer.
  209. .It Dv SCTP_AUTOCLOSE
  210. For the one-to-many model
  211. .Dv ( SOCK_SEQPACKET )
  212. associations are setup implicitly.
  213. This option allows the user to specify a default number of idle
  214. seconds to allow the association be maintained.
  215. After the idle timer (where no user message have been sent or have
  216. been received from the peer) the association will be gracefully
  217. closed.
  218. The default for this value is 0, or unlimited (i.e., no automatic
  219. close).
  220. .It Dv SCTP_SET_PEER_PRIMARY_ADDR
  221. The dynamic address extension allows a peer to also request a
  222. particular address of its be made into the primary address.
  223. This option allows the caller to make such a request to a peer.
  224. Note that if the peer does not also support the dynamic address
  225. extension, this call will fail.
  226. Note the caller must provide a valid local address that the peer has
  227. been told about during association setup or dynamically.
  228. .It Dv SCTP_PRIMARY_ADDR
  229. This option allows the setting of the primary address
  230. that the caller wishes to send to.
  231. The caller provides the address of a peer that is to be made primary.
  232. .It Dv SCTP_ADAPTATION_LAYER
  233. The dynamic address extension also allows a user to
  234. pass a 32 bit opaque value upon association setup.
  235. This option allows a user to set or get this value.
  236. .It Dv SCTP_DISABLE_FRAGMENTS
  237. By default
  238. .Tn SCTP
  239. will fragment user messages into multiple pieces that
  240. will fit on the network and then later, upon reception, reassemble
  241. the pieces into a single user message.
  242. If this option is enabled instead, any send that exceeds the path
  243. maximum transfer unit (P-MTU) will fail and the message will NOT be
  244. sent.
  245. .It Dv SCTP_PEER_ADDR_PARAMS
  246. This option will allow a user to set or get specific
  247. peer address parameters.
  248. .It Dv SCTP_DEFAULT_SEND_PARAM
  249. When a user does not use one of the extended send
  250. calls (e.g.,
  251. .Xr sctp_sendmsg 3 )
  252. a set of default values apply to each send.
  253. These values include things like the stream number to send
  254. to as well as the per-protocol id.
  255. This option lets a caller both get and set these values.
  256. If the user changes these default values, then these new values will
  257. be used as the default whenever no information is provided by the
  258. sender (i.e., the non-extended API is used).
  259. .It Dv SCTP_EVENTS
  260. .Tn SCTP
  261. has non-data events that it can communicate
  262. to its application.
  263. By default these are all disabled since they arrive in the data path
  264. with a special flag
  265. .Dv MSG_NOTIFICATION
  266. set upon the received message.
  267. This option lets a caller
  268. both get what events are current being received
  269. as well as set different events that they may be interested
  270. in receiving.
  271. .It Dv SCTP_I_WANT_MAPPED_V4_ADDR
  272. .Tn SCTP
  273. supports both IPV4 and IPV6.
  274. An association may span both IPV4 and IPV6 addresses since
  275. .Tn SCTP
  276. is multi-homed.
  277. By default, when opening an IPV6 socket, when
  278. data arrives on the socket from a peer's
  279. V4 address the V4 address will be presented with an address family
  280. of AF_INET.
  281. If this is undesirable, then this option
  282. can be enabled which will then convert all V4 addresses
  283. into mapped V6 representations.
  284. .It Dv SCTP_MAXSEG
  285. By default
  286. .Tn SCTP
  287. chooses its message fragmentation point
  288. based upon the smallest P-MTU of the peer.
  289. This option lets the caller set it to a smaller value.
  290. Note that while the user can change this value, if the P-MTU
  291. is smaller than the value set by the user, then the P-MTU
  292. value will override any user setting.
  293. .It Dv SCTP_DELAYED_ACK_TIME
  294. This option lets the user both set and get the
  295. delayed ack time (in milliseconds) that
  296. .Tn SCTP
  297. is using.
  298. The default is 200 milliseconds.
  299. .It Dv SCTP_PARTIAL_DELIVERY_POINT
  300. .Tn SCTP
  301. at times may need to start delivery of a
  302. very large message before the entire message has
  303. arrived.
  304. By default SCTP waits until the incoming
  305. message is larger than one fourth of the receive
  306. buffer.
  307. This option allows the stacks value
  308. to be overridden with a smaller value.
  309. .It Dv SCTP_FRAGMENT_INTERLEAVE
  310. .Tn SCTP
  311. at times will start partial delivery (as mentioned above).
  312. In the normal case successive reads will continue to return
  313. the rest of the message, blocking if needed, until all of
  314. that message is read.
  315. However this means other messages may have arrived and be ready
  316. for delivery and be blocked behind the message being partially
  317. delivered.
  318. If this option is enabled, when a partial delivery
  319. message has no more data to be received, then a subsequent
  320. read may return a different message that is ready for delivery.
  321. By default this option is off since the user must be using the
  322. extended API's to be able to tell the difference between
  323. messages (via the stream and stream sequence number).
  324. .It Dv SCTP_AUTH_CHUNK
  325. By default only the dynamic addressing chunks are
  326. authenticated.
  327. This option lets a user request an
  328. additional chunk be authenticated as well.
  329. Note that successive calls to this option will work and continue
  330. to add more chunks that require authentication.
  331. Note that this option only effects future associations and
  332. not existing ones.
  333. .It Dv SCTP_AUTH_KEY
  334. This option allows a user to specify a shared
  335. key that can be later used to authenticate
  336. a peer.
  337. .It Dv SCTP_HMAC_IDENT
  338. This option will let you get or set the list of
  339. HMAC algorithms used to authenticate peers.
  340. Note that the HMAC values are in priority order where
  341. the first HMAC identifier is the most preferred
  342. and the last is the least preferred.
  343. .It Dv SCTP_AUTH_ACTIVE_KEY
  344. This option allows you to make a key active for
  345. the generation of authentication information.
  346. Note that the peer must have the same key or else the
  347. data will be discarded.
  348. .It Dv SCTP_AUTH_DELETE_KEY
  349. This option allows you to delete an old key.
  350. .It Dv SCTP_USE_EXT_RECVINFO
  351. The sockets api document allows an extended
  352. send/receive information structure to be used.
  353. The extended structure includes additional fields
  354. related to the next message to be received (after the
  355. current receive completes) if such information is known.
  356. By default the system will not pass this information.
  357. This option allows the user to request this information.
  358. .It Dv SCTP_AUTO_ASCONF
  359. By default when bound to all address and the system administrator has
  360. enables automatic dynamic addresses, the
  361. .Tn SCTP
  362. stack will automatically generate address changes into add and
  363. delete requests to any peers by setting this option to
  364. true.
  365. This option allows an endpoint to disable that behavior.
  366. .It Dv SCTP_MAXBURST
  367. By default
  368. .Tn SCTP
  369. implements micro-burst control so that as the congestion window
  370. opens up no large burst of packets can be generated.
  371. The default burst limit is four.
  372. This option lets the user change this value.
  373. .It Dv SCTP_CONTEXT
  374. Many sctp extended calls have a context field.
  375. The context field is a 32 bit opaque value that will be returned in
  376. send failures.
  377. This option lets the caller set the default
  378. context value to use when none is provided by the user.
  379. .It Dv SCTP_EXPLICIT_EOR
  380. By default, a single send is a complete message.
  381. .Tn SCTP
  382. generates an implied record boundary.
  383. If this option is enabled, then all sends are part of the same message
  384. until the user indicates an end of record with the
  385. special flag
  386. .Dv SCTP_EOR
  387. passed in the sctp_sndrcvinfo flags field.
  388. This effectively makes all sends part of the same message
  389. until the user specifies differently.
  390. This means that a caller must NOT change the stream number until
  391. after the
  392. .Dv SCTP_EOR
  393. is passed to
  394. .Tn SCTP
  395. else an error will be returned.
  396. .It Dv SCTP_STATUS
  397. This option is a read only option that returns
  398. various status information about the specified association.
  399. .It Dv SCTP_GET_PEER_ADDR_INFO
  400. This read only option returns information about a peer
  401. address.
  402. .It Dv SCTP_PEER_AUTH_CHUNKS
  403. This read only option returns a list of the chunks
  404. the peer requires to be authenticated.
  405. .It Dv SCTP_LOCAL_AUTH_CHUNKS
  406. This read only option returns a list of the locally
  407. required chunks that must be authenticated.
  408. .It Dv SCTP_RESET_STREAMS
  409. This socket option is used to cause a stream sequence
  410. number or all stream sequence numbers to be reset.
  411. Note that the peer
  412. .Tn SCTP
  413. endpoint must also support the stream reset extension
  414. as well.
  415. .El
  416. .Sh SEE ALSO
  417. .Xr accept 2 ,
  418. .Xr bind 2 ,
  419. .Xr connect 2 ,
  420. .Xr listen 2 ,
  421. .Xr sctp_bindx 3 ,
  422. .Xr sctp_connectx 3 ,
  423. .Xr sctp_opt_info 3 ,
  424. .Xr sctp_recvmsg 3 ,
  425. .Xr sctp_sendmsg 3