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