share/man/man4/tcp.4

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.
   3 .\" Copyright (c) 2010-2011 The FreeBSD Foundation
   4 .\" All rights reserved.
   5 .\"
   6 .\" Portions of this documentation were written at the Centre for Advanced
   7 .\" Internet Architectures, Swinburne University of Technology, Melbourne,
   8 .\" Australia by David Hayes under sponsorship from the FreeBSD Foundation.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"     This product includes software developed by the University of
  21 .\"     California, Berkeley and its contributors.
  22 .\" 4. Neither the name of the University nor the names of its contributors
  23 .\"    may be used to endorse or promote products derived from this software
  24 .\"    without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  29 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  36 .\" SUCH DAMAGE.
  37 .\"
  38 .\"     From: @(#)tcp.4 8.1 (Berkeley) 6/5/93
  39 .\" $FreeBSD$
  40 .\"
  41 .Dd November 14, 2011
  42 .Dt TCP 4
  43 .Os
  44 .Sh NAME
  45 .Nm tcp
  46 .Nd Internet Transmission Control Protocol
  47 .Sh SYNOPSIS
  48 .In sys/types.h
  49 .In sys/socket.h
  50 .In netinet/in.h
  51 .Ft int
  52 .Fn socket AF_INET SOCK_STREAM 0
  53 .Sh DESCRIPTION
  54 The
  55 .Tn TCP
  56 protocol provides reliable, flow-controlled, two-way
  57 transmission of data.
  58 It is a byte-stream protocol used to
  59 support the
  60 .Dv SOCK_STREAM
  61 abstraction.
  62 .Tn TCP
  63 uses the standard
  64 Internet address format and, in addition, provides a per-host
  65 collection of
  66 .Dq "port addresses" .
  67 Thus, each address is composed
  68 of an Internet address specifying the host and network,
  69 with a specific
  70 .Tn TCP
  71 port on the host identifying the peer entity.
  72 .Pp
  73 Sockets utilizing the
  74 .Tn TCP
  75 protocol are either
  76 .Dq active
  77 or
  78 .Dq passive .
  79 Active sockets initiate connections to passive
  80 sockets.
  81 By default,
  82 .Tn TCP
  83 sockets are created active; to create a
  84 passive socket, the
  85 .Xr listen 2
  86 system call must be used
  87 after binding the socket with the
  88 .Xr bind 2
  89 system call.
  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 Passive sockets may
  98 .Dq underspecify
  99 their location to match
 100 incoming connection requests from multiple networks.
 101 This technique, termed
 102 .Dq "wildcard addressing" ,
 103 allows a single
 104 server to provide service to clients on multiple networks.
 105 To create a socket which listens on all networks, the Internet
 106 address
 107 .Dv INADDR_ANY
 108 must be bound.
 109 The
 110 .Tn TCP
 111 port may still be specified
 112 at this time; if the port is not specified, the system will assign one.
 113 Once a connection has been established, the socket's address is
 114 fixed by the peer entity's location.
 115 The address assigned to the
 116 socket is the address associated with the network interface
 117 through which packets are being transmitted and received.
 118 Normally, this address corresponds to the peer entity's network.
 119 .Pp
 120 .Tn TCP
 121 supports a number of socket options which can be set with
 122 .Xr setsockopt 2
 123 and tested with
 124 .Xr getsockopt 2 :
 125 .Bl -tag -width ".Dv TCP_CONGESTION"
 126 .It Dv TCP_INFO
 127 Information about a socket's underlying TCP session may be retrieved
 128 by passing the read-only option
 129 .Dv TCP_INFO
 130 to
 131 .Xr getsockopt 2 .
 132 It accepts a single argument: a pointer to an instance of
 133 .Vt "struct tcp_info" .
 134 .Pp
 135 This API is subject to change; consult the source to determine
 136 which fields are currently filled out by this option.
 137 .Fx
 138 specific additions include
 139 send window size,
 140 receive window size,
 141 and
 142 bandwidth-controlled window space.
 143 .It Dv TCP_CONGESTION
 144 Select or query the congestion control algorithm that TCP will use for the
 145 connection.
 146 See
 147 .Xr mod_cc 4
 148 for details.
 149 .It Dv TCP_NODELAY
 150 Under most circumstances,
 151 .Tn TCP
 152 sends data when it is presented;
 153 when outstanding data has not yet been acknowledged, it gathers
 154 small amounts of output to be sent in a single packet once
 155 an acknowledgement is received.
 156 For a small number of clients, such as window systems
 157 that send a stream of mouse events which receive no replies,
 158 this packetization may cause significant delays.
 159 The boolean option
 160 .Dv TCP_NODELAY
 161 defeats this algorithm.
 162 .It Dv TCP_MAXSEG
 163 By default, a sender- and
 164 .No receiver- Ns Tn TCP
 165 will negotiate among themselves to determine the maximum segment size
 166 to be used for each connection.
 167 The
 168 .Dv TCP_MAXSEG
 169 option allows the user to determine the result of this negotiation,
 170 and to reduce it if desired.
 171 .It Dv TCP_NOOPT
 172 .Tn TCP
 173 usually sends a number of options in each packet, corresponding to
 174 various
 175 .Tn TCP
 176 extensions which are provided in this implementation.
 177 The boolean option
 178 .Dv TCP_NOOPT
 179 is provided to disable
 180 .Tn TCP
 181 option use on a per-connection basis.
 182 .It Dv TCP_NOPUSH
 183 By convention, the
 184 .No sender- Ns Tn TCP
 185 will set the
 186 .Dq push
 187 bit, and begin transmission immediately (if permitted) at the end of
 188 every user call to
 189 .Xr write 2
 190 or
 191 .Xr writev 2 .
 192 When this option is set to a non-zero value,
 193 .Tn TCP
 194 will delay sending any data at all until either the socket is closed,
 195 or the internal send buffer is filled.
 196 .It Dv TCP_MD5SIG
 197 This option enables the use of MD5 digests (also known as TCP-MD5)
 198 on writes to the specified socket.
 199 In the current release, only outgoing traffic is digested;
 200 digests on incoming traffic are not verified.
 201 The current default behavior for the system is to respond to a system
 202 advertising this option with TCP-MD5; this may change.
 203 .Pp
 204 One common use for this in a
 205 .Fx
 206 router deployment is to enable
 207 based routers to interwork with Cisco equipment at peering points.
 208 Support for this feature conforms to RFC 2385.
 209 Only IPv4
 210 .Pq Dv AF_INET
 211 sessions are supported.
 212 .Pp
 213 In order for this option to function correctly, it is necessary for the
 214 administrator to add a tcp-md5 key entry to the system's security
 215 associations database (SADB) using the
 216 .Xr setkey 8
 217 utility.
 218 This entry must have an SPI of 0x1000 and can therefore only be specified
 219 on a per-host basis at this time.
 220 .Pp
 221 If an SADB entry cannot be found for the destination, the outgoing traffic
 222 will have an invalid digest option prepended, and the following error message
 223 will be visible on the system console:
 224 .Em "tcp_signature_compute: SADB lookup failed for %d.%d.%d.%d" .
 225 .El
 226 .Pp
 227 The option level for the
 228 .Xr setsockopt 2
 229 call is the protocol number for
 230 .Tn TCP ,
 231 available from
 232 .Xr getprotobyname 3 ,
 233 or
 234 .Dv IPPROTO_TCP .
 235 All options are declared in
 236 .In netinet/tcp.h .
 237 .Pp
 238 Options at the
 239 .Tn IP
 240 transport level may be used with
 241 .Tn TCP ;
 242 see
 243 .Xr ip 4 .
 244 Incoming connection requests that are source-routed are noted,
 245 and the reverse source route is used in responding.
 246 .Pp
 247 The default congestion control algorithm for
 248 .Tn TCP
 249 is
 250 .Xr cc_newreno 4 .
 251 Other congestion control algorithms can be made available using the
 252 .Xr mod_cc 4
 253 framework.
 254 .Ss MIB Variables
 255 The
 256 .Tn TCP
 257 protocol implements a number of variables in the
 258 .Va net.inet.tcp
 259 branch of the
 260 .Xr sysctl 3
 261 MIB.
 262 .Bl -tag -width ".Va TCPCTL_DO_RFC1323"
 263 .It Dv TCPCTL_DO_RFC1323
 264 .Pq Va rfc1323
 265 Implement the window scaling and timestamp options of RFC 1323
 266 (default is true).
 267 .It Dv TCPCTL_MSSDFLT
 268 .Pq Va mssdflt
 269 The default value used for the maximum segment size
 270 .Pq Dq MSS
 271 when no advice to the contrary is received from MSS negotiation.
 272 .It Dv TCPCTL_SENDSPACE
 273 .Pq Va sendspace
 274 Maximum
 275 .Tn TCP
 276 send window.
 277 .It Dv TCPCTL_RECVSPACE
 278 .Pq Va recvspace
 279 Maximum
 280 .Tn TCP
 281 receive window.
 282 .It Va log_in_vain
 283 Log any connection attempts to ports where there is not a socket
 284 accepting connections.
 285 The value of 1 limits the logging to
 286 .Tn SYN
 287 (connection establishment) packets only.
 288 That of 2 results in any
 289 .Tn TCP
 290 packets to closed ports being logged.
 291 Any value unlisted above disables the logging
 292 (default is 0, i.e., the logging is disabled).
 293 .It Va msl
 294 The Maximum Segment Lifetime, in milliseconds, for a packet.
 295 .It Va keepinit
 296 Timeout, in milliseconds, for new, non-established
 297 .Tn TCP
 298 connections.
 299 .It Va keepidle
 300 Amount of time, in milliseconds, that the connection must be idle
 301 before keepalive probes (if enabled) are sent.
 302 .It Va keepintvl
 303 The interval, in milliseconds, between keepalive probes sent to remote
 304 machines, when no response is received on a
 305 .Va keepidle
 306 probe.
 307 After
 308 .Dv TCPTV_KEEPCNT
 309 (default 8) probes are sent, with no response, the connection is dropped.
 310 .It Va always_keepalive
 311 Assume that
 312 .Dv SO_KEEPALIVE
 313 is set on all
 314 .Tn TCP
 315 connections, the kernel will
 316 periodically send a packet to the remote host to verify the connection
 317 is still up.
 318 .It Va icmp_may_rst
 319 Certain
 320 .Tn ICMP
 321 unreachable messages may abort connections in
 322 .Tn SYN-SENT
 323 state.
 324 .It Va do_tcpdrain
 325 Flush packets in the
 326 .Tn TCP
 327 reassembly queue if the system is low on mbufs.
 328 .It Va blackhole
 329 If enabled, disable sending of RST when a connection is attempted
 330 to a port where there is not a socket accepting connections.
 331 See
 332 .Xr blackhole 4 .
 333 .It Va delayed_ack
 334 Delay ACK to try and piggyback it onto a data packet.
 335 .It Va delacktime
 336 Maximum amount of time, in milliseconds, before a delayed ACK is sent.
 337 .It Va path_mtu_discovery
 338 Enable Path MTU Discovery.
 339 .It Va tcbhashsize
 340 Size of the
 341 .Tn TCP
 342 control-block hash table
 343 (read-only).
 344 This may be tuned using the kernel option
 345 .Dv TCBHASHSIZE
 346 or by setting
 347 .Va net.inet.tcp.tcbhashsize
 348 in the
 349 .Xr loader 8 .
 350 .It Va pcbcount
 351 Number of active process control blocks
 352 (read-only).
 353 .It Va syncookies
 354 Determines whether or not
 355 .Tn SYN
 356 cookies should be generated for outbound
 357 .Tn SYN-ACK
 358 packets.
 359 .Tn SYN
 360 cookies are a great help during
 361 .Tn SYN
 362 flood attacks, and are enabled by default.
 363 (See
 364 .Xr syncookies 4 . )
 365 .It Va isn_reseed_interval
 366 The interval (in seconds) specifying how often the secret data used in
 367 RFC 1948 initial sequence number calculations should be reseeded.
 368 By default, this variable is set to zero, indicating that
 369 no reseeding will occur.
 370 Reseeding should not be necessary, and will break
 371 .Dv TIME_WAIT
 372 recycling for a few minutes.
 373 .It Va rexmit_min , rexmit_slop
 374 Adjust the retransmit timer calculation for
 375 .Tn TCP .
 376 The slop is
 377 typically added to the raw calculation to take into account
 378 occasional variances that the
 379 .Tn SRTT
 380 (smoothed round-trip time)
 381 is unable to accommodate, while the minimum specifies an
 382 absolute minimum.
 383 While a number of
 384 .Tn TCP
 385 RFCs suggest a 1
 386 second minimum, these RFCs tend to focus on streaming behavior,
 387 and fail to deal with the fact that a 1 second minimum has severe
 388 detrimental effects over lossy interactive connections, such
 389 as a 802.11b wireless link, and over very fast but lossy
 390 connections for those cases not covered by the fast retransmit
 391 code.
 392 For this reason, we use 200ms of slop and a near-0
 393 minimum, which gives us an effective minimum of 200ms (similar to
 394 .Tn Linux ) .
 395 .It Va rfc3042
 396 Enable the Limited Transmit algorithm as described in RFC 3042.
 397 It helps avoid timeouts on lossy links and also when the congestion window
 398 is small, as happens on short transfers.
 399 .It Va rfc3390
 400 Enable support for RFC 3390, which allows for a variable-sized
 401 starting congestion window on new connections, depending on the
 402 maximum segment size.
 403 This helps throughput in general, but
 404 particularly affects short transfers and high-bandwidth large
 405 propagation-delay connections.
 406 .It Va sack.enable
 407 Enable support for RFC 2018, TCP Selective Acknowledgment option,
 408 which allows the receiver to inform the sender about all successfully
 409 arrived segments, allowing the sender to retransmit the missing segments
 410 only.
 411 .It Va sack.maxholes
 412 Maximum number of SACK holes per connection.
 413 Defaults to 128.
 414 .It Va sack.globalmaxholes
 415 Maximum number of SACK holes per system, across all connections.
 416 Defaults to 65536.
 417 .It Va maxtcptw
 418 When a TCP connection enters the
 419 .Dv TIME_WAIT
 420 state, its associated socket structure is freed, since it is of
 421 negligible size and use, and a new structure is allocated to contain a
 422 minimal amount of information necessary for sustaining a connection in
 423 this state, called the compressed TCP TIME_WAIT state.
 424 Since this structure is smaller than a socket structure, it can save
 425 a significant amount of system memory.
 426 The
 427 .Va net.inet.tcp.maxtcptw
 428 MIB variable controls the maximum number of these structures allocated.
 429 By default, it is initialized to
 430 .Va kern.ipc.maxsockets
 431 / 5.
 432 .It Va nolocaltimewait
 433 Suppress creating of compressed TCP TIME_WAIT states for connections in
 434 which both endpoints are local.
 435 .It Va fast_finwait2_recycle
 436 Recycle
 437 .Tn TCP
 438 .Dv FIN_WAIT_2
 439 connections faster when the socket is marked as
 440 .Dv SBS_CANTRCVMORE
 441 (no user process has the socket open, data received on
 442 the socket cannot be read).
 443 The timeout used here is
 444 .Va finwait2_timeout .
 445 .It Va finwait2_timeout
 446 Timeout to use for fast recycling of
 447 .Tn TCP
 448 .Dv FIN_WAIT_2
 449 connections.
 450 Defaults to 60 seconds.
 451 .It Va ecn.enable
 452 Enable support for TCP Explicit Congestion Notification (ECN).
 453 ECN allows a TCP sender to reduce the transmission rate in order to
 454 avoid packet drops.
 455 .It Va ecn.maxretries
 456 Number of retries (SYN or SYN/ACK retransmits) before disabling ECN on a
 457 specific connection. This is needed to help with connection establishment
 458 when a broken firewall is in the network path.
 459 .El
 460 .Sh ERRORS
 461 A socket operation may fail with one of the following errors returned:
 462 .Bl -tag -width Er
 463 .It Bq Er EISCONN
 464 when trying to establish a connection on a socket which
 465 already has one;
 466 .It Bq Er ENOBUFS
 467 when the system runs out of memory for
 468 an internal data structure;
 469 .It Bq Er ETIMEDOUT
 470 when a connection was dropped
 471 due to excessive retransmissions;
 472 .It Bq Er ECONNRESET
 473 when the remote peer
 474 forces the connection to be closed;
 475 .It Bq Er ECONNREFUSED
 476 when the remote
 477 peer actively refuses connection establishment (usually because
 478 no process is listening to the port);
 479 .It Bq Er EADDRINUSE
 480 when an attempt
 481 is made to create a socket with a port which has already been
 482 allocated;
 483 .It Bq Er EADDRNOTAVAIL
 484 when an attempt is made to create a
 485 socket with a network address for which no network interface
 486 exists;
 487 .It Bq Er EAFNOSUPPORT
 488 when an attempt is made to bind or connect a socket to a multicast
 489 address.
 490 .El
 491 .Sh SEE ALSO
 492 .Xr getsockopt 2 ,
 493 .Xr socket 2 ,
 494 .Xr sysctl 3 ,
 495 .Xr blackhole 4 ,
 496 .Xr inet 4 ,
 497 .Xr intro 4 ,
 498 .Xr ip 4 ,
 499 .Xr mod_cc 4 ,
 500 .Xr syncache 4 ,
 501 .Xr setkey 8
 502 .Rs
 503 .%A "V. Jacobson"
 504 .%A "R. Braden"
 505 .%A "D. Borman"
 506 .%T "TCP Extensions for High Performance"
 507 .%O "RFC 1323"
 508 .Re
 509 .Rs
 510 .%A "A. Heffernan"
 511 .%T "Protection of BGP Sessions via the TCP MD5 Signature Option"
 512 .%O "RFC 2385"
 513 .Re
 514 .Rs
 515 .%A "K. Ramakrishnan"
 516 .%A "S. Floyd"
 517 .%A "D. Black"
 518 .%T "The Addition of Explicit Congestion Notification (ECN) to IP"
 519 .%O "RFC 3168"
 520 .Re
 521 .Sh HISTORY
 522 The
 523 .Tn TCP
 524 protocol appeared in
 525 .Bx 4.2 .
 526 The RFC 1323 extensions for window scaling and timestamps were added
 527 in
 528 .Bx 4.4 .
 529 The
 530 .Dv TCP_INFO
 531 option was introduced in
 532 .Tn Linux 2.6
 533 and is
 534 .Em subject to change .