share/man/man4/syncache.4

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