share/man/man4/tcp.4

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)tcp.4 8.1 (Berkeley) 6/5/93
  33 .\" $FreeBSD: src/share/man/man4/tcp.4,v 1.11.2.14 2002/12/29 16:35:38 schweikh Exp $
  34 .\" $DragonFly: src/share/man/man4/tcp.4,v 1.8 2007/09/14 23:47:53 swildner Exp $
  35 .\"
  36 .Dd February 14, 1995
  37 .Dt TCP 4
  38 .Os
  39 .Sh NAME
  40 .Nm tcp
  41 .Nd Internet Transmission Control Protocol
  42 .Sh SYNOPSIS
  43 .In sys/types.h
  44 .In sys/socket.h
  45 .In netinet/in.h
  46 .Ft int
  47 .Fn socket AF_INET SOCK_STREAM 0
  48 .Sh DESCRIPTION
  49 The
  50 .Tn TCP
  51 protocol provides reliable, flow-controlled, two-way
  52 transmission of data.  It is a byte-stream protocol used to
  53 support the
  54 .Dv SOCK_STREAM
  55 abstraction.  TCP uses the standard
  56 Internet address format and, in addition, provides a per-host
  57 collection of
  58 .Dq port addresses .
  59 Thus, each address is composed
  60 of an Internet address specifying the host and network, with
  61 a specific
  62 .Tn TCP
  63 port on the host identifying the peer entity.
  64 .Pp
  65 Sockets utilizing the tcp protocol are either
  66 .Dq active
  67 or
  68 .Dq passive .
  69 Active sockets initiate connections to passive
  70 sockets.  By default
  71 .Tn TCP
  72 sockets are created active; to create a
  73 passive socket the
  74 .Xr listen 2
  75 system call must be used
  76 after binding the socket with the
  77 .Xr bind 2
  78 system call.  Only
  79 passive sockets may use the
  80 .Xr accept 2
  81 call to accept incoming connections.  Only active sockets may
  82 use the
  83 .Xr connect 2
  84 call to initiate connections.
  85 .Tn TCP
  86 also supports a more datagram-like mode, called Transaction
  87 .Tn TCP ,
  88 which is described in
  89 .Xr ttcp 4 .
  90 .Pp
  91 Passive sockets may
  92 .Dq underspecify
  93 their location to match
  94 incoming connection requests from multiple networks.  This
  95 technique, termed
  96 .Dq wildcard addressing ,
  97 allows a single
  98 server to provide service to clients on multiple networks.
  99 To create a socket which listens on all networks, the Internet
 100 address
 101 .Dv INADDR_ANY
 102 must be bound.  The
 103 .Tn TCP
 104 port may still be specified
 105 at this time; if the port is not specified the system will assign one.
 106 Once a connection has been established the socket's address is
 107 fixed by the peer entity's location.   The address assigned the
 108 socket is the address associated with the network interface
 109 through which packets are being transmitted and received.  Normally
 110 this address corresponds to the peer entity's network.
 111 .Pp
 112 .Tn TCP
 113 supports a number of socket options which can be set with
 114 .Xr setsockopt 2
 115 and tested with
 116 .Xr getsockopt 2 :
 117 .Bl -tag -width TCP_NODELAYx
 118 .It Dv TCP_NODELAY
 119 Under most circumstances,
 120 .Tn TCP
 121 sends data when it is presented;
 122 when outstanding data has not yet been acknowledged, it gathers
 123 small amounts of output to be sent in a single packet once
 124 an acknowledgement is received.
 125 For a small number of clients, such as window systems
 126 that send a stream of mouse events which receive no replies,
 127 this packetization may cause significant delays.
 128 The boolean option
 129 .Dv TCP_NODELAY
 130 defeats this algorithm.
 131 .It Dv TCP_MAXSEG
 132 By default, a sender\- and receiver-TCP
 133 will negotiate among themselves to determine the maximum segment size
 134 to be used for each connection.  The
 135 .Dv TCP_MAXSEG
 136 option allows the user to determine the result of this negotiation,
 137 and to reduce it if desired.
 138 .It Dv TCP_NOOPT
 139 .Tn TCP
 140 usually sends a number of options in each packet, corresponding to
 141 various
 142 .Tn TCP
 143 extensions which are provided in this implementation.  The boolean
 144 option
 145 .Dv TCP_NOOPT
 146 is provided to disable
 147 .Tn TCP
 148 option use on a per-connection basis.
 149 .It Dv TCP_NOPUSH
 150 By convention, the sender-TCP
 151 will set the
 152 .Dq push
 153 bit and begin transmission immediately (if permitted) at the end of
 154 every user call to
 155 .Xr write 2
 156 or
 157 .Xr writev 2 .
 158 The
 159 .Dv TCP_NOPUSH
 160 option is provided to allow servers to easily make use of Transaction
 161 TCP (see
 162 .Xr ttcp 4 ) .
 163 When the option is set to a non-zero value,
 164 .Tn TCP
 165 will delay sending any data at all until either the socket is closed,
 166 or the internal send buffer is filled.
 167 .El
 168 .Pp
 169 The option level for the
 170 .Xr setsockopt 2
 171 call is the protocol number for
 172 .Tn TCP ,
 173 available from
 174 .Xr getprotobyname 3 ,
 175 or
 176 .Dv IPPROTO_TCP .
 177 All options are declared in
 178 .In netinet/tcp.h .
 179 .Pp
 180 Options at the
 181 .Tn IP
 182 transport level may be used with
 183 .Tn TCP ;
 184 see
 185 .Xr ip 4 .
 186 Incoming connection requests that are source-routed are noted,
 187 and the reverse source route is used in responding.
 188 .Sh MIB VARIABLES
 189 The
 190 .Nm
 191 protocol implements a number of variables in the
 192 .Li net.inet
 193 branch of the
 194 .Xr sysctl 3
 195 MIB.
 196 .Bl -tag -width TCPCTL_DO_RFC1644
 197 .It Dv TCPCTL_DO_RFC1323
 198 .Pq tcp.rfc1323
 199 Implement the window scaling and timestamp options of RFC 1323
 200 (default true).
 201 .It Dv TCPCTL_DO_RFC1644
 202 .Pq tcp.rfc1644
 203 Implement Transaction
 204 .Tn TCP ,
 205 as described in RFC 1644.
 206 .It Dv TCPCTL_MSSDFLT
 207 .Pq tcp.mssdflt
 208 The default value used for the maximum segment size
 209 .Pq Dq MSS
 210 when no advice to the contrary is received from MSS negotiation.
 211 .It Dv TCPCTL_SENDSPACE
 212 .Pq tcp.sendspace
 213 Maximum TCP send window.
 214 .It Dv TCPCTL_RECVSPACE
 215 .Pq tcp.recvspace
 216 Maximum TCP receive window.
 217 .It tcp.log_in_vain
 218 Log any connection attempts to ports where there is not a socket
 219 accepting connections.
 220 The value of 1 limits the logging to SYN (connection establishment)
 221 packets only.
 222 That of 2 results in any TCP packets to closed ports being logged.
 223 Any value unlisted above disables the logging
 224 (default is 0, i.e., the logging is disabled).
 225 .It tcp.msl
 226 The Maximum Segment Lifetime for a packet.
 227 .It tcp.keepinit
 228 Timeout for new, non-established TCP connections.
 229 .It tcp.keepidle
 230 Amount of time the connection should be idle before keepalive
 231 probes (if enabled) are sent.
 232 .It tcp.keepintvl
 233 The interval between keepalive probes sent to remote machines.
 234 After
 235 .Dv TCPTV_KEEPCNT
 236 (default 8) probes are sent, with no response, the connection is dropped.
 237 .It tcp.always_keepalive
 238 Assume that
 239 .Dv SO_KEEPALIVE
 240 is set on all
 241 .Tn TCP
 242 connections, the kernel will
 243 periodically send a packet to the remote host to verify the connection
 244 is still up.
 245 .It tcp.icmp_may_rst
 246 Certain
 247 .Tn ICMP
 248 unreachable messages may abort connections in
 249 .Tn SYN-SENT
 250 state.
 251 .It tcp.do_tcpdrain
 252 Flush packets in the
 253 .Tn TCP
 254 reassembly queue if the system is low on mbufs.
 255 .It tcp.blackhole
 256 If enabled, disable sending of RST when a connection is attempted
 257 to a port where there is not a socket accepting connections.
 258 See
 259 .Xr blackhole 4 .
 260 .It tcp.delayed_ack
 261 Delay ACK to try and piggyback it onto a data packet.
 262 .It tcp.delacktime
 263 Maximum amount of time before a delayed ACK is sent.
 264 .It tcp.newreno
 265 Enable TCP NewReno Fast Recovery algorithm,
 266 as described in RFC 2582.
 267 .It tcp.path_mtu_discovery
 268 Enables Path MTU Discovery.  PMTU Discovery is helpful for avoiding
 269 IP fragmentation when tranferring lots of data to the same client.
 270 For web servers, where most of the connections are short and to
 271 different clients, PMTU Discovery actually hurts performance due
 272 to unnecessary retransmissions.  Turn this on only if most of your
 273 TCP connections are long transfers or are repeatedly to the same
 274 set of clients.
 275 .It tcp.tcbhashsize
 276 Size of the
 277 .Tn TCP
 278 control-block hashtable
 279 (read-only).
 280 This may be tuned using the kernel option
 281 .Dv TCBHASHSIZE
 282 or by setting
 283 .Va net.inet.tcp.tcbhashsize
 284 in the
 285 .Xr loader 8 .
 286 .It tcp.pcbcount
 287 Number of active process control blocks
 288 (read-only).
 289 .It tcp.syncookies
 290 Determines whether or not syn cookies should be generated for
 291 outbound syn-ack packets.  Syn cookies are a great help during
 292 syn flood attacks, and are enabled by default.
 293 .It tcp.isn_reseed_interval
 294 The interval (in seconds) specifying how often the secret data used in
 295 RFC 1948 initial sequence number calculations should be reseeded.
 296 By default, this variable is set to zero, indicating that
 297 no reseeding will occur.
 298 Reseeding should not be necessary, and will break
 299 .Dv TIME_WAIT
 300 recycling for a few minutes.
 301 .It tcp.inet.tcp.rexmit_{min,slop}
 302 Adjust the retransmit timer calculation for TCP.  The slop is
 303 typically added to the raw calculation to take into account
 304 occasional variances that the SRTT (smoothed round trip time)
 305 is unable to accommodate, while the minimum specifies an
 306 absolute minimum.  While a number of TCP RFCs suggest a 1
 307 second minimum these RFCs tend to focus on streaming behavior
 308 and fail to deal with the fact that a 1 second minimum has severe
 309 detrimental effects over lossy interactive connections, such
 310 as a 802.11b wireless link, and over very fast but lossy
 311 connections for those cases not covered by the fast retransmit
 312 code.  For this reason we suggest changing the slop to 200ms and
 313 setting the minimum to something out of the way, like 20ms,
 314 which gives you an effective minimum of 200ms (similar to Linux).
 315 .It tcp.inflight_enable
 316 Enable
 317 .Tn TCP
 318 bandwidth delay product limiting.  An attempt will be made to calculate
 319 the bandwidth delay product for each individual TCP connection and limit
 320 the amount of inflight data being transmitted to avoid building up
 321 unnecessary packets in the network.  This option is recommended if you
 322 are serving a lot of data over connections with high bandwidth-delay
 323 products, such as modems, GigE links, and fast long-haul WANs, and/or
 324 you have configured your machine to accommodate large TCP windows.  In such
 325 situations, without this option, you may experience high interactive
 326 latencies or packet loss due to the overloading of intermediate routers
 327 and switches.  Note that bandwidth delay product limiting only affects
 328 the transmit side of a TCP connection.
 329 .It tcp.inflight_debug
 330 Enable debugging for the bandwidth delay product algorithm.  This may
 331 default to on (1) so if you enable the algorithm you should probably also
 332 disable debugging by setting this variable to 0.
 333 .It tcp.inflight_min
 334 This puts an lower bound on the bandwidth delay product window, in bytes.
 335 A value of 1024 is typically used for debugging.  6000-16000 is more typical
 336 in a production installation.  Setting this value too low may result in
 337 slow ramp-up times for bursty connections.  Setting this value too high
 338 effectively disables the algorithm.
 339 .It tcp.inflight_max
 340 This puts an upper bound on the bandwidth delay product window, in bytes.
 341 This value should not generally be modified but may be used to set a
 342 global per-connection limit on queued data, potentially allowing you to
 343 intentionally set a less then optimum limit to smooth data flow over a
 344 network while still being able to specify huge internal TCP buffers.
 345 .It tcp.inflight_stab
 346 The bandwidth delay product algorithm requires a slightly larger window
 347 then it otherwise calculates for stability.  This parameter determines the
 348 extra window in maximal packets / 10.  The default value of 20 represents
 349 2 maximal packets.  Reducing this value is not recommended but you may
 350 come across a situation with very slow links where the ping time
 351 reduction of the default inflight code is not sufficient.  If this case
 352 occurs you should first try reducing tcp.inflight_min and, if that does not
 353 work, reduce both tcp.inflight_min and tcp.inflight_stab, trying values of
 354 15, 10, or 5 for the latter.  Never use a value less then 5.  Reducing
 355 tcp.inflight_stab can lead to upwards of a 20% underutilization of the link
 356 as well as reducing the algorithm's ability to adapt to changing
 357 situations and should only be done as a last resort.
 358 .El
 359 .Sh ERRORS
 360 A socket operation may fail with one of the following errors returned:
 361 .Bl -tag -width Er
 362 .It Bq Er EISCONN
 363 when trying to establish a connection on a socket which
 364 already has one;
 365 .It Bq Er ENOBUFS
 366 when the system runs out of memory for
 367 an internal data structure;
 368 .It Bq Er ETIMEDOUT
 369 when a connection was dropped
 370 due to excessive retransmissions;
 371 .It Bq Er ECONNRESET
 372 when the remote peer
 373 forces the connection to be closed;
 374 .It Bq Er ECONNREFUSED
 375 when the remote
 376 peer actively refuses connection establishment (usually because
 377 no process is listening to the port);
 378 .It Bq Er EADDRINUSE
 379 when an attempt
 380 is made to create a socket with a port which has already been
 381 allocated;
 382 .It Bq Er EADDRNOTAVAIL
 383 when an attempt is made to create a
 384 socket with a network address for which no network interface
 385 exists.
 386 .It Bq Er EAFNOSUPPORT
 387 when an attempt is made to bind or connect a socket to a multicast
 388 address.
 389 .El
 390 .Sh SEE ALSO
 391 .Xr getsockopt 2 ,
 392 .Xr socket 2 ,
 393 .Xr sysctl 3 ,
 394 .Xr blackhole 4 ,
 395 .Xr inet 4 ,
 396 .Xr intro 4 ,
 397 .Xr ip 4 ,
 398 .Xr ttcp 4
 399 .Rs
 400 .%A V. Jacobson
 401 .%A R. Braden
 402 .%A D. Borman
 403 .%T "TCP Extensions for High Performance"
 404 .%O RFC 1323
 405 .Re
 406 .Rs
 407 .%A R. Braden
 408 .%T "T/TCP \- TCP Extensions for Transactions"
 409 .%O RFC 1644
 410 .Re
 411 .Sh HISTORY
 412 The
 413 .Nm
 414 protocol appeared in
 415 .Bx 4.2 .
 416 The RFC 1323 extensions for window scaling and timestamps were added
 417 in
 418 .Bx 4.4 .