Debian Codegraph @

upstream/debian-unstable/man7/tcp.7

raw
1 .\" Copyright 1999, Andi Kleen <[email protected]>
2 .\" Copyright 2008, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-1-para
6 .\"
7 .\" FIXME The following need to be documented
8 .\" TCP_MD5SIG (2.6.20)
9 .\" commit cfb6eeb4c860592edd123fdea908d23c6ad1c7dc
10 .\" Author was [email protected]
11 .\" Needs CONFIG_TCP_MD5SIG
12 .\" From net/inet/Kconfig:
13 .\" bool "TCP: MD5 Signature Option support (RFC2385) (EXPERIMENTAL)"
14 .\" RFC2385 specifies a method of giving MD5 protection to TCP sessions.
15 .\" Its main (only?) use is to protect BGP sessions between core routers
16 .\" on the Internet.
17 .\"
18 .\" There is a TCP_MD5SIG option documented in FreeBSD's tcp(4),
19 .\" but probably many details are different on Linux
20 .\" http://thread.gmane.org/gmane.linux.network/47490
21 .\" http://www.daemon-systems.org/man/tcp.4.html
22 .\" http://article.gmane.org/gmane.os.netbsd.devel.network/3767/match=tcp_md5sig+freebsd
23 .\"
24 .\" TCP_COOKIE_TRANSACTIONS (2.6.33)
25 .\" commit 519855c508b9a17878c0977a3cdefc09b59b30df
26 .\" Author: William Allen Simpson <[email protected]>
27 .\" commit e56fb50f2b7958b931c8a2fc0966061b3f3c8f3a
28 .\" Author: William Allen Simpson <[email protected]>
29 .\"
30 .\" REMOVED in Linux 3.10
31 .\" commit 1a2c6181c4a1922021b4d7df373bba612c3e5f04
32 .\" Author: Christoph Paasch <[email protected]>
33 .\"
34 .\" TCP_THIN_LINEAR_TIMEOUTS (2.6.34)
35 .\" commit 36e31b0af58728071e8023cf8e20c5166b700717
36 .\" Author: Andreas Petlund <[email protected]>
37 .\"
38 .\" TCP_THIN_DUPACK (2.6.34)
39 .\" commit 7e38017557bc0b87434d184f8804cadb102bb903
40 .\" Author: Andreas Petlund <[email protected]>
41 .\"
42 .\" TCP_REPAIR (3.5)
43 .\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37
44 .\" Author: Pavel Emelyanov <[email protected]>
45 .\" See also
46 .\" http://criu.org/TCP_connection
47 .\" https://lwn.net/Articles/495304/
48 .\"
49 .\" TCP_REPAIR_QUEUE (3.5)
50 .\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37
51 .\" Author: Pavel Emelyanov <[email protected]>
52 .\"
53 .\" TCP_QUEUE_SEQ (3.5)
54 .\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37
55 .\" Author: Pavel Emelyanov <[email protected]>
56 .\"
57 .\" TCP_REPAIR_OPTIONS (3.5)
58 .\" commit b139ba4e90dccbf4cd4efb112af96a5c9e0b098c
59 .\" Author: Pavel Emelyanov <[email protected]>
60 .\"
61 .\" TCP_FASTOPEN (3.6)
62 .\" (Fast Open server side implementation completed in Linux 3.7)
63 .\" http://lwn.net/Articles/508865/
64 .\"
65 .\" TCP_TIMESTAMP (3.9)
66 .\" commit 93be6ce0e91b6a94783e012b1857a347a5e6e9f2
67 .\" Author: Andrey Vagin <[email protected]>
68 .\"
69 .\" TCP_NOTSENT_LOWAT (3.12)
70 .\" commit c9bee3b7fdecb0c1d070c7b54113b3bdfb9a3d36
71 .\" Author: Eric Dumazet <[email protected]>
72 .\"
73 .\" TCP_CC_INFO (4.1)
74 .\" commit 6e9250f59ef9efb932c84850cd221f22c2a03c4a
75 .\" Author: Eric Dumazet <[email protected]>
76 .\"
77 .TH tcp 7 2026-04-19 "Linux man-pages 6.18"
78 .SH NAME
79 tcp \- TCP protocol
80 .SH SYNOPSIS
81 .nf
82 .B #include <sys/socket.h>
83 .B #include <netinet/in.h>
84 .B #include <netinet/tcp.h>
85 .P
86 .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);"
87 .fi
88 .SH DESCRIPTION
89 This is an implementation of the TCP protocol defined in
90 RFC\ 793, RFC\ 1122 and RFC\ 2001 with the NewReno and SACK
91 extensions.
92 It provides a reliable, stream-oriented,
93 full-duplex connection between two sockets on top of
94 .BR ip (7),
95 for both v4 and v6 versions.
96 TCP guarantees that the data arrives in order and
97 retransmits lost packets.
98 It generates and checks a per-packet checksum to catch
99 transmission errors.
100 TCP does not preserve record boundaries.
101 .P
102 A newly created TCP socket has no remote or local address and is not
103 fully specified.
104 To create an outgoing TCP connection use
105 .BR connect (2)
106 to establish a connection to another TCP socket.
107 To receive new incoming connections, first
108 .BR bind (2)
109 the socket to a local address and port and then call
110 .BR listen (2)
111 to put the socket into the listening state.
112 After that a new socket for each incoming connection can be accepted using
113 .BR accept (2).
114 A socket which has had
115 .BR accept (2)
116 or
117 .BR connect (2)
118 successfully called on it is fully specified and may transmit data.
119 Data cannot be transmitted on listening or not yet connected sockets.
120 .P
121 Linux supports RFC\ 1323 TCP high performance
122 extensions.
123 These include Protection Against Wrapped
124 Sequence Numbers (PAWS), Window Scaling and Timestamps.
125 Window scaling allows the use
126 of large (> 64\ kB) TCP windows in order to support links with high
127 latency or bandwidth.
128 To make use of them, the send and receive buffer sizes must be increased.
129 They can be set globally with the
130 .I /proc/sys/net/ipv4/tcp_wmem
131 and
132 .I /proc/sys/net/ipv4/tcp_rmem
133 files, or on individual sockets by using the
134 .B SO_SNDBUF
135 and
136 .B SO_RCVBUF
137 socket options with the
138 .BR setsockopt (2)
139 call.
140 .P
141 The maximum sizes for socket buffers declared via the
142 .B SO_SNDBUF
143 and
144 .B SO_RCVBUF
145 mechanisms are limited by the values in the
146 .I /proc/sys/net/core/rmem_max
147 and
148 .I /proc/sys/net/core/wmem_max
149 files.
150 Note that TCP actually allocates twice the size of
151 the buffer requested in the
152 .BR setsockopt (2)
153 call, and so a succeeding
154 .BR getsockopt (2)
155 call will not return the same size of buffer as requested in the
156 .BR setsockopt (2)
157 call.
158 TCP uses the extra space for administrative purposes and internal
159 kernel structures, and the
160 .I /proc
161 file values reflect the
162 larger sizes compared to the actual TCP windows.
163 On individual connections, the socket buffer size must be set prior to the
164 .BR listen (2)
165 or
166 .BR connect (2)
167 calls in order to have it take effect.
168 See
169 .BR socket (7)
170 for more information.
171 .P
172 TCP supports urgent data.
173 Urgent data is used to signal the
174 receiver that some important message is part of the data
175 stream and that it should be processed as soon as possible.
176 To send urgent data specify the
177 .B MSG_OOB
178 option to
179 .BR send (2).
180 When urgent data is received, the kernel sends a
181 .B SIGURG
182 signal to the process or process group that has been set as the
183 socket "owner" using the
184 .B SIOCSPGRP
185 or
186 .B FIOSETOWN
187 ioctls (or the POSIX.1-specified
188 .BR fcntl (2)
189 .B F_SETOWN
190 operation).
191 When the
192 .B SO_OOBINLINE
193 socket option is enabled, urgent data is put into the normal
194 data stream (a program can test for its location using the
195 .B SIOCATMARK
196 ioctl described below),
197 otherwise it can be received only when the
198 .B MSG_OOB
199 flag is set for
200 .BR recv (2)
201 or
202 .BR recvmsg (2).
203 .P
204 When out-of-band data is present,
205 .BR select (2)
206 indicates the file descriptor as having an exceptional condition and
207 .I poll (2)
208 indicates a
209 .B POLLPRI
210 event.
211 .P
212 Linux 2.4 introduced a number of changes for improved
213 throughput and scaling, as well as enhanced functionality.
214 Some of these features include support for zero-copy
215 .BR sendfile (2),
216 Explicit Congestion Notification, new
217 management of TIME_WAIT sockets, keep-alive socket options
218 and support for Duplicate SACK extensions.
219 .SS Address formats
220 TCP is built on top of IP (see
221 .BR ip (7)).
222 The address formats defined by
223 .BR ip (7)
224 apply to TCP.
225 TCP supports point-to-point communication only;
226 broadcasting and multicasting are not
227 supported.
228 .SS /proc interfaces
229 System-wide TCP parameter settings can be accessed by files in the directory
230 .IR /proc/sys/net/ipv4/ .
231 In addition, most IP
232 .I /proc
233 interfaces also apply to TCP;
234 see
235 .BR ip (7).
236 Variables described as
237 .I Boolean
238 take an integer value, with a nonzero value ("true") meaning that
239 the corresponding option is enabled, and a zero value ("false")
240 meaning that the option is disabled.
241 .TP
242 .IR tcp_abc " (Integer; default: 0; Linux 2.6.15 to Linux 3.8)"
243 .\" Since Linux 2.6.15; removed in Linux 3.9
244 .\" commit ca2eb5679f8ddffff60156af42595df44a315ef0
245 Control the Appropriate Byte Count (ABC), defined in RFC 3465.
246 ABC is a way of increasing the congestion window
247 .RI ( cwnd )
248 more slowly in response to partial acknowledgements.
249 Possible values are:
250 .RS
251 .TP
252 .B 0
253 increase
254 .I cwnd
255 once per acknowledgement (no ABC)
256 .TP
257 .B 1
258 increase
259 .I cwnd
260 once per acknowledgement of full sized segment
261 .TP
262 .B 2
263 allow increase
264 .I cwnd
265 by two if acknowledgement is
266 of two segments to compensate for delayed acknowledgements.
267 .RE
268 .TP
269 .IR tcp_abort_on_overflow " (Boolean; default: disabled; since Linux 2.4)"
270 .\" Since Linux 2.3.41
271 Enable resetting connections if the listening service is too
272 slow and unable to keep up and accept them.
273 It means that if overflow occurred due
274 to a burst, the connection will recover.
275 Enable this option
276 .I only
277 if you are really sure that the listening daemon
278 cannot be tuned to accept connections faster.
279 Enabling this option can harm the clients of your server.
280 .TP
281 .IR tcp_adv_win_scale " (integer; default: 2; since Linux 2.4)"
282 .\" Since Linux 2.4.0-test7
283 Count buffering overhead as
284 .IR "bytes/2\[ha]tcp_adv_win_scale" ,
285 if
286 .I tcp_adv_win_scale
287 is greater than 0;
288 or
289 .IR "bytes\-bytes/2\[ha](\-tcp_adv_win_scale)" ,
290 if
291 .I tcp_adv_win_scale
292 is less than or equal to zero.
293 .IP
294 The socket receive buffer space is shared between the
295 application and kernel.
296 TCP maintains part of the buffer as
297 the TCP window, this is the size of the receive window
298 advertised to the other end.
299 The rest of the space is used
300 as the "application" buffer, used to isolate the network
301 from scheduling and application latencies.
302 The
303 .I tcp_adv_win_scale
304 default value of 2 implies that the space
305 used for the application buffer is one fourth that of the total.
306 .TP
307 .IR tcp_allowed_congestion_control " (String; default: see text; since Linux 2.4.20)"
308 Show/set the congestion control algorithm choices available to unprivileged
309 processes (see the description of the
310 .B TCP_CONGESTION
311 socket option).
312 The items in the list are separated by white space and
313 terminated by a newline character.
314 The list is a subset of those listed in
315 .IR tcp_available_congestion_control .
316 The default value for this list is "reno" plus the default setting of
317 .IR tcp_congestion_control .
318 .TP
319 .IR tcp_autocorking " (Boolean; default: enabled; since Linux 3.14)"
320 .\" commit f54b311142a92ea2e42598e347b84e1655caf8e3
321 .\" Text heavily based on Documentation/networking/ip-sysctl.rst
322 If this option is enabled, the kernel tries to coalesce small writes
323 (from consecutive
324 .BR write (2)
325 and
326 .BR sendmsg (2)
327 calls) as much as possible,
328 in order to decrease the total number of sent packets.
329 Coalescing is done if at least one prior packet for the flow
330 is waiting in Qdisc queues or device transmit queue.
331 Applications can still use the
332 .B TCP_CORK
333 socket option to obtain optimal behavior
334 when they know how/when to uncork their sockets.
335 .TP
336 .IR tcp_available_congestion_control " (String; read-only; since Linux 2.4.20)"
337 Show a list of the congestion-control algorithms
338 that are registered.
339 The items in the list are separated by white space and
340 terminated by a newline character.
341 This list is a limiting set for the list in
342 .IR tcp_allowed_congestion_control .
343 More congestion-control algorithms may be available as modules,
344 but not loaded.
345 .TP
346 .IR tcp_app_win " (integer; default: 31; since Linux 2.4)"
347 .\" Since Linux 2.4.0-test7
348 This variable defines how many
349 bytes of the TCP window are reserved for buffering overhead.
350 .IP
351 A maximum of
352 .RI ( window/2\[ha]tcp_app_win ,
353 mss) bytes in the window
354 are reserved for the application buffer.
355 A value of 0 implies that no amount is reserved.
356 .\"
357 .TP
358 .IR tcp_base_mss " (Integer; default: 512; since Linux 2.6.17)"
359 The initial value of
360 .I search_low
361 to be used by the packetization layer Path MTU discovery (MTU probing).
362 If MTU probing is enabled,
363 this is the initial MSS used by the connection.
364 .\"
365 .TP
366 .IR tcp_bic " (Boolean; default: disabled; Linux 2.4.27/2.6.6 to Linux 2.6.13)"
367 Enable BIC TCP congestion control algorithm.
368 BIC-TCP is a sender-side-only change that ensures a linear RTT
369 fairness under large windows while offering both scalability and
370 bounded TCP-friendliness.
371 The protocol combines two schemes
372 called additive increase and binary search increase.
373 When the congestion window is large, additive increase with a large
374 increment ensures linear RTT fairness as well as good scalability.
375 Under small congestion windows, binary search
376 increase provides TCP friendliness.
377 .\"
378 .TP
379 .IR tcp_bic_low_window " (integer; default: 14; Linux 2.4.27/2.6.6 to Linux 2.6.13)"
380 Set the threshold window (in packets) where BIC TCP starts to
381 adjust the congestion window.
382 Below this threshold BIC TCP behaves the same as the default TCP Reno.
383 .\"
384 .TP
385 .IR tcp_bic_fast_convergence " (Boolean; default: enabled; Linux 2.4.27/2.6.6 to Linux 2.6.13)"
386 Force BIC TCP to more quickly respond to changes in congestion window.
387 Allows two flows sharing the same connection to converge more rapidly.
388 .TP
389 .IR tcp_congestion_control " (String; default: see text; since Linux 2.4.13)"
390 Set the default congestion-control algorithm to be used for new connections.
391 The algorithm "reno" is always available,
392 but additional choices may be available depending on kernel configuration.
393 The default value for this file is set as part of kernel configuration.
394 .TP
395 .IR tcp_dma_copybreak " (integer; default: 4096; since Linux 2.6.24)"
396 Lower limit, in bytes, of the size of socket reads that will be
397 offloaded to a DMA copy engine, if one is present in the system
398 and the kernel was configured with the
399 .B CONFIG_NET_DMA
400 option.
401 .TP
402 .IR tcp_dsack " (Boolean; default: enabled; since Linux 2.4)"
403 .\" Since Linux 2.4.0-test7
404 Enable RFC\ 2883 TCP Duplicate SACK support.
405 .TP
406 .IR tcp_fastopen " (Bitmask; default: 0x1; since Linux 3.7)"
407 Enables RFC\~7413 Fast Open support.
408 The flag is used as a bitmap with the following values:
409 .RS
410 .TP
411 .B 0x1
412 Enables client side Fast Open support
413 .TP
414 .B 0x2
415 Enables server side Fast Open support
416 .TP
417 .B 0x4
418 Allows client side to transmit data in SYN without Fast Open option
419 .TP
420 .B 0x200
421 Allows server side to accept SYN data without Fast Open option
422 .TP
423 .B 0x400
424 Enables Fast Open on all listeners without
425 .B TCP_FASTOPEN
426 socket option
427 .RE
428 .TP
429 .IR tcp_fastopen_key " (since Linux 3.7)"
430 Set server side RFC\~7413 Fast Open key to generate Fast Open cookie
431 when server side Fast Open support is enabled.
432 .TP
433 .IR tcp_ecn " (Integer; default: see below; since Linux 2.4)"
434 .\" Since Linux 2.4.0-test7
435 Enable RFC\ 3168 Explicit Congestion Notification.
436 .IP
437 This file can have one of the following values:
438 .RS
439 .TP
440 .B 0
441 Disable ECN.
442 Neither initiate nor accept ECN.
443 This was the default up to and including Linux 2.6.30.
444 .TP
445 .B 1
446 Enable ECN when requested by incoming connections and also
447 request ECN on outgoing connection attempts.
448 .TP
449 .B 2
450 .\" commit 255cac91c3c9ce7dca7713b93ab03c75b7902e0e
451 Enable ECN when requested by incoming connections,
452 but do not request ECN on outgoing connections.
453 This value is supported, and is the default, since Linux 2.6.31.
454 .RE
455 .IP
456 When enabled, connectivity to some destinations could be affected
457 due to older, misbehaving middle boxes along the path, causing
458 connections to be dropped.
459 However, to facilitate and encourage deployment with option 1, and
460 to work around such buggy equipment, the
461 .B tcp_ecn_fallback
462 option has been introduced.
463 .TP
464 .IR tcp_ecn_fallback " (Boolean; default: enabled; since Linux 4.1)"
465 .\" commit 492135557dc090a1abb2cfbe1a412757e3ed68ab
466 Enable RFC\ 3168, Section 6.1.1.1 fallback.
467 When enabled, outgoing ECN-setup SYNs that time out within the
468 normal SYN retransmission timeout will be resent with CWR and
469 ECE cleared.
470 .TP
471 .IR tcp_fack " (Boolean; default: enabled; since Linux 2.2)"
472 .\" Since Linux 2.1.92
473 Enable TCP Forward Acknowledgement support.
474 .TP
475 .IR tcp_fin_timeout " (integer; default: 60; since Linux 2.2)"
476 .\" Since Linux 2.1.53
477 This specifies how many seconds to wait for a final FIN packet before the
478 socket is forcibly closed.
479 This is strictly a violation of the TCP specification,
480 but required to prevent denial-of-service attacks.
481 In Linux 2.2, the default value was 180.
482 .\"
483 .TP
484 .IR tcp_frto " (integer; default: see below; since Linux 2.4.21/2.6)"
485 .\" Since Linux 2.4.21/2.5.43
486 Enable F-RTO, an enhanced recovery algorithm for TCP retransmission
487 timeouts (RTOs).
488 It is particularly beneficial in wireless environments
489 where packet loss is typically due to random radio interference
490 rather than intermediate router congestion.
491 See RFC 4138 for more details.
492 .IP
493 This file can have one of the following values:
494 .RS
495 .TP
496 .B 0
497 Disabled.
498 This was the default up to and including Linux 2.6.23.
499 .TP
500 .B 1
501 The basic version F-RTO algorithm is enabled.
502 .TP
503 .B 2
504 .\" commit c96fd3d461fa495400df24be3b3b66f0e0b152f9
505 Enable SACK-enhanced F-RTO if flow uses SACK.
506 The basic version can be used also when
507 SACK is in use though in that case scenario(s) exists where F-RTO
508 interacts badly with the packet counting of the SACK-enabled TCP flow.
509 This value is the default since Linux 2.6.24.
510 .RE
511 .IP
512 Before Linux 2.6.22, this parameter was a Boolean value,
513 supporting just values 0 and 1 above.
514 .TP
515 .IR tcp_frto_response " (integer; default: 0; since Linux 2.6.22)"
516 When F-RTO has detected that a TCP retransmission timeout was spurious
517 (i.e., the timeout would have been avoided had TCP set a
518 longer retransmission timeout),
519 TCP has several options concerning what to do next.
520 Possible values are:
521 .RS
522 .TP
523 .B 0
524 Rate halving based;
525 a smooth and conservative response,
526 results in halved congestion window
527 .RI ( cwnd )
528 and slow-start threshold
529 .RI ( ssthresh )
530 after one RTT.
531 .TP
532 .B 1
533 Very conservative response;
534 not recommended because even though being valid,
535 it interacts poorly with the rest of Linux TCP;
536 halves
537 .I cwnd
538 and
539 .I ssthresh
540 immediately.
541 .TP
542 .B 2
543 Aggressive response;
544 undoes congestion-control measures
545 that are now known to be unnecessary
546 (ignoring the possibility of a lost retransmission
547 that would require TCP to be more cautious);
548 .I cwnd
549 and
550 .I ssthresh
551 are restored to the values prior to timeout.
552 .RE
553 .TP
554 .IR tcp_keepalive_intvl " (integer; default: 75; since Linux 2.4)"
555 .\" Since Linux 2.3.18
556 The number of seconds between TCP keep-alive probes.
557 .TP
558 .IR tcp_keepalive_probes " (integer; default: 9; since Linux 2.2)"
559 .\" Since Linux 2.1.43
560 The maximum number of TCP keep-alive probes to send
561 before giving up and killing the connection if
562 no response is obtained from the other end.
563 .TP
564 .IR tcp_keepalive_time " (integer; default: 7200; since Linux 2.2)"
565 .\" Since Linux 2.1.43
566 The number of seconds a connection needs to be idle
567 before TCP begins sending out keep-alive probes.
568 Keep-alives are sent only when the
569 .B SO_KEEPALIVE
570 socket option is enabled.
571 The default value is 7200 seconds (2 hours).
572 An idle connection is terminated after
573 approximately an additional 11 minutes (9 probes an interval
574 of 75 seconds apart) when keep-alive is enabled.
575 .IP
576 Note that underlying connection tracking mechanisms and
577 application timeouts may be much shorter.
578 .\"
579 .TP
580 .IR tcp_low_latency " (Boolean; default: disabled; since Linux 2.4.21/2.6; obsolete since Linux 4.14)"
581 .\" Since Linux 2.4.21/2.5.60
582 If enabled, the TCP stack makes decisions that prefer lower
583 latency as opposed to higher throughput.
584 It this option is disabled, then higher throughput is preferred.
585 An example of an application where this default should be
586 changed would be a Beowulf compute cluster.
587 Since Linux 4.14,
588 .\" commit b6690b14386698ce2c19309abad3f17656bdfaea
589 this file still exists, but its value is ignored.
590 .TP
591 .IR tcp_max_orphans " (integer; default: see below; since Linux 2.4)"
592 .\" Since Linux 2.3.41
593 The maximum number of orphaned (not attached to any user file
594 handle) TCP sockets allowed in the system.
595 When this number is exceeded,
596 the orphaned connection is reset and a warning is printed.
597 This limit exists only to prevent simple denial-of-service attacks.
598 Lowering this limit is not recommended.
599 Network conditions might require you to increase the number of
600 orphans allowed, but note that each orphan can eat up to \[ti]64\ kB
601 of unswappable memory.
602 The default initial value is set equal to the kernel parameter NR_FILE.
603 This initial default is adjusted depending on the memory in the system.
604 .TP
605 .IR tcp_max_syn_backlog " (integer; default: see below; since Linux 2.2)"
606 .\" Since Linux 2.1.53
607 The maximum number of queued connection requests which have
608 still not received an acknowledgement from the connecting client.
609 If this number is exceeded, the kernel will begin
610 dropping requests.
611 The default value of 256 is increased to
612 1024 when the memory present in the system is adequate or
613 greater (>= 128\ MB), and reduced to 128 for those systems with
614 very low memory (<= 32\ MB).
615 .IP
616 Before Linux 2.6.20,
617 .\" commit 72a3effaf633bcae9034b7e176bdbd78d64a71db
618 it was recommended that if this needed to be increased above 1024,
619 the size of the SYNACK hash table
620 .RB ( TCP_SYNQ_HSIZE )
621 in
622 .I include/net/tcp.h
623 should be modified to keep
624 .IP
625 .in +4n
626 .EX
627 TCP_SYNQ_HSIZE * 16 <= tcp_max_syn_backlog
628 .EE
629 .in
630 .IP
631 and the kernel should be
632 recompiled.
633 In Linux 2.6.20, the fixed sized
634 .B TCP_SYNQ_HSIZE
635 was removed in favor of dynamic sizing.
636 .TP
637 .IR tcp_max_tw_buckets " (integer; default: see below; since Linux 2.4)"
638 .\" Since Linux 2.3.41
639 The maximum number of sockets in TIME_WAIT state allowed in
640 the system.
641 This limit exists only to prevent simple denial-of-service attacks.
642 The default value of NR_FILE*2 is adjusted
643 depending on the memory in the system.
644 If this number is
645 exceeded, the socket is closed and a warning is printed.
646 .TP
647 .IR tcp_moderate_rcvbuf " (Boolean; default: enabled; since Linux 2.4.17/2.6.7)"
648 If enabled, TCP performs receive buffer auto-tuning,
649 attempting to automatically size the buffer (no greater than
650 .IR tcp_rmem[2] )
651 to match the size required by the path for full throughput.
652 .TP
653 .IR tcp_mem " (since Linux 2.4)"
654 .\" Since Linux 2.4.0-test7
655 This is a vector of 3 integers: [low, pressure, high].
656 These bounds, measured in units of the system page size,
657 are used by TCP to track its memory usage.
658 The defaults are calculated at boot time from the amount of
659 available memory.
660 (TCP can only use
661 .I "low memory"
662 for this, which is limited to around 900 megabytes on 32-bit systems.
663 64-bit systems do not suffer this limitation.)
664 .RS
665 .TP
666 .I low
667 TCP doesn't regulate its memory allocation when the number
668 of pages it has allocated globally is below this number.
669 .TP
670 .I pressure
671 When the amount of memory allocated by TCP
672 exceeds this number of pages, TCP moderates its memory consumption.
673 This memory pressure state is exited
674 once the number of pages allocated falls below
675 the
676 .I low
677 mark.
678 .TP
679 .I high
680 The maximum number of pages, globally, that TCP will allocate.
681 This value overrides any other limits imposed by the kernel.
682 .RE
683 .TP
684 .IR tcp_mtu_probing " (integer; default: 0; since Linux 2.6.17)"
685 This parameter controls TCP Packetization-Layer Path MTU Discovery.
686 The following values may be assigned to the file:
687 .RS
688 .TP
689 .B 0
690 Disabled
691 .TP
692 .B 1
693 Disabled by default, enabled when an ICMP black hole detected
694 .TP
695 .B 2
696 Always enabled, use initial MSS of
697 .IR tcp_base_mss .
698 .RE
699 .TP
700 .IR tcp_no_metrics_save " (Boolean; default: disabled; since Linux 2.6.6)"
701 By default, TCP saves various connection metrics in the route cache
702 when the connection closes, so that connections established in the
703 near future can use these to set initial conditions.
704 Usually, this increases overall performance,
705 but it may sometimes cause performance degradation.
706 If
707 .I tcp_no_metrics_save
708 is enabled, TCP will not cache metrics on closing connections.
709 .TP
710 .IR tcp_orphan_retries " (integer; default: 8; since Linux 2.4)"
711 .\" Since Linux 2.3.41
712 The maximum number of attempts made to probe the other
713 end of a connection which has been closed by our end.
714 .TP
715 .IR tcp_reordering " (integer; default: 3; since Linux 2.4)"
716 .\" Since Linux 2.4.0-test7
717 The maximum a packet can be reordered in a TCP packet stream
718 without TCP assuming packet loss and going into slow start.
719 It is not advisable to change this number.
720 This is a packet reordering detection metric designed to
721 minimize unnecessary back off and retransmits provoked by
722 reordering of packets on a connection.
723 .TP
724 .IR tcp_retrans_collapse " (Boolean; default: enabled; since Linux 2.2)"
725 .\" Since Linux 2.1.96
726 Try to send full-sized packets during retransmit.
727 .TP
728 .IR tcp_retries1 " (integer; default: 3; since Linux 2.2)"
729 .\" Since Linux 2.1.43
730 The number of times TCP will attempt to retransmit a
731 packet on an established connection normally,
732 without the extra effort of getting the network layers involved.
733 Once we exceed this number of
734 retransmits, we first have the network layer
735 update the route if possible before each new retransmit.
736 The default is the RFC specified minimum of 3.
737 .TP
738 .IR tcp_retries2 " (integer; default: 15; since Linux 2.2)"
739 .\" Since Linux 2.1.43
740 The maximum number of times a TCP packet is retransmitted
741 in established state before giving up.
742 The default value is 15, which corresponds to a duration of
743 approximately between 13 to 30 minutes, depending
744 on the retransmission timeout.
745 The RFC\ 1122 specified
746 minimum limit of 100 seconds is typically deemed too short.
747 .TP
748 .IR tcp_rfc1337 " (Boolean; default: disabled; since Linux 2.2)"
749 .\" Since Linux 2.1.90
750 Enable TCP behavior conformant with RFC\ 1337.
751 When disabled,
752 if a RST is received in TIME_WAIT state, we close
753 the socket immediately without waiting for the end
754 of the TIME_WAIT period.
755 .TP
756 .IR tcp_rmem " (since Linux 2.4)"
757 .\" Since Linux 2.4.0-test7
758 This is a vector of 3 integers: [min, default, max].
759 These parameters are used by TCP to regulate receive buffer sizes.
760 TCP dynamically adjusts the size of the
761 receive buffer from the defaults listed below, in the range
762 of these values, depending on memory available in the system.
763 .RS
764 .TP
765 .I min
766 minimum size of the receive buffer used by each TCP socket.
767 The default value is the system page size.
768 (On Linux 2.4, the default value is 4\ kB, lowered to
769 .B PAGE_SIZE
770 bytes in low-memory systems.)
771 This value
772 is used to ensure that in memory pressure mode,
773 allocations below this size will still succeed.
774 This is not
775 used to bound the size of the receive buffer declared
776 using
777 .B SO_RCVBUF
778 on a socket.
779 .TP
780 .I default
781 the default size of the receive buffer for a TCP socket.
782 This value overwrites the initial default buffer size from
783 the generic global
784 .I net.core.rmem_default
785 defined for all protocols.
786 The default value is 87380 bytes.
787 (On Linux 2.4, this will be lowered to 43689 in low-memory systems.)
788 If larger receive buffer sizes are desired, this value should
789 be increased (to affect all sockets).
790 To employ large TCP windows, the
791 .I net.ipv4.tcp_window_scaling
792 must be enabled (default).
793 .TP
794 .I max
795 the maximum size of the receive buffer used by each TCP socket.
796 This value does not override the global
797 .IR net.core.rmem_max .
798 This is not used to limit the size of the receive buffer declared using
799 .B SO_RCVBUF
800 on a socket.
801 The default value is calculated using the formula
802 .IP
803 .in +4n
804 .EX
805 .RI "max(87380, min(4\ MB, " tcp_mem [1]*PAGE_SIZE/128))
806 .EE
807 .in
808 .IP
809 (On Linux 2.4, the default is 87380*2 bytes,
810 lowered to 87380 in low-memory systems).
811 .RE
812 .TP
813 .IR tcp_sack " (Boolean; default: enabled; since Linux 2.2)"
814 .\" Since Linux 2.1.36
815 Enable RFC\ 2018 TCP Selective Acknowledgements.
816 .TP
817 .IR tcp_slow_start_after_idle " (Boolean; default: enabled; since Linux 2.6.18)"
818 If enabled, provide RFC 2861 behavior and time out the congestion
819 window after an idle period.
820 An idle period is defined as the current RTO (retransmission timeout).
821 If disabled, the congestion window will not
822 be timed out after an idle period.
823 .TP
824 .IR tcp_stdurg " (Boolean; default: disabled; since Linux 2.2)"
825 .\" Since Linux 2.1.44
826 If this option is enabled, then use the RFC\ 1122 interpretation
827 of the TCP urgent-pointer field.
828 .\" RFC 793 was ambiguous in its specification of the meaning of the
829 .\" urgent pointer. RFC 1122 (and RFC 961) fixed on a particular
830 .\" resolution of this ambiguity (unfortunately the "wrong" one).
831 According to this interpretation, the urgent pointer points
832 to the last byte of urgent data.
833 If this option is disabled, then use the BSD-compatible interpretation of
834 the urgent pointer:
835 the urgent pointer points to the first byte after the urgent data.
836 Enabling this option may lead to interoperability problems.
837 .TP
838 .IR tcp_syn_retries " (integer; default: 6; since Linux 2.2)"
839 .\" Since Linux 2.1.38
840 The maximum number of times initial SYNs for an active TCP
841 connection attempt will be retransmitted.
842 This value should not be higher than 255.
843 The default value is 6, which corresponds to retrying for up to
844 approximately 127 seconds.
845 Before Linux 3.7,
846 .\" commit 6c9ff979d1921e9fd05d89e1383121c2503759b9
847 the default value was 5, which
848 (in conjunction with calculation based on other kernel parameters)
849 corresponded to approximately 180 seconds.
850 .TP
851 .IR tcp_synack_retries " (integer; default: 5; since Linux 2.2)"
852 .\" Since Linux 2.1.38
853 The maximum number of times a SYN/ACK segment
854 for a passive TCP connection will be retransmitted.
855 This number should not be higher than 255.
856 .TP
857 .IR tcp_syncookies " (integer; default: 1; since Linux 2.2)"
858 .\" Since Linux 2.1.43
859 Enable TCP syncookies.
860 The kernel must be compiled with
861 .BR CONFIG_SYN_COOKIES .
862 The syncookies feature attempts to protect a
863 socket from a SYN flood attack.
864 This should be used as a last resort, if at all.
865 This is a violation of the TCP protocol,
866 and conflicts with other areas of TCP such as TCP extensions.
867 It can cause problems for clients and relays.
868 It is not recommended as a tuning mechanism for heavily
869 loaded servers to help with overloaded or misconfigured conditions.
870 For recommended alternatives see
871 .IR tcp_max_syn_backlog ,
872 .IR tcp_synack_retries ,
873 and
874 .IR tcp_abort_on_overflow .
875 Set to one of the following values:
876 .RS
877 .TP
878 .B 0
879 Disable TCP syncookies.
880 .TP
881 .B 1
882 Send out syncookies when the syn backlog queue of a socket overflows.
883 .TP
884 .B 2
885 (since Linux 3.12)
886 .\" commit 5ad37d5deee1ff7150a2d0602370101de158ad86
887 Send out syncookies unconditionally.
888 This can be useful for network testing.
889 .RE
890 .TP
891 .IR tcp_timestamps " (integer; default: 1; since Linux 2.2)"
892 .\" Since Linux 2.1.36
893 Set to one of the following values to enable or disable RFC\ 1323
894 TCP timestamps:
895 .RS
896 .TP
897 .B 0
898 Disable timestamps.
899 .TP
900 .B 1
901 Enable timestamps as defined in RFC1323 and use random offset for
902 each connection rather than only using the current time.
903 .TP
904 .B 2
905 As for the value 1, but without random offsets.
906 .\" commit 25429d7b7dca01dc4f17205de023a30ca09390d0
907 Setting
908 .I tcp_timestamps
909 to this value is meaningful since Linux 4.10.
910 .RE
911 .TP
912 .IR tcp_tso_win_divisor " (integer; default: 3; since Linux 2.6.9)"
913 This parameter controls what percentage of the congestion window
914 can be consumed by a single TCP Segmentation Offload (TSO) frame.
915 The setting of this parameter is a tradeoff between burstiness and
916 building larger TSO frames.
917 .TP
918 .IR tcp_tw_recycle " (Boolean; default: disabled; Linux 2.4 to Linux 4.11)"
919 .\" Since Linux 2.3.15
920 .\" removed in Linux 4.12; commit 4396e46187ca5070219b81773c4e65088dac50cc
921 Enable fast recycling of TIME_WAIT sockets.
922 Enabling this option is
923 not recommended as the remote IP may not use monotonically increasing
924 timestamps (devices behind NAT, devices with per-connection timestamp
925 offsets).
926 See RFC 1323 (PAWS) and RFC 6191.
927 .\"
928 .TP
929 .IR tcp_tw_reuse " (Boolean; default: disabled; since Linux 2.4.19/2.6)"
930 .\" Since Linux 2.4.19/2.5.43
931 Allow to reuse TIME_WAIT sockets for new connections when it is
932 safe from protocol viewpoint.
933 It should not be changed without advice/request of technical experts.
934 .\"
935 .TP
936 .IR tcp_vegas_cong_avoid " (Boolean; default: disabled; Linux 2.2 to Linux 2.6.13)"
937 .\" Since Linux 2.1.8; removed in Linux 2.6.13
938 Enable TCP Vegas congestion avoidance algorithm.
939 TCP Vegas is a sender-side-only change to TCP that anticipates
940 the onset of congestion by estimating the bandwidth.
941 TCP Vegas adjusts the sending rate by modifying the congestion window.
942 TCP Vegas should provide less packet loss, but it is
943 not as aggressive as TCP Reno.
944 .\"
945 .TP
946 .IR tcp_westwood " (Boolean; default: disabled; Linux 2.4.26/2.6.3 to Linux 2.6.13)"
947 Enable TCP Westwood+ congestion control algorithm.
948 TCP Westwood+ is a sender-side-only modification of the TCP Reno
949 protocol stack that optimizes the performance of TCP congestion control.
950 It is based on end-to-end bandwidth estimation to set
951 congestion window and slow start threshold after a congestion episode.
952 Using this estimation, TCP Westwood+ adaptively sets a
953 slow start threshold and a congestion window which takes into
954 account the bandwidth used at the time congestion is experienced.
955 TCP Westwood+ significantly increases fairness with respect to
956 TCP Reno in wired networks and throughput over wireless links.
957 .TP
958 .IR tcp_window_scaling " (Boolean; default: enabled; since Linux 2.2)"
959 .\" Since Linux 2.1.36
960 Enable RFC\ 1323 TCP window scaling.
961 This feature allows the use of a large window
962 (> 64\ kB) on a TCP connection, should the other end support it.
963 Normally, the 16 bit window length field in the TCP header
964 limits the window size to less than 64\ kB.
965 If larger windows are desired, applications can increase the size of
966 their socket buffers and the window scaling option will be employed.
967 If
968 .I tcp_window_scaling
969 is disabled, TCP will not negotiate the use of window
970 scaling with the other end during connection setup.
971 .TP
972 .IR tcp_wmem " (since Linux 2.4)"
973 .\" Since Linux 2.4.0-test7
974 This is a vector of 3 integers: [min, default, max].
975 These parameters are used by TCP to regulate send buffer sizes.
976 TCP dynamically adjusts the size of the send buffer from the
977 default values listed below, in the range of these values,
978 depending on memory available.
979 .RS
980 .TP
981 .I min
982 Minimum size of the send buffer used by each TCP socket.
983 The default value is the system page size.
984 (On Linux 2.4, the default value is 4\ kB.)
985 This value is used to ensure that in memory pressure mode,
986 allocations below this size will still succeed.
987 This is not used to bound the size of the send buffer declared using
988 .B SO_SNDBUF
989 on a socket.
990 .TP
991 .I default
992 The default size of the send buffer for a TCP socket.
993 This value overwrites the initial default buffer size from
994 the generic global
995 .I /proc/sys/net/core/wmem_default
996 defined for all protocols.
997 The default value is 16\ kB.
998 .\" True in Linux 2.4 and 2.6
999 If larger send buffer sizes are desired, this value
1000 should be increased (to affect all sockets).
1001 To employ large TCP windows, the
1002 .I /proc/sys/net/ipv4/tcp_window_scaling
1003 must be set to a nonzero value (default).
1004 .TP
1005 .I max
1006 The maximum size of the send buffer used by each TCP socket.
1007 This value does not override the value in
1008 .IR /proc/sys/net/core/wmem_max .
1009 This is not used to limit the size of the send buffer declared using
1010 .B SO_SNDBUF
1011 on a socket.
1012 The default value is calculated using the formula
1013 .IP
1014 .in +4n
1015 .EX
1016 .RI "max(65536, min(4\ MB, " tcp_mem [1]*PAGE_SIZE/128))
1017 .EE
1018 .in
1019 .IP
1020 (On Linux 2.4, the default value is 128\ kB,
1021 lowered 64\ kB depending on low-memory systems.)
1022 .RE
1023 .TP
1024 .IR tcp_workaround_signed_windows " (Boolean; default: disabled; since Linux 2.6.26)"
1025 If enabled, assume that no receipt of a window-scaling option means that the
1026 remote TCP is broken and treats the window as a signed quantity.
1027 If disabled, assume that the remote TCP is not broken even if we do
1028 not receive a window scaling option from it.
1029 .SS Socket options
1030 To set or get a TCP socket option, call
1031 .BR getsockopt (2)
1032 to read or
1033 .BR setsockopt (2)
1034 to write the option with the option level argument set to
1035 .BR IPPROTO_TCP .
1036 Unless otherwise noted,
1037 .I optval
1038 is a pointer to an
1039 .IR int .
1040 .\" or SOL_TCP on Linux
1041 In addition,
1042 most
1043 .B IPPROTO_IP
1044 socket options are valid on TCP sockets.
1045 For more information see
1046 .BR ip (7).
1047 .P
1048 Following is a list of TCP-specific socket options.
1049 For details of some other socket options that are also applicable
1050 for TCP sockets, see
1051 .BR socket (7).
1052 .TP
1053 .BR TCP_CONGESTION " (since Linux 2.6.13)"
1054 .\" commit 5f8ef48d240963093451bcf83df89f1a1364f51d
1055 .\" Author: Stephen Hemminger <[email protected]>
1056 The argument for this option is a string.
1057 This option allows the caller to set the TCP congestion control
1058 algorithm to be used, on a per-socket basis.
1059 Unprivileged processes are restricted to choosing one of the algorithms in
1060 .I tcp_allowed_congestion_control
1061 (described above).
1062 Privileged processes
1063 .RB ( CAP_NET_ADMIN )
1064 can choose from any of the available congestion-control algorithms
1065 (see the description of
1066 .I tcp_available_congestion_control
1067 above).
1068 .TP
1069 .BR TCP_CORK " (since Linux 2.2)"
1070 .\" precisely: since Linux 2.1.127
1071 If set, don't send out partial frames.
1072 All queued partial frames are sent when the option is cleared again.
1073 This is useful for prepending headers before calling
1074 .BR sendfile (2),
1075 or for throughput optimization.
1076 As currently implemented, there is a 200 millisecond ceiling on the time
1077 for which output is corked by
1078 .BR TCP_CORK .
1079 If this ceiling is reached, then queued data is automatically transmitted.
1080 This option can be combined with
1081 .B TCP_NODELAY
1082 only since Linux 2.5.71.
1083 This option should not be used in code intended to be portable.
1084 .TP
1085 .BR TCP_DEFER_ACCEPT " (since Linux 2.4)"
1086 .\" Precisely: since Linux 2.3.38
1087 .\" Useful references:
1088 .\" http://www.techrepublic.com/article/take-advantage-of-tcp-ip-options-to-optimize-data-transmission/
1089 .\" http://unix.stackexchange.com/questions/94104/real-world-use-of-tcp-defer-accept
1090 Allow a listener to be awakened only when data arrives on the socket.
1091 Takes an integer value (seconds), this can
1092 bound the maximum number of attempts TCP will make to
1093 complete the connection.
1094 The kernel will round this value up
1095 to the next larger TCP retransmit duration.
1096 .IP
1097 On a client socket,
1098 if nonzero,
1099 delays sending the final ACK of the three-way handshake
1100 until the socket has data to send,
1101 in which case the ACK is piggybacked on the first data segment,
1102 or a delayed-ACK timeout is reached.
1103 .IP
1104 This option should not be used in code intended to be portable.
1105 .TP
1106 .BR TCP_INFO " (since Linux 2.4)"
1107 Used to collect information about this socket.
1108 The kernel returns a
1109 .I struct tcp_info
1110 as defined in the file
1111 .IR /usr/include/linux/tcp.h .
1112 This option should not be used in code intended to be portable.
1113 .TP
1114 .BR TCP_KEEPCNT " (since Linux 2.4)"
1115 .\" Precisely: since Linux 2.3.18
1116 The maximum number of keepalive probes TCP should send
1117 before dropping the connection.
1118 This option should not be
1119 used in code intended to be portable.
1120 .TP
1121 .BR TCP_KEEPIDLE " (since Linux 2.4)"
1122 .\" Precisely: since Linux 2.3.18
1123 The time (in seconds) the connection needs to remain idle
1124 before TCP starts sending keepalive probes, if the socket
1125 option
1126 .B SO_KEEPALIVE
1127 has been set on this socket.
1128 This option should not be used in code intended to be portable.
1129 .TP
1130 .BR TCP_KEEPINTVL " (since Linux 2.4)"
1131 .\" Precisely: since Linux 2.3.18
1132 The time (in seconds) between individual keepalive probes.
1133 This option should not be used in code intended to be portable.
1134 .TP
1135 .BR TCP_LINGER2 " (since Linux 2.4)"
1136 .\" Precisely: since Linux 2.3.41
1137 The lifetime of orphaned FIN_WAIT2 state sockets.
1138 This option can be used to override the system-wide setting in the file
1139 .I /proc/sys/net/ipv4/tcp_fin_timeout
1140 for this socket.
1141 This is not to be confused with the
1142 .BR socket (7)
1143 level option
1144 .BR SO_LINGER .
1145 This option should not be used in code intended to be portable.
1146 .TP
1147 .B TCP_MAXSEG
1148 .\" Present in Linux 1.0
1149 The maximum segment size for outgoing TCP packets.
1150 In Linux 2.2 and earlier, and in Linux 2.6.28 and later,
1151 if this option is set before connection establishment, it also
1152 changes the MSS value announced to the other end in the initial packet.
1153 Values greater than the (eventual) interface MTU have no effect.
1154 TCP will also impose
1155 its minimum and maximum bounds over the value provided.
1156 .TP
1157 .B TCP_NODELAY
1158 .\" Present in Linux 1.0
1159 If set, disable the Nagle algorithm.
1160 This means that segments
1161 are always sent as soon as possible, even if there is only a
1162 small amount of data.
1163 When not set, data is buffered until there
1164 is a sufficient amount to send out, thereby avoiding the
1165 frequent sending of small packets, which results in poor
1166 utilization of the network.
1167 This option is overridden by
1168 .BR TCP_CORK ;
1169 however, setting this option forces an explicit flush of
1170 pending output, even if
1171 .B TCP_CORK
1172 is currently set.
1173 .TP
1174 .BR TCP_QUICKACK " (since Linux 2.4.4)"
1175 Enable quickack mode if set or disable quickack
1176 mode if cleared.
1177 In quickack mode, acks are sent
1178 immediately, rather than delayed if needed in accordance
1179 to normal TCP operation.
1180 This flag is not permanent,
1181 it only enables a switch to or from quickack mode.
1182 Subsequent operation of the TCP protocol will
1183 once again enter/leave quickack mode depending on
1184 internal protocol processing and factors such as
1185 delayed ack timeouts occurring and data transfer.
1186 This option should not be used in code intended to be
1187 portable.
1188 .TP
1189 .BR TCP_SYNCNT " (since Linux 2.4)"
1190 .\" Precisely: since Linux 2.3.18
1191 Set the number of SYN retransmits that TCP should send before
1192 aborting the attempt to connect.
1193 It cannot exceed 255.
1194 This option should not be used in code intended to be portable.
1195 .TP
1196 .BR TCP_SAVE_SYN " (since Linux 4.3)"
1197 Saves incoming SYN packet contents of the listening socket
1198 until it is read with
1199 .B TCP_SAVED_SYN
1200 once.
1201 Could be set before or after the
1202 .BR listen (2)
1203 call.
1204 .TP
1205 .BR TCP_SAVED_SYN " (since Linux 4.3)"
1206 Reads SYN packet contents saved by
1207 .BR TCP_SAVE_SYN .
1208 The saved SYN headers are freed after the first call.
1209 The data returned in
1210 .B TCP_SAVED_SYN
1211 are network (IPv4/IPv6) and TCP headers.
1212 .TP
1213 .BR TCP_USER_TIMEOUT " (since Linux 2.6.37)"
1214 .\" commit dca43c75e7e545694a9dd6288553f55c53e2a3a3
1215 .\" Author: Jerry Chu <[email protected]>
1216 .\" The following text taken nearly verbatim from Jerry Chu's (excellent)
1217 .\" commit message.
1218 .\"
1219 This option takes an
1220 .I unsigned int
1221 as an argument.
1222 When the value is greater than 0,
1223 it specifies the maximum amount of time in milliseconds that transmitted
1224 data may remain unacknowledged, or buffered data may remain untransmitted
1225 (due to zero window size) before TCP will forcibly close the
1226 corresponding connection and return
1227 .B ETIMEDOUT
1228 to the application.
1229 If the option value is specified as 0,
1230 TCP will use the system default.
1231 .IP
1232 Increasing user timeouts allows a TCP connection to survive extended
1233 periods without end-to-end connectivity.
1234 Decreasing user timeouts
1235 allows applications to "fail fast", if so desired.
1236 Otherwise, failure may take up to 20 minutes with
1237 the current system defaults in a normal WAN environment.
1238 .IP
1239 This option can be set during any state of a TCP connection,
1240 but is effective only during the synchronized states of a connection
1241 (ESTABLISHED, FIN-WAIT-1, FIN-WAIT-2, CLOSE-WAIT, CLOSING, and LAST-ACK).
1242 Moreover, when used with the TCP keepalive
1243 .RB ( SO_KEEPALIVE )
1244 option,
1245 .B TCP_USER_TIMEOUT
1246 will override keepalive to determine when to close a
1247 connection due to keepalive failure.
1248 .IP
1249 The option has no effect on when TCP retransmits a packet,
1250 nor when a keepalive probe is sent.
1251 .IP
1252 This option, like many others, will be inherited by the socket returned by
1253 .BR accept (2),
1254 if it was set on the listening socket.
1255 .IP
1256 Further details on the user timeout feature can be found in
1257 RFC\ 793 and RFC\ 5482 ("TCP User Timeout Option").
1258 .TP
1259 .BR TCP_WINDOW_CLAMP " (since Linux 2.4)"
1260 .\" Precisely: since Linux 2.3.41
1261 Bound the size of the advertised window to this value.
1262 The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2.
1263 This option should not be used in code intended to be
1264 portable.
1265 .TP
1266 .BR TCP_FASTOPEN " (since Linux 3.6)"
1267 This option enables Fast Open (RFC\~7413) on the listener socket.
1268 The value specifies the maximum length of pending SYNs
1269 (similar to the backlog argument in
1270 .BR listen (2)).
1271 Once enabled,
1272 the listener socket grants the TCP Fast Open cookie
1273 on incoming SYN with TCP Fast Open option.
1274 .IP
1275 More importantly it accepts the data in SYN with a valid Fast Open cookie
1276 and responds SYN-ACK acknowledging both the data and the SYN sequence.
1277 .BR accept (2)
1278 returns a socket that is available for read and write
1279 when the handshake has not completed yet.
1280 Thus the data exchange can commence before the handshake completes.
1281 This option requires enabling the server-side support on sysctl
1282 .I net.ipv4.tcp_fastopen
1283 (see above).
1284 For TCP Fast Open client-side support,
1285 see
1286 .BR send (2)
1287 .B MSG_FASTOPEN
1288 or
1289 .B TCP_FASTOPEN_CONNECT
1290 below.
1291 .TP
1292 .BR TCP_FASTOPEN_CONNECT " (since Linux 4.11)"
1293 This option enables an alternative way to perform Fast Open
1294 on the active side (client).
1295 When this option is enabled,
1296 .BR connect (2)
1297 would behave differently depending on
1298 if a Fast Open cookie is available for the destination.
1299 .IP
1300 If a cookie is not available
1301 (i.e., first contact to the destination),
1302 .BR connect (2)
1303 behaves as usual by sending a SYN immediately,
1304 except the SYN would include an empty Fast Open cookie option
1305 to solicit a cookie.
1306 .IP
1307 If a cookie is available,
1308 .BR connect (2)
1309 would return 0 immediately but the SYN transmission is deferred.
1310 A subsequent
1311 .BR write (2)
1312 or
1313 .BR sendmsg (2)
1314 would trigger a SYN with data plus cookie in the Fast Open option.
1315 In other words,
1316 the actual connect operation is deferred until data is supplied.
1317 .IP
1318 .B Note:
1319 While this option is designed for convenience,
1320 enabling it does change the behaviors and certain system calls might set
1321 different
1322 .I errno
1323 values.
1324 With cookie present,
1325 .BR write (2)
1326 or
1327 .BR sendmsg (2)
1328 must be called right after
1329 .BR connect (2)
1330 in order to send out SYN+data to complete 3WHS and establish connection.
1331 Calling
1332 .BR read (2)
1333 right after
1334 .BR connect (2)
1335 without
1336 .BR write (2)
1337 will cause the blocking socket to be blocked forever.
1338 .IP
1339 The application should either set
1340 .B TCP_FASTOPEN_CONNECT
1341 socket option before
1342 .BR write (2)
1343 or
1344 .BR sendmsg (2),
1345 or call
1346 .BR write (2)
1347 or
1348 .BR sendmsg (2)
1349 with
1350 .B MSG_FASTOPEN
1351 flag directly,
1352 instead of both on the same connection.
1353 .IP
1354 Here is the typical call flow with this new option:
1355 .IP
1356 .in +4n
1357 .EX
1358 s = socket();
1359 setsockopt(s, IPPROTO_TCP, TCP_FASTOPEN_CONNECT, 1, ...);
1360 connect(s);
1361 write(s); /* write() should always follow connect()
1362 * in order to trigger SYN to go out. */
1363 read(s)/write(s);
1364 /* ...\& */
1365 close(s);
1366 .EE
1367 .in
1368 .SS Sockets API
1369 TCP provides limited support for out-of-band data,
1370 in the form of (a single byte of) urgent data.
1371 In Linux this means if the other end sends newer out-of-band
1372 data the older urgent data is inserted as normal data into
1373 the stream (even when
1374 .B SO_OOBINLINE
1375 is not set).
1376 This differs from BSD-based stacks.
1377 .P
1378 Linux uses the BSD compatible interpretation of the urgent
1379 pointer field by default.
1380 This violates RFC\ 1122, but is
1381 required for interoperability with other stacks.
1382 It can be changed via
1383 .IR /proc/sys/net/ipv4/tcp_stdurg .
1384 .P
1385 It is possible to peek at out-of-band data using the
1386 .BR recv (2)
1387 .B MSG_PEEK
1388 flag.
1389 .P
1390 Since Linux 2.4, Linux supports the use of
1391 .B MSG_TRUNC
1392 in the
1393 .I flags
1394 argument of
1395 .BR recv (2)
1396 (and
1397 .BR recvmsg (2)).
1398 This flag causes the received bytes of data to be discarded,
1399 rather than passed back in a caller-supplied buffer.
1400 Since Linux 2.4.4,
1401 .B MSG_TRUNC
1402 also has this effect when used in conjunction with
1403 .B MSG_OOB
1404 to receive out-of-band data.
1405 .SS Ioctls
1406 The following
1407 .BR ioctl (2)
1408 calls return information in
1409 .IR value .
1410 The correct syntax is:
1411 .P
1412 .RS
1413 .nf
1414 .BI int " value";
1415 .IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");"
1416 .fi
1417 .RE
1418 .P
1419 .I ioctl_type
1420 is one of the following:
1421 .TP
1422 .B SIOCINQ
1423 Returns the amount of queued unread data in the receive buffer.
1424 The socket must not be in LISTEN state, otherwise an error
1425 .RB ( EINVAL )
1426 is returned.
1427 .B SIOCINQ
1428 is defined in
1429 .IR <linux/sockios.h> .
1430 .\" FIXME https://www.sourceware.org/bugzilla/show_bug.cgi?id=12002,
1431 .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers
1432 Alternatively,
1433 you can use the synonymous
1434 .BR FIONREAD ,
1435 defined in
1436 .IR <sys/ioctl.h> .
1437 .TP
1438 .B SIOCATMARK
1439 Returns true (i.e.,
1440 .I value
1441 is nonzero) if the inbound data stream is at the urgent mark.
1442 .IP
1443 If the
1444 .B SO_OOBINLINE
1445 socket option is set, and
1446 .B SIOCATMARK
1447 returns true, then the
1448 next read from the socket will return the urgent data.
1449 If the
1450 .B SO_OOBINLINE
1451 socket option is not set, and
1452 .B SIOCATMARK
1453 returns true, then the
1454 next read from the socket will return the bytes following
1455 the urgent data (to actually read the urgent data requires the
1456 .B recv(MSG_OOB)
1457 flag).
1458 .IP
1459 Note that a read never reads across the urgent mark.
1460 If an application is informed of the presence of urgent data via
1461 .BR select (2)
1462 (using the
1463 .I exceptfds
1464 argument) or through delivery of a
1465 .B SIGURG
1466 signal,
1467 then it can advance up to the mark using a loop which repeatedly tests
1468 .B SIOCATMARK
1469 and performs a read (requesting any number of bytes) as long as
1470 .B SIOCATMARK
1471 returns false.
1472 .TP
1473 .B SIOCOUTQ
1474 Returns the amount of unsent data in the socket send queue.
1475 The socket must not be in LISTEN state, otherwise an error
1476 .RB ( EINVAL )
1477 is returned.
1478 .B SIOCOUTQ
1479 is defined in
1480 .IR <linux/sockios.h> .
1481 .\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12002,
1482 .\" filed 2010-09-10, may cause SIOCOUTQ to be defined in glibc headers
1483 Alternatively,
1484 you can use the synonymous
1485 .BR TIOCOUTQ ,
1486 defined in
1487 .IR <sys/ioctl.h> .
1488 .SS Error handling
1489 When a network error occurs, TCP tries to resend the packet.
1490 If it doesn't succeed after some time, either
1491 .B ETIMEDOUT
1492 or the last received error on this connection is reported.
1493 .P
1494 Some applications require a quicker error notification.
1495 This can be enabled with the
1496 .B IPPROTO_IP
1497 level
1498 .B IP_RECVERR
1499 socket option.
1500 When this option is enabled, all incoming
1501 errors are immediately passed to the user program.
1502 Use this option with care \[em] it makes TCP less tolerant to routing
1503 changes and other normal network conditions.
1504 .SH ERRORS
1505 .TP
1506 .B EAFNOTSUPPORT
1507 Passed socket address type in
1508 .I sin_family
1509 was not
1510 .BR AF_INET .
1511 .TP
1512 .B EPIPE
1513 The other end closed the socket unexpectedly or a read is
1514 executed on a shut down socket.
1515 .TP
1516 .B ETIMEDOUT
1517 The other end didn't acknowledge retransmitted data after some time.
1518 .P
1519 Any errors defined for
1520 .BR ip (7)
1521 or the generic socket layer may also be returned for TCP.
1522 .SH VERSIONS
1523 Support for Explicit Congestion Notification, zero-copy
1524 .BR sendfile (2),
1525 reordering support and some SACK extensions
1526 (DSACK) were introduced in Linux 2.4.
1527 Support for forward acknowledgement (FACK), TIME_WAIT recycling,
1528 and per-connection keepalive socket options were introduced in Linux 2.3.
1529 .SH BUGS
1530 Not all errors are documented.
1531 .P
1532 IPv6 is not described.
1533 .\" Only a single Linux kernel version is described
1534 .\" Info for 2.2 was lost. Should be added again,
1535 .\" or put into a separate page.
1536 .\" .SH AUTHORS
1537 .\" This man page was originally written by Andi Kleen.
1538 .\" It was updated for 2.4 by Nivedita Singhvi with input from
1539 .\" Alexey Kuznetsov's Documentation/networking/ip-sysctl.rst
1540 .\" document.
1541 .SH SEE ALSO
1542 .BR accept (2),
1543 .BR bind (2),
1544 .BR connect (2),
1545 .BR getsockopt (2),
1546 .BR listen (2),
1547 .BR recvmsg (2),
1548 .BR sendfile (2),
1549 .BR sendmsg (2),
1550 .BR socket (2),
1551 .BR ip (7),
1552 .BR socket (7)
1553 .P
1554 The kernel source file
1555 .IR Documentation/networking/ip\-sysctl.rst .
1556 .P
1557 RFC\ 793 for the TCP specification.
1558 .br
1559 RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm.
1560 .br
1561 RFC\ 1323 for TCP timestamp and window scaling options.
1562 .br
1563 RFC\ 1337 for a description of TIME_WAIT assassination hazards.
1564 .br
1565 RFC\ 3168 for a description of Explicit Congestion Notification.
1566 .br
1567 RFC\ 2581 for TCP congestion control algorithms.
1568 .br
1569 RFC\ 2018 and RFC\ 2883 for SACK and extensions to SACK.