TCP SYN Cookies

This filter is an alternative to standard SYN cookies. Thanks to its XDP-based implementation, it can mitigate significantly larger SYN flood attacks.

The filter works only in host mode (see Local host protection).

To use this filter, the Linux kernel must be compiled with SYN cookie support (CONFIG_SYN_COOKIES=y), which is usually enabled by default.

The net.ipv4.tcp_syncookies sysctl must be enabled. xfwctl sets it from the configuration file, for example:

cat xfw.json
{
    ...
    "sysctl-tcp-max-syn-backlog": 4096,
    "sysctl-tcp-syncookies": 1
}

Set the value to 1 to use the bimodal operation, with passive and flood modes, and avoid the overhead of generating a cookie for every TCP handshake. Set it to 2 for debugging purposes to generate a cookie for every SYN (see the kernel documentation).

The algorithm starts in passive mode, in which Tempesta xFW sends a SYN cookie at most once per passive_timer. If the Linux kernel determines that a SYN cookie should be generated, the cookie is sent to the client and the algorithm transitions to flood mode.

In flood mode, the kernel is queried once per flood_timer interval to determine whether SYN cookies should continue to be generated. When the kernel decides that the SYN flood has stopped, the algorithm transitions back to passive mode.

The Linux kernel decides whether a SYN cookie should be generated, i.e. whether the system is experiencing a SYN flood, based on whether the SYN queue of a listening socket overflows (exceeds the net.ipv4.tcp_max_syn_backlog value). If net.ipv4.tcp_syncookies is set to 0, the kernel never enters SYN flood protection mode.

Looking up a listening socket for each received packet is a relatively expensive operation. Increasing the value of passive_timer reduces the overhead of the SYN cookies mechanism, but also increases the response time to a SYN flood. Similarly, larger values of flood_timer reduce system overhead during an attack, but prolong the overall SYN cookies overhead after the attack has ended.

Example rule for the filter with recommended values (time is specified in seconds):

tcp_syncookies passive_timer=1 flood_timer=1;

By default, both passive_timer and flood_timer are set to 1 second.

Zero timer values are not recommended for normal operation and have different effects:

• passive_timer=0 allows a passive SYN-cookie attempt for every eligible SYN.
• flood_timer=0 keeps flood mode active only for the kernel tick in which a cookie was generated. A client ACK will normally arrive after that tick and bypass xFW SYN-cookie validation, although the Linux kernel can still accept it.

Use a positive flood_timer when xFW must validate cookie ACKs and account them in xfw_syncookie_received_packets.

The functionality can be disabled with the following command:

tcp_syncookies/del;

Tempesta xFW exports SYN cookie packet and byte counters as Prometheus metrics:

curl --silent --show-error http://127.0.0.1:9090/metrics | grep '^xfw_syncookie'
xfw_syncookie_received_packets 0
xfw_syncookie_received_bytes 0
xfw_syncookie_failed_packets 0
xfw_syncookie_failed_bytes 0
xfw_syncookie_generated_packets 1000000
xfw_syncookie_generated_bytes 60000000

The _packets metrics count packets. The _bytes metrics sum the sizes of those packets.

The kernel exposes its counters in /proc/net/netstat:

grep -A1 '^TcpExt: SyncookiesSent' /proc/net/netstat | awk '{print $2, $3, $4}'
SyncookiesSent SyncookiesRecv SyncookiesFailed
426057 127017 40592

The counters have the following meanings:

xFW runs at XDP before the Linux TCP stack. The following stages explain which component processes each TCP handshake segment and how its counters change:

1. The client sends a SYN. xFW first applies its common packet checks. A packet rejected before the SYN cookie filter does not increment an xFW SYN cookie counter.
2. In passive mode, xFW attempts SYN cookie generation only when the per-CPU passive_timer interval has elapsed. If the interval has not elapsed, or the kernel reports that a cookie is not required, xFW passes the SYN to the TCP stack without incrementing an xFW SYN cookie counter. The kernel then processes the SYN normally. If it generates a SYN cookie, SyncookiesSent increments.
3. If xFW generates the cookie, it converts the received SYN into a SYN-ACK, returns the packet through XDP, and increments xfw_syncookie_generated_*. The original SYN does not reach the TCP stack, so this path does not increment SyncookiesSent. Successful generation starts or extends xFW’s per-CPU flood window. While this window is active, xFW attempts cookie generation for every eligible SYN.
4. The client replies with the final ACK. While the per-CPU flood window is active, xFW validates the cookie unless TCP authentication already marks the connection as trusted. A valid cookie increments xfw_syncookie_received_*; xFW then passes the ACK to the TCP stack, which normally accepts the same cookie and increments SyncookiesRecv. Thus, one ACK can increment both counters.
5. If xFW rejects the final ACK, xfw_syncookie_failed_* increments and the packet is dropped at XDP. The TCP stack does not see that ACK, so it cannot increment either SyncookiesRecv or SyncookiesFailed for the packet.
6. Outside xFW’s flood window, or when cookie validation is otherwise bypassed, xFW does not increment a SYN cookie counter. If the ACK reaches the TCP stack, the kernel can increment SyncookiesRecv for a valid cookie or SyncookiesFailed for an invalid cookie.

The xFW and kernel counters are independent and must not be added to calculate a total number of handshakes. In particular, xfw_syncookie_failed_* and SyncookiesFailed are not equivalent: the xFW counter covers both SYN-side and ACK-side failures, whereas the kernel counter applies to cookie ACK validation. Counters also need not balance because clients may not complete the handshake and because xFW’s passive and flood state is maintained separately on each CPU.