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. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" From: @(#)tcp.4 8.1 (Berkeley) 6/5/93 35.\" $FreeBSD$ 36.\" 37.Dd August 6, 2018 38.Dt TCP 4 39.Os 40.Sh NAME 41.Nm tcp 42.Nd Internet Transmission Control Protocol 43.Sh SYNOPSIS 44.In sys/types.h 45.In sys/socket.h 46.In netinet/in.h 47.In netinet/tcp.h 48.Ft int 49.Fn socket AF_INET SOCK_STREAM 0 50.Sh DESCRIPTION 51The 52.Tn TCP 53protocol provides reliable, flow-controlled, two-way 54transmission of data. 55It is a byte-stream protocol used to 56support the 57.Dv SOCK_STREAM 58abstraction. 59.Tn TCP 60uses the standard 61Internet address format and, in addition, provides a per-host 62collection of 63.Dq "port addresses" . 64Thus, each address is composed 65of an Internet address specifying the host and network, 66with a specific 67.Tn TCP 68port on the host identifying the peer entity. 69.Pp 70Sockets utilizing the 71.Tn TCP 72protocol are either 73.Dq active 74or 75.Dq passive . 76Active sockets initiate connections to passive 77sockets. 78By default, 79.Tn TCP 80sockets are created active; to create a 81passive socket, the 82.Xr listen 2 83system call must be used 84after binding the socket with the 85.Xr bind 2 86system call. 87Only passive sockets may use the 88.Xr accept 2 89call to accept incoming connections. 90Only active sockets may use the 91.Xr connect 2 92call to initiate connections. 93.Pp 94Passive sockets may 95.Dq underspecify 96their location to match 97incoming connection requests from multiple networks. 98This technique, termed 99.Dq "wildcard addressing" , 100allows a single 101server to provide service to clients on multiple networks. 102To create a socket which listens on all networks, the Internet 103address 104.Dv INADDR_ANY 105must be bound. 106The 107.Tn TCP 108port may still be specified 109at this time; if the port is not specified, the system will assign one. 110Once a connection has been established, the socket's address is 111fixed by the peer entity's location. 112The address assigned to the 113socket is the address associated with the network interface 114through which packets are being transmitted and received. 115Normally, this address corresponds to the peer entity's network. 116.Pp 117.Tn TCP 118supports a number of socket options which can be set with 119.Xr setsockopt 2 120and tested with 121.Xr getsockopt 2 : 122.Bl -tag -width ".Dv TCP_FUNCTION_BLK" 123.It Dv TCP_INFO 124Information about a socket's underlying TCP session may be retrieved 125by passing the read-only option 126.Dv TCP_INFO 127to 128.Xr getsockopt 2 . 129It accepts a single argument: a pointer to an instance of 130.Vt "struct tcp_info" . 131.Pp 132This API is subject to change; consult the source to determine 133which fields are currently filled out by this option. 134.Fx 135specific additions include 136send window size, 137receive window size, 138and 139bandwidth-controlled window space. 140.It Dv TCP_CCALGOOPT 141Set or query congestion control algorithm specific parameters. 142See 143.Xr mod_cc 4 144for details. 145.It Dv TCP_CONGESTION 146Select or query the congestion control algorithm that TCP will use for the 147connection. 148See 149.Xr mod_cc 4 150for details. 151.It Dv TCP_FUNCTION_BLK 152Select or query the set of functions that TCP will use for this connection. 153This allows a user to select an alternate TCP stack. 154The alternate TCP stack must already be loaded in the kernel. 155To list the available TCP stacks, see 156.Va functions_available 157in the 158.Sx MIB Variables 159section further down. 160To list the default TCP stack, see 161.Va functions_default 162in the 163.Sx MIB Variables 164section. 165.It Dv TCP_KEEPINIT 166This 167.Xr setsockopt 2 168option accepts a per-socket timeout argument of 169.Vt "u_int" 170in seconds, for new, non-established 171.Tn TCP 172connections. 173For the global default in milliseconds see 174.Va keepinit 175in the 176.Sx MIB Variables 177section further down. 178.It Dv TCP_KEEPIDLE 179This 180.Xr setsockopt 2 181option accepts an argument of 182.Vt "u_int" 183for the amount of time, in seconds, that the connection must be idle 184before keepalive probes (if enabled) are sent for the connection of this 185socket. 186If set on a listening socket, the value is inherited by the newly created 187socket upon 188.Xr accept 2 . 189For the global default in milliseconds see 190.Va keepidle 191in the 192.Sx MIB Variables 193section further down. 194.It Dv TCP_KEEPINTVL 195This 196.Xr setsockopt 2 197option accepts an argument of 198.Vt "u_int" 199to set the per-socket interval, in seconds, between keepalive probes sent 200to a peer. 201If set on a listening socket, the value is inherited by the newly created 202socket upon 203.Xr accept 2 . 204For the global default in milliseconds see 205.Va keepintvl 206in the 207.Sx MIB Variables 208section further down. 209.It Dv TCP_KEEPCNT 210This 211.Xr setsockopt 2 212option accepts an argument of 213.Vt "u_int" 214and allows a per-socket tuning of the number of probes sent, with no response, 215before the connection will be dropped. 216If set on a listening socket, the value is inherited by the newly created 217socket upon 218.Xr accept 2 . 219For the global default see the 220.Va keepcnt 221in the 222.Sx MIB Variables 223section further down. 224.It Dv TCP_NODELAY 225Under most circumstances, 226.Tn TCP 227sends data when it is presented; 228when outstanding data has not yet been acknowledged, it gathers 229small amounts of output to be sent in a single packet once 230an acknowledgement is received. 231For a small number of clients, such as window systems 232that send a stream of mouse events which receive no replies, 233this packetization may cause significant delays. 234The boolean option 235.Dv TCP_NODELAY 236defeats this algorithm. 237.It Dv TCP_MAXSEG 238By default, a sender- and 239.No receiver- Ns Tn TCP 240will negotiate among themselves to determine the maximum segment size 241to be used for each connection. 242The 243.Dv TCP_MAXSEG 244option allows the user to determine the result of this negotiation, 245and to reduce it if desired. 246.It Dv TCP_NOOPT 247.Tn TCP 248usually sends a number of options in each packet, corresponding to 249various 250.Tn TCP 251extensions which are provided in this implementation. 252The boolean option 253.Dv TCP_NOOPT 254is provided to disable 255.Tn TCP 256option use on a per-connection basis. 257.It Dv TCP_NOPUSH 258By convention, the 259.No sender- Ns Tn TCP 260will set the 261.Dq push 262bit, and begin transmission immediately (if permitted) at the end of 263every user call to 264.Xr write 2 265or 266.Xr writev 2 . 267When this option is set to a non-zero value, 268.Tn TCP 269will delay sending any data at all until either the socket is closed, 270or the internal send buffer is filled. 271.It Dv TCP_MD5SIG 272This option enables the use of MD5 digests (also known as TCP-MD5) 273on writes to the specified socket. 274Outgoing traffic is digested; 275digests on incoming traffic are verified. 276When this option is enabled on a socket, all inbound and outgoing 277TCP segments must be signed with MD5 digests. 278.Pp 279One common use for this in a 280.Fx 281router deployment is to enable 282based routers to interwork with Cisco equipment at peering points. 283Support for this feature conforms to RFC 2385. 284.Pp 285In order for this option to function correctly, it is necessary for the 286administrator to add a tcp-md5 key entry to the system's security 287associations database (SADB) using the 288.Xr setkey 8 289utility. 290This entry can only be specified on a per-host basis at this time. 291.Pp 292If an SADB entry cannot be found for the destination, 293the system does not send any outgoing segments and drops any inbound segments. 294.Pp 295Each dropped segment is taken into account in the TCP protocol statistics. 296.El 297.Pp 298The option level for the 299.Xr setsockopt 2 300call is the protocol number for 301.Tn TCP , 302available from 303.Xr getprotobyname 3 , 304or 305.Dv IPPROTO_TCP . 306All options are declared in 307.In netinet/tcp.h . 308.Pp 309Options at the 310.Tn IP 311transport level may be used with 312.Tn TCP ; 313see 314.Xr ip 4 . 315Incoming connection requests that are source-routed are noted, 316and the reverse source route is used in responding. 317.Pp 318The default congestion control algorithm for 319.Tn TCP 320is 321.Xr cc_newreno 4 . 322Other congestion control algorithms can be made available using the 323.Xr mod_cc 4 324framework. 325.Ss MIB Variables 326The 327.Tn TCP 328protocol implements a number of variables in the 329.Va net.inet.tcp 330branch of the 331.Xr sysctl 3 332MIB. 333.Bl -tag -width ".Va TCPCTL_DO_RFC1323" 334.It Dv TCPCTL_DO_RFC1323 335.Pq Va rfc1323 336Implement the window scaling and timestamp options of RFC 1323 337(default is true). 338.It Dv TCPCTL_MSSDFLT 339.Pq Va mssdflt 340The default value used for the maximum segment size 341.Pq Dq MSS 342when no advice to the contrary is received from MSS negotiation. 343.It Dv TCPCTL_SENDSPACE 344.Pq Va sendspace 345Maximum 346.Tn TCP 347send window. 348.It Dv TCPCTL_RECVSPACE 349.Pq Va recvspace 350Maximum 351.Tn TCP 352receive window. 353.It Va log_in_vain 354Log any connection attempts to ports where there is not a socket 355accepting connections. 356The value of 1 limits the logging to 357.Tn SYN 358(connection establishment) packets only. 359That of 2 results in any 360.Tn TCP 361packets to closed ports being logged. 362Any value unlisted above disables the logging 363(default is 0, i.e., the logging is disabled). 364.It Va msl 365The Maximum Segment Lifetime, in milliseconds, for a packet. 366.It Va keepinit 367Timeout, in milliseconds, for new, non-established 368.Tn TCP 369connections. 370The default is 75000 msec. 371.It Va keepidle 372Amount of time, in milliseconds, that the connection must be idle 373before keepalive probes (if enabled) are sent. 374The default is 7200000 msec (2 hours). 375.It Va keepintvl 376The interval, in milliseconds, between keepalive probes sent to remote 377machines, when no response is received on a 378.Va keepidle 379probe. 380The default is 75000 msec. 381.It Va keepcnt 382Number of probes sent, with no response, before a connection 383is dropped. 384The default is 8 packets. 385.It Va always_keepalive 386Assume that 387.Dv SO_KEEPALIVE 388is set on all 389.Tn TCP 390connections, the kernel will 391periodically send a packet to the remote host to verify the connection 392is still up. 393.It Va icmp_may_rst 394Certain 395.Tn ICMP 396unreachable messages may abort connections in 397.Tn SYN-SENT 398state. 399.It Va do_tcpdrain 400Flush packets in the 401.Tn TCP 402reassembly queue if the system is low on mbufs. 403.It Va blackhole 404If enabled, disable sending of RST when a connection is attempted 405to a port where there is not a socket accepting connections. 406See 407.Xr blackhole 4 . 408.It Va delayed_ack 409Delay ACK to try and piggyback it onto a data packet. 410.It Va delacktime 411Maximum amount of time, in milliseconds, before a delayed ACK is sent. 412.It Va path_mtu_discovery 413Enable Path MTU Discovery. 414.It Va tcbhashsize 415Size of the 416.Tn TCP 417control-block hash table 418(read-only). 419This may be tuned using the kernel option 420.Dv TCBHASHSIZE 421or by setting 422.Va net.inet.tcp.tcbhashsize 423in the 424.Xr loader 8 . 425.It Va pcbcount 426Number of active process control blocks 427(read-only). 428.It Va syncookies 429Determines whether or not 430.Tn SYN 431cookies should be generated for outbound 432.Tn SYN-ACK 433packets. 434.Tn SYN 435cookies are a great help during 436.Tn SYN 437flood attacks, and are enabled by default. 438(See 439.Xr syncookies 4 . ) 440.It Va isn_reseed_interval 441The interval (in seconds) specifying how often the secret data used in 442RFC 1948 initial sequence number calculations should be reseeded. 443By default, this variable is set to zero, indicating that 444no reseeding will occur. 445Reseeding should not be necessary, and will break 446.Dv TIME_WAIT 447recycling for a few minutes. 448.It Va reass.cursegments 449The current total number of segments present in all reassembly queues. 450.It Va reass.maxsegments 451The maximum limit on the total number of segments across all reassembly 452queues. 453The limit can be adjusted as a tunable. 454.It Va reass.maxqueuelen 455The maximum number of segments allowed in each reassembly queue. 456By default, the system chooses a limit based on each TCP connection's 457receive buffer size and maximum segment size (MSS). 458The actual limit applied to a session's reassembly queue will be the lower of 459the system-calculated automatic limit and the user-specified 460.Va reass.maxqueuelen 461limit. 462.It Va rexmit_min , rexmit_slop 463Adjust the retransmit timer calculation for 464.Tn TCP . 465The slop is 466typically added to the raw calculation to take into account 467occasional variances that the 468.Tn SRTT 469(smoothed round-trip time) 470is unable to accommodate, while the minimum specifies an 471absolute minimum. 472While a number of 473.Tn TCP 474RFCs suggest a 1 475second minimum, these RFCs tend to focus on streaming behavior, 476and fail to deal with the fact that a 1 second minimum has severe 477detrimental effects over lossy interactive connections, such 478as a 802.11b wireless link, and over very fast but lossy 479connections for those cases not covered by the fast retransmit 480code. 481For this reason, we use 200ms of slop and a near-0 482minimum, which gives us an effective minimum of 200ms (similar to 483.Tn Linux ) . 484.It Va initcwnd_segments 485Enable the ability to specify initial congestion window in number of segments. 486The default value is 10 as suggested by RFC 6928. 487Changing the value on fly would not affect connections using congestion window 488from the hostcache. 489Caution: 490This regulates the burst of packets allowed to be sent in the first RTT. 491The value should be relative to the link capacity. 492Start with small values for lower-capacity links. 493Large bursts can cause buffer overruns and packet drops if routers have small 494buffers or the link is experiencing congestion. 495.It Va rfc3042 496Enable the Limited Transmit algorithm as described in RFC 3042. 497It helps avoid timeouts on lossy links and also when the congestion window 498is small, as happens on short transfers. 499.It Va rfc3390 500Enable support for RFC 3390, which allows for a variable-sized 501starting congestion window on new connections, depending on the 502maximum segment size. 503This helps throughput in general, but 504particularly affects short transfers and high-bandwidth large 505propagation-delay connections. 506.It Va sack.enable 507Enable support for RFC 2018, TCP Selective Acknowledgment option, 508which allows the receiver to inform the sender about all successfully 509arrived segments, allowing the sender to retransmit the missing segments 510only. 511.It Va sack.maxholes 512Maximum number of SACK holes per connection. 513Defaults to 128. 514.It Va sack.globalmaxholes 515Maximum number of SACK holes per system, across all connections. 516Defaults to 65536. 517.It Va maxtcptw 518When a TCP connection enters the 519.Dv TIME_WAIT 520state, its associated socket structure is freed, since it is of 521negligible size and use, and a new structure is allocated to contain a 522minimal amount of information necessary for sustaining a connection in 523this state, called the compressed TCP TIME_WAIT state. 524Since this structure is smaller than a socket structure, it can save 525a significant amount of system memory. 526The 527.Va net.inet.tcp.maxtcptw 528MIB variable controls the maximum number of these structures allocated. 529By default, it is initialized to 530.Va kern.ipc.maxsockets 531/ 5. 532.It Va nolocaltimewait 533Suppress creating of compressed TCP TIME_WAIT states for connections in 534which both endpoints are local. 535.It Va fast_finwait2_recycle 536Recycle 537.Tn TCP 538.Dv FIN_WAIT_2 539connections faster when the socket is marked as 540.Dv SBS_CANTRCVMORE 541(no user process has the socket open, data received on 542the socket cannot be read). 543The timeout used here is 544.Va finwait2_timeout . 545.It Va finwait2_timeout 546Timeout to use for fast recycling of 547.Tn TCP 548.Dv FIN_WAIT_2 549connections. 550Defaults to 60 seconds. 551.It Va ecn.enable 552Enable support for TCP Explicit Congestion Notification (ECN). 553ECN allows a TCP sender to reduce the transmission rate in order to 554avoid packet drops. 555Settings: 556.Bl -tag -compact 557.It 0 558Disable ECN. 559.It 1 560Allow incoming connections to request ECN. 561Outgoing connections will request ECN. 562.It 2 563Allow incoming connections to request ECN. 564Outgoing connections will not request ECN. 565.El 566.It Va ecn.maxretries 567Number of retries (SYN or SYN/ACK retransmits) before disabling ECN on a 568specific connection. 569This is needed to help with connection establishment 570when a broken firewall is in the network path. 571.It Va pmtud_blackhole_detection 572Turn on automatic path MTU blackhole detection. 573In case of retransmits OS will 574lower the MSS to check if it's MTU problem. 575If current MSS is greater than 576configured value to try, it will be set to configured value, otherwise, 577MSS will be set to default values 578.Po Va net.inet.tcp.mssdflt 579and 580.Va net.inet.tcp.v6mssdflt 581.Pc . 582.It Va pmtud_blackhole_mss 583MSS to try for IPv4 if PMTU blackhole detection is turned on. 584.It Va v6pmtud_blackhole_mss 585MSS to try for IPv6 if PMTU blackhole detection is turned on. 586.It Va pmtud_blackhole_activated 587Number of times configured values were used in an attempt to downshift. 588.It Va pmtud_blackhole_activated_min_mss 589Number of times default MSS was used in an attempt to downshift. 590.It Va pmtud_blackhole_failed 591Number of connections for which retransmits continued even after MSS 592downshift. 593.It Va functions_available 594List of available TCP function blocks (TCP stacks). 595.It Va functions_default 596The default TCP function block (TCP stack). 597.It Va functions_inherit_listen_socket_stack 598Determines whether to inherit listen socket's tcp stack or use the current 599system default tcp stack, as defined by 600.Va functions_default 601.Pc . 602Default is true. 603.It Va insecure_rst 604Use criteria defined in RFC793 instead of RFC5961 for accepting RST segments. 605Default is false. 606.It Va insecure_syn 607Use criteria defined in RFC793 instead of RFC5961 for accepting SYN segments. 608Default is false. 609.El 610.Sh ERRORS 611A socket operation may fail with one of the following errors returned: 612.Bl -tag -width Er 613.It Bq Er EISCONN 614when trying to establish a connection on a socket which 615already has one; 616.It Bo Er ENOBUFS Bc or Bo Er ENOMEM Bc 617when the system runs out of memory for 618an internal data structure; 619.It Bq Er ETIMEDOUT 620when a connection was dropped 621due to excessive retransmissions; 622.It Bq Er ECONNRESET 623when the remote peer 624forces the connection to be closed; 625.It Bq Er ECONNREFUSED 626when the remote 627peer actively refuses connection establishment (usually because 628no process is listening to the port); 629.It Bq Er EADDRINUSE 630when an attempt 631is made to create a socket with a port which has already been 632allocated; 633.It Bq Er EADDRNOTAVAIL 634when an attempt is made to create a 635socket with a network address for which no network interface 636exists; 637.It Bq Er EAFNOSUPPORT 638when an attempt is made to bind or connect a socket to a multicast 639address. 640.It Bq Er EINVAL 641when trying to change TCP function blocks at an invalid point in the session; 642.It Bq Er ENOENT 643when trying to use a TCP function block that is not available; 644.El 645.Sh SEE ALSO 646.Xr getsockopt 2 , 647.Xr socket 2 , 648.Xr sysctl 3 , 649.Xr blackhole 4 , 650.Xr inet 4 , 651.Xr intro 4 , 652.Xr ip 4 , 653.Xr mod_cc 4 , 654.Xr siftr 4 , 655.Xr syncache 4 , 656.Xr setkey 8 , 657.Xr tcp_functions 9 658.Rs 659.%A "V. Jacobson" 660.%A "R. Braden" 661.%A "D. Borman" 662.%T "TCP Extensions for High Performance" 663.%O "RFC 1323" 664.Re 665.Rs 666.%A "A. Heffernan" 667.%T "Protection of BGP Sessions via the TCP MD5 Signature Option" 668.%O "RFC 2385" 669.Re 670.Rs 671.%A "K. Ramakrishnan" 672.%A "S. Floyd" 673.%A "D. Black" 674.%T "The Addition of Explicit Congestion Notification (ECN) to IP" 675.%O "RFC 3168" 676.Re 677.Sh HISTORY 678The 679.Tn TCP 680protocol appeared in 681.Bx 4.2 . 682The RFC 1323 extensions for window scaling and timestamps were added 683in 684.Bx 4.4 . 685The 686.Dv TCP_INFO 687option was introduced in 688.Tn Linux 2.6 689and is 690.Em subject to change . 691