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.\" $FreeBSD$ 14.\" 15.Dd April 12, 2021 16.Dt SYNCACHE 4 17.Os 18.Sh NAME 19.Nm syncache , syncookies 20.Nd 21.Xr sysctl 8 22MIBs for controlling TCP SYN caching 23.Sh SYNOPSIS 24.Bl -item -compact 25.It 26.Nm sysctl Cm net.inet.tcp.syncookies 27.It 28.Nm sysctl Cm net.inet.tcp.syncookies_only 29.El 30.Pp 31.Bl -item -compact 32.It 33.Nm sysctl Cm net.inet.tcp.syncache.hashsize 34.It 35.Nm sysctl Cm net.inet.tcp.syncache.bucketlimit 36.It 37.Nm sysctl Cm net.inet.tcp.syncache.cachelimit 38.It 39.Nm sysctl Cm net.inet.tcp.syncache.rexmtlimit 40.It 41.Nm sysctl Cm net.inet.tcp.syncache.count 42.It 43.Nm sysctl Cm net.inet.tcp.syncache.see_other 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. 112.Pp 113The 114.Nm 115implements a number of variables in 116the 117.Va net.inet.tcp.syncache 118branch of the 119.Xr sysctl 3 120MIB. 121Several of these may be tuned by setting the corresponding 122variable in the 123.Xr loader 8 . 124.Bl -tag -width ".Va bucketlimit" 125.It Va hashsize 126Size of the 127.Nm 128hash table, must be a power of 2. 129Read-only, tunable via 130.Xr loader 8 . 131.It Va bucketlimit 132Limit on the number of entries permitted in each bucket of the hash table. 133This should be left at a low value to minimize search time. 134Read-only, tunable via 135.Xr loader 8 . 136.It Va cachelimit 137Limit on the total number of entries in the 138.Nm . 139Defaults to 140.Va ( hashsize No \(mu Va bucketlimit ) , 141may be set lower to minimize memory 142consumption. 143Read-only, tunable via 144.Xr loader 8 . 145.It Va rexmtlimit 146Maximum number of times a SYN,ACK is retransmitted before being discarded. 147The default of 3 retransmits corresponds to a 45 second timeout, this value 148may be increased depending on the RTT to client machines. 149Tunable via 150.Xr sysctl 3 . 151.It Va count 152Number of entries present in the 153.Nm 154(read-only). 155.It Va see_other 156If set to true value, all 157.Nm 158entries will be visible via 159.Va net.inet.tcp.pcblist 160sysctl, or via 161.Xr netstat 1 , 162ignoring all of 163.Xr security 7 164UID/GID, 165.Xr jail 2 166and 167.Xr mac 4 168checks. 169If turned off, the visibility checks are enforced. 170However, extra 171.Xr ucred 9 172referencing is required on every incoming SYN packet processed. 173The default is off. 174.El 175.Pp 176Statistics on the performance of the 177.Nm 178may be obtained via 179.Xr netstat 1 , 180which provides the following counts: 181.Bl -tag -width ".Li cookies received" 182.It Li "syncache entries added" 183Entries successfully inserted in the 184.Nm . 185.It Li retransmitted 186SYN,ACK retransmissions due to a timeout expiring. 187.It Li dupsyn 188Incoming SYN segment matching an existing entry. 189.It Li dropped 190SYNs dropped because SYN,ACK could not be sent. 191.It Li completed 192Successfully completed connections. 193.It Li "bucket overflow" 194Entries dropped for exceeding per-bucket size. 195.It Li "cache overflow" 196Entries dropped for exceeding overall cache size. 197.It Li reset 198RST segment received. 199.It Li stale 200Entries dropped due to maximum retransmissions or listen socket disappearance. 201.It Li aborted 202New socket allocation failures. 203.It Li badack 204Entries dropped due to bad ACK reply. 205.It Li unreach 206Entries dropped due to ICMP unreachable messages. 207.It Li "zone failures" 208Failures to allocate new 209.Nm 210entry. 211.It Li "cookies received" 212Connections created from segment containing ACK. 213.El 214.Sh SEE ALSO 215.Xr netstat 1 , 216.Xr jail 2 , 217.Xr mac 4 , 218.Xr tcp 4 , 219.Xr security 7 , 220.Xr loader 8 , 221.Xr sysctl 8 , 222.Xr ucred 9 223.Sh HISTORY 224The existing 225.Nm 226implementation 227first appeared in 228.Fx 4.5 . 229The original concept of a 230.Nm 231originally appeared in 232.Bsx , 233and was later modified by 234.Nx , 235then further extended here. 236.Sh AUTHORS 237The 238.Nm 239code and manual page were written by 240.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . 241