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