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 August 31, 2001 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.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 101The 102.Nm 103implements a number of variables in 104the 105.Va net.inet.tcp.syncache 106branch of the 107.Xr sysctl 3 108MIB. 109Several of these may be tuned by setting the corresponding 110variable in the 111.Xr loader 8 . 112.Bl -tag -width ".Va bucketlimit" 113.It Va hashsize 114Size of the 115.Nm 116hash table, must be a power of 2. 117Read-only, tunable via 118.Xr loader 8 . 119.It Va bucketlimit 120Limit on the number of entries permitted in each bucket of the hash table. 121This should be left at a low value to minimize search time. 122Read-only, tunable via 123.Xr loader 8 . 124.It Va cachelimit 125Limit on the total number of entries in the 126.Nm . 127Defaults to 128.Va ( hashsize No \(mu Va bucketlimit ) , 129may be set lower to minimize memory 130consumption. 131Read-only, tunable via 132.Xr loader 8 . 133.It Va rexmtlimit 134Maximum number of times a SYN,ACK is retransmitted before being discarded. 135The default of 3 retransmits corresponds to a 15 second timeout, this value 136may be increased depending on the RTT to client machines. 137Tunable via 138.Xr sysctl 3 . 139.It Va count 140Number of entries present in the 141.Nm 142(read-only). 143.El 144.Pp 145Statistics on the performance of the 146.Nm 147may be obtained via 148.Xr netstat 1 , 149which provides the following counts: 150.Bl -tag -width ".Li cookies received" 151.It Li "syncache entries added" 152Entries successfully inserted in the 153.Nm . 154.It Li retransmitted 155SYN,ACK retransmissions due to a timeout expiring. 156.It Li dupsyn 157Incoming SYN segment matching an existing entry. 158.It Li dropped 159SYNs dropped because SYN,ACK could not be sent. 160.It Li completed 161Successfully completed connections. 162.It Li "bucket overflow" 163Entries dropped for exceeding per-bucket size. 164.It Li "cache overflow" 165Entries dropped for exceeding overall cache size. 166.It Li reset 167RST segment received. 168.It Li stale 169Entries dropped due to maximum retransmissions or listen socket disappearance. 170.It Li aborted 171New socket allocation failures. 172.It Li badack 173Entries dropped due to bad ACK reply. 174.It Li unreach 175Entries dropped due to ICMP unreachable messages. 176.It Li "zone failures" 177Failures to allocate new 178.Nm 179entry. 180.It Li "cookies received" 181Connections created from segment containing ACK. 182.El 183.Sh SEE ALSO 184.Xr netstat 1 , 185.Xr tcp 4 , 186.Xr loader 8 , 187.Xr sysctl 8 188.Sh HISTORY 189The existing 190.Nm 191implementation 192first appeared in 193.Fx 4.5 . 194The original concept of a 195.Nm 196originally appeared in 197.Bsx , 198and was later modified by 199.Nx , 200then further extended here. 201.Sh AUTHORS 202The 203.Nm 204code and manual page were written by 205.An Jonathan Lemon Aq jlemon@FreeBSD.org . 206