1.\" 2.\" syncache - TCP SYN caching to handle SYN flood DoS. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.Dd August 30, 2025 14.Dt SYNCACHE 4 15.Os 16.Sh NAME 17.Nm syncache , syncookies 18.Nd 19.Xr sysctl 8 20MIBs for controlling TCP SYN caching 21.Sh SYNOPSIS 22.Bl -item -compact 23.It 24.Nm sysctl Cm net.inet.tcp.syncookies 25.It 26.Nm sysctl Cm net.inet.tcp.syncookies_only 27.El 28.Pp 29.Bl -item -compact 30.It 31.Nm sysctl Cm net.inet.tcp.syncache.hashsize 32.It 33.Nm sysctl Cm net.inet.tcp.syncache.bucketlimit 34.It 35.Nm sysctl Cm net.inet.tcp.syncache.cachelimit 36.It 37.Nm sysctl Cm net.inet.tcp.syncache.rexmtlimit 38.It 39.Nm sysctl Cm net.inet.tcp.syncache.count 40.It 41.Nm sysctl Cm net.inet.tcp.syncache.see_other 42.It 43.Nm sysctl Cm net.inet.tcp.syncache.rst_on_sock_fail 44.El 45.Sh DESCRIPTION 46The 47.Nm 48.Xr sysctl 8 49MIB is used to control the TCP SYN caching in the system, which 50is intended to handle SYN flood Denial of Service attacks. 51.Pp 52When a TCP SYN segment is received on a port corresponding to a listen 53socket, an entry is made in the 54.Nm , 55and a SYN,ACK segment is 56returned to the peer. 57The 58.Nm 59entry holds the TCP options from the initial SYN, 60enough state to perform a SYN,ACK retransmission, and takes up less 61space than a TCP control block endpoint. 62An incoming segment which contains an ACK for the SYN,ACK 63and matches a 64.Nm 65entry will cause the system to create a TCP control block 66with the options stored in the 67.Nm 68entry, which is then released. 69.Pp 70The 71.Nm 72protects the system from SYN flood DoS attacks by minimizing 73the amount of state kept on the server, and by limiting the overall size 74of the 75.Nm . 76.Pp 77.Nm Syncookies 78provides a way to virtually expand the size of the 79.Nm 80by keeping state regarding the initial SYN in the network. 81Enabling 82.Nm syncookies 83sends a cryptographic value in the SYN,ACK reply to 84the client machine, which is then returned in the client's ACK. 85If the corresponding entry is not found in the 86.Nm , 87but the value 88passes specific security checks, the connection will be accepted. 89This is only used if the 90.Nm 91is unable to handle the volume of 92incoming connections, and a prior entry has been evicted from the cache. 93.Pp 94.Nm Syncookies 95have a certain number of disadvantages that a paranoid 96administrator may wish to take note of. 97Since the TCP options from the initial SYN are not saved, they are not 98applied to the connection, precluding use of features like window scale, 99timestamps, or exact MSS sizing. 100As the returning ACK establishes the connection, it may be possible for 101an attacker to ACK flood a machine in an attempt to create a connection. 102While steps have been taken to mitigate this risk, this may provide a way 103to bypass firewalls which filter incoming segments with the SYN bit set. 104.Pp 105To disable the 106.Nm syncache 107and run only with 108.Nm syncookies , 109set 110.Va net.inet.tcp.syncookies_only 111to 1. 112To use 113.Nm syncookies 114to handle bucket overflows in the 115.Nm syncache 116set 117.Va net.inet.tcp.syncookies 118to 1. 119The default value for 120.Va net.inet.tcp.syncookies_only 121is 0 and the default value for 122.Va net.inet.tcp.syncookies 123is 1. 124.Pp 125The 126.Nm 127implements a number of variables in 128the 129.Va net.inet.tcp.syncache 130branch of the 131.Xr sysctl 3 132MIB. 133Several of these may be tuned by setting the corresponding 134variable in the 135.Xr loader 8 . 136.Bl -tag -width ".Va bucketlimit" 137.It Va hashsize 138Size of the 139.Nm 140hash table, must be a power of 2. 141Read-only, tunable via 142.Xr loader 8 . 143.It Va bucketlimit 144Limit on the number of entries permitted in each bucket of the hash table. 145This should be left at a low value to minimize search time. 146Read-only, tunable via 147.Xr loader 8 . 148.It Va cachelimit 149Limit on the total number of entries in the 150.Nm . 151Defaults to 152.Va ( hashsize No \(mu Va bucketlimit ) , 153may be set lower to minimize memory 154consumption. 155Read-only, tunable via 156.Xr loader 8 . 157.It Va rexmtlimit 158Maximum number of times a SYN,ACK is retransmitted before being discarded. 159The default of 3 retransmits corresponds to a 45 second timeout, this value 160may be increased depending on the RTT to client machines. 161Tunable via 162.Xr sysctl 3 . 163.It Va count 164Number of entries present in the 165.Nm 166(read-only). 167.It Va see_other 168If set to true value, all 169.Nm 170entries will be visible via 171.Va net.inet.tcp.pcblist 172sysctl, or via 173.Xr netstat 1 , 174ignoring all of 175.Xr security 7 176UID/GID, 177.Xr jail 2 178and 179.Xr mac 4 180checks. 181If turned off, the visibility checks are enforced. 182However, extra 183.Xr ucred 9 184referencing is required on every incoming SYN packet processed. 185The default is off. 186.It Va rst_on_sock_fail 187Send a TCP RST segment if the socket allocation fails. 188The default is on. 189.El 190.Pp 191Statistics on the performance of the 192.Nm 193may be obtained via 194.Xr netstat 1 , 195which provides the following counts: 196.Bl -tag -width ".Li cookies received" 197.It Li "syncache entries added" 198Entries successfully inserted in the 199.Nm . 200.It Li retransmitted 201SYN,ACK retransmissions due to a timeout expiring. 202.It Li dupsyn 203Incoming SYN segment matching an existing entry. 204.It Li dropped 205SYNs dropped because SYN,ACK could not be sent. 206.It Li completed 207Successfully completed connections. 208.It Li "bucket overflow" 209Entries dropped for exceeding per-bucket size. 210.It Li "cache overflow" 211Entries dropped for exceeding overall cache size. 212.It Li reset 213RST segment received. 214.It Li stale 215Entries dropped due to maximum retransmissions or listen socket disappearance. 216.It Li aborted 217New socket allocation failures. 218.It Li badack 219Entries dropped due to bad ACK reply. 220.It Li unreach 221Entries dropped due to ICMP unreachable messages. 222.It Li "zone failures" 223Failures to allocate new 224.Nm 225entry. 226.It Li "cookies sent" 227SYN cookies sent in SYN ACK segments. 228.It Li "cookies received" 229ACK segments with valid syncookies which resulted in TCP connection 230establishment. 231.It Li "spurious cookies rejected" 232Received ACKs, for which the syncache lookup failed and also no syncookie was 233recently sent. 234.It Li "failed cookies rejected" 235Received ACKs for which the syncookie validation failed. 236.El 237.Sh SEE ALSO 238.Xr netstat 1 , 239.Xr jail 2 , 240.Xr mac 4 , 241.Xr tcp 4 , 242.Xr security 7 , 243.Xr loader 8 , 244.Xr sysctl 8 , 245.Xr ucred 9 246.Sh HISTORY 247The existing 248.Nm 249implementation 250first appeared in 251.Fx 4.5 . 252The original concept of a 253.Nm 254originally appeared in 255.Bsx , 256and was later modified by 257.Nx , 258then further extended here. 259.Sh AUTHORS 260The 261.Nm 262code and manual page were written by 263.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . 264