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