git: ab14a9ac18e5 - stable/12 - pf.conf: document syncookies

The branch stable/12 has been updated by kp:

URL: https://cgit.FreeBSD.org/src/commit/?id=ab14a9ac18e5c2b681cc6e1d9e5a7f13e453c16a

commit ab14a9ac18e5c2b681cc6e1d9e5a7f13e453c16a
Author:     Kristof Provost <kp@FreeBSD.org>
AuthorDate: 2021-08-14 08:42:03 +0000
Commit:     Kristof Provost <kp@FreeBSD.org>
CommitDate: 2021-10-06 08:46:58 +0000

    pf.conf: document syncookies
    
    Reviewed by:    bcr
    Obtained from:  OpenBSD
    MFC after:      1 week
    Sponsored by:   Modirum MDPay
    Differential Revision:  https://reviews.freebsd.org/D32137
    
    (cherry picked from commit 20f015f08d66d0d953e49245cb95c81c118b9ee9)
---
 share/man/man5/pf.conf.5 | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 48902f11cf15..f75edb6fcc17 100644
--- a/share/man/man5/pf.conf.5
+++ b/share/man/man5/pf.conf.5
@@ -28,7 +28,7 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd April 19, 2021
+.Dd September 25, 2021
 .Dt PF.CONF 5
 .Os
 .Sh NAME
@@ -540,6 +540,34 @@ For example:
 .Bd -literal -offset indent
 set state-policy if-bound
 .Ed
+.It Ar set syncookies never | always | adaptive
+When
+.Cm syncookies
+are active, pf will answer each incoming TCP SYN with a syncookie SYNACK,
+without allocating any resources.
+Upon reception of the client's ACK in response to the syncookie
+SYNACK, pf will evaluate the ruleset and create state if the ruleset
+permits it, complete the three way handshake with the target host and
+continue the connection with synproxy in place.
+This allows pf to be resilient against large synflood attacks which would
+run the state table against its limits otherwise.
+Due to the blind answers to every incoming SYN syncookies share the caveats of
+synproxy, namely seemingly accepting connections that will be dropped later on.
+.Pp
+.Bl -tag -width adaptive -compact
+.It Cm never
+pf will never send syncookie SYNACKs (the default).
+.It Cm always
+pf will always send syncookie SYNACKs.
+.It Cm adaptive
+pf will enable syncookie mode when a given percentage of the state table
+is used up by half-open TCP connections, as in, those that saw the initial
+SYN but didn't finish the three way handshake.
+The thresholds for entering and leaving syncookie mode can be specified using
+.Bd -literal -offset indent
+set syncookies adaptive (start 25%, end 12%)
+.Ed
+.El
 .It Ar set state-defaults
 The
 .Ar state-defaults