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