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