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