From 3bdd42986130aad7cbc8f2e104385b83f9c8e43e Mon Sep 17 00:00:00 2001
From: henning <henning@openbsd.org>
Date: Thu, 8 Feb 2018 09:14:19 +0000
Subject: [PATCH] give jmc another chance to "fix previous" - document
 syncookies (thanks jmc!)

---
 share/man/man5/pf.conf.5 | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 9c22845165a..77994dc6ee3 100644
--- a/share/man/man5/pf.conf.5
+++ b/share/man/man5/pf.conf.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pf.conf.5,v 1.571 2017/11/13 18:18:53 jmc Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.572 2018/02/08 09:14:19 henning Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" Copyright (c) 2003 - 2013 Henning Brauer <henning@openbsd.org>
@@ -28,7 +28,7 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 13 2017 $
+.Dd $Mdocdate: February 8 2018 $
 .Dt PF.CONF 5
 .Os
 .Sh NAME
@@ -1355,6 +1355,35 @@ States are bound to an interface.
 .It Cm floating
 States can match packets on any interfaces (the default).
 .El
+.It Ic set Cm syncookies never | always | adaptive
+When
+.Cm syncookies
+are active, pf will answer each and every incoming tcp SYN with a
+syncookie SYNACK, without allocating any ressources.
+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 each and every 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.
+.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 Ic set Cm timeout Ar variable value
 .Bl -tag -width "src.track" -compact
 .It Cm frag
-- 
2.20.1