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.3 2005/01/08 09:46:17 hsu 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 .Aq Pa 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 Enable Path MTU Discovery
 269 .It tcp.tcbhashsize
 270 Size of the
 271 .Tn TCP
 272 control-block hashtable
 273 (read-only).
 274 This may be tuned using the kernel option
 275 .Dv TCBHASHSIZE
 276 or by setting
 277 .Va net.inet.tcp.tcbhashsize
 278 in the
 279 .Xr loader 8 .
 280 .It tcp.pcbcount
 281 Number of active process control blocks
 282 (read-only).
 283 .It tcp.syncookies
 284 Determines whether or not syn cookies should be generated for
 285 outbound syn-ack packets.  Syn cookies are a great help during
 286 syn flood attacks, and are enabled by default.
 287 .It tcp.isn_reseed_interval
 288 The interval (in seconds) specifying how often the secret data used in
 289 RFC 1948 initial sequence number calculations should be reseeded.
 290 By default, this variable is set to zero, indicating that
 291 no reseeding will occur.
 292 Reseeding should not be necessary, and will break
 293 .Dv TIME_WAIT
 294 recycling for a few minutes.
 295 .It tcp.inet.tcp.rexmit_{min,slop}
 296 Adjust the retransmit timer calculation for TCP.  The slop is
 297 typically added to the raw calculation to take into account
 298 occasional variances that the SRTT (smoothed round trip time)
 299 is unable to accomodate, while the minimum specifies an
 300 absolute minimum.  While a number of TCP RFCs suggest a 1
 301 second minimum these RFCs tend to focus on streaming behavior
 302 and fail to deal with the fact that a 1 second minimum has severe
 303 detrimental effects over lossy interactive connections, such
 304 as a 802.11b wireless link, and over very fast but lossy
 305 connections for those cases not covered by the fast retransmit
 306 code.  For this reason we suggest changing the slop to 200ms and
 307 setting the minimum to something out of the way, like 20ms,
 308 which gives you an effective minimum of 200ms (similar to Linux).
 309 .It tcp.inflight_enable
 310 Enable
 311 .Tn TCP
 312 bandwidth delay product limiting.  An attempt will be made to calculate
 313 the bandwidth delay product for each individual TCP connection and limit
 314 the amount of inflight data being transmitted to avoid building up
 315 unnecessary packets in the network.  This option is recommended if you
 316 are serving a lot of data over connections with high bandwidth-delay
 317 products, such as modems, GigE links, and fast long-haul WANs, and/or
 318 you have configured your machine to accomodate large TCP windows.  In such
 319 situations, without this option, you may experience high interactive
 320 latencies or packet loss due to the overloading of intermediate routers
 321 and switches.  Note that bandwidth delay product limiting only effects
 322 the transmit side of a TCP connection.
 323 .It tcp.inflight_debug
 324 Enable debugging for the bandwidth delay product algorithm.  This may
 325 default to on (1) so if you enable the algorithm you should probably also
 326 disable debugging by setting this variable to 0.
 327 .It tcp.inflight_min
 328 This puts an lower bound on the bandwidth delay product window, in bytes.
 329 A value of 1024 is typically used for debugging.  6000-16000 is more typical
 330 in a production installation.  Setting this value too low may result in
 331 slow ramp-up times for bursty connections.  Setting this value too high
 332 effectively disables the algorithm.
 333 .It tcp.inflight_max
 334 This puts an upper bound on the bandwidth delay product window, in bytes.
 335 This value should not generally be modified but may be used to set a
 336 global per-connection limit on queued data, potentially allowing you to
 337 intentionally set a less then optimum limit to smooth data flow over a
 338 network while still being able to specify huge internal TCP buffers.
 339 .It tcp.inflight_stab
 340 The bandwidth delay product algorithm requires a slightly larger window
 341 then it otherwise calculates for stability.  This parameter determines the
 342 extra window in maximal packets / 10.  The default value of 20 represents
 343 2 maximal packets.  Reducing this value is not recommended but you may
 344 come across a situation with very slow links where the ping time
 345 reduction of the default inflight code is not sufficient.  If this case
 346 occurs you should first try reducing tcp.inflight_min and, if that does not
 347 work, reduce both tcp.inflight_min and tcp.inflight_stab, trying values of
 348 15, 10, or 5 for the latter.  Never use a value less then 5.  Reducing
 349 tcp.inflight_stab can lead to upwards of a 20% underutilization of the link
 350 as well as reducing the algorithm's ability to adapt to changing
 351 situations and should only be done as a last resort.
 352 .El
 353 .Sh ERRORS
 354 A socket operation may fail with one of the following errors returned:
 355 .Bl -tag -width Er
 356 .It Bq Er EISCONN
 357 when trying to establish a connection on a socket which
 358 already has one;
 359 .It Bq Er ENOBUFS
 360 when the system runs out of memory for
 361 an internal data structure;
 362 .It Bq Er ETIMEDOUT
 363 when a connection was dropped
 364 due to excessive retransmissions;
 365 .It Bq Er ECONNRESET
 366 when the remote peer
 367 forces the connection to be closed;
 368 .It Bq Er ECONNREFUSED
 369 when the remote
 370 peer actively refuses connection establishment (usually because
 371 no process is listening to the port);
 372 .It Bq Er EADDRINUSE
 373 when an attempt
 374 is made to create a socket with a port which has already been
 375 allocated;
 376 .It Bq Er EADDRNOTAVAIL
 377 when an attempt is made to create a
 378 socket with a network address for which no network interface
 379 exists.
 380 .It Bq Er EAFNOSUPPORT
 381 when an attempt is made to bind or connect a socket to a multicast
 382 address.
 383 .El
 384 .Sh SEE ALSO
 385 .Xr getsockopt 2 ,
 386 .Xr socket 2 ,
 387 .Xr sysctl 3 ,
 388 .Xr blackhole 4 ,
 389 .Xr inet 4 ,
 390 .Xr intro 4 ,
 391 .Xr ip 4 ,
 392 .Xr ttcp 4
 393 .Rs
 394 .%A V. Jacobson
 395 .%A R. Braden
 396 .%A D. Borman
 397 .%T "TCP Extensions for High Performance"
 398 .%O RFC 1323
 399 .Re
 400 .Rs
 401 .%A R. Braden
 402 .%T "T/TCP \- TCP Extensions for Transactions"
 403 .%O RFC 1644
 404 .Re
 405 .Sh HISTORY
 406 The
 407 .Nm
 408 protocol appeared in
 409 .Bx 4.2 .
 410 The RFC 1323 extensions for window scaling and timestamps were added
 411 in
 412 .Bx 4.4 .