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 January 22, 2008 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.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.El 154.Pp 155Statistics on the performance of the 156.Nm 157may be obtained via 158.Xr netstat 1 , 159which provides the following counts: 160.Bl -tag -width ".Li cookies received" 161.It Li "syncache entries added" 162Entries successfully inserted in the 163.Nm . 164.It Li retransmitted 165SYN,ACK retransmissions due to a timeout expiring. 166.It Li dupsyn 167Incoming SYN segment matching an existing entry. 168.It Li dropped 169SYNs dropped because SYN,ACK could not be sent. 170.It Li completed 171Successfully completed connections. 172.It Li "bucket overflow" 173Entries dropped for exceeding per-bucket size. 174.It Li "cache overflow" 175Entries dropped for exceeding overall cache size. 176.It Li reset 177RST segment received. 178.It Li stale 179Entries dropped due to maximum retransmissions or listen socket disappearance. 180.It Li aborted 181New socket allocation failures. 182.It Li badack 183Entries dropped due to bad ACK reply. 184.It Li unreach 185Entries dropped due to ICMP unreachable messages. 186.It Li "zone failures" 187Failures to allocate new 188.Nm 189entry. 190.It Li "cookies received" 191Connections created from segment containing ACK. 192.El 193.Sh SEE ALSO 194.Xr netstat 1 , 195.Xr tcp 4 , 196.Xr loader 8 , 197.Xr sysctl 8 198.Sh HISTORY 199The existing 200.Nm 201implementation 202first appeared in 203.Fx 4.5 . 204The original concept of a 205.Nm 206originally appeared in 207.Bsx , 208and was later modified by 209.Nx , 210then further extended here. 211.Sh AUTHORS 212The 213.Nm 214code and manual page were written by 215.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . 216