Document the new flow queue specification

With input and OK sthen

1 files changed, 46 insertions, 5 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index e0e8e897768..e67dc1cbe55 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.557 2017/01/17 21:08:34 jmc Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.558 2017/05/15 11:24:37 mikeb 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: January 17 2017 $
+.Dd $Mdocdate: May 15 2017 $
 .Dt PF.CONF 5
 .Os
 .Sh NAME
@@ -48,7 +48,7 @@ including network address translation (NAT).
 .It Sx OPTIONS
 globally tune the behaviour of the packet filtering engine.
 .It Sx QUEUEING
-provides rule-based bandwidth control.
+provides rule-based bandwidth and traffic control.
 .It Sx TABLES
 provide a method for dealing with large numbers of addresses.
 .It Sx ANCHORS
@@ -1564,6 +1564,44 @@ pass out on em0 inet proto tcp from any to any port 22 \e
 pass out on em0 inet proto tcp from any to any port 25 \e
       set queue mail
 .Ed
+.Pp
+Additionally to the bandwidth management a fair traffic sharing option
+is provided via a flow queue.
+When packets are classified by the stateful inspection engine, a flow
+identifier is assigned to all packets belonging to this state.
+A flow queue splits the outgoing traffic according to these identifiers
+into individual queues and services them in a way that provides equal
+opportunities for all connections to progress.
+.Pp
+Configuration of a flow queue is similar to a regular one, however flow
+queues don't build a hierarchy and thus only one flow queue may be
+specified per interface.
+.Pp
+The core parameter of a flow queue is a number of expected simultaneous
+connections, or
+.Cm flows ,
+bounded by the resolution of the flow identifier (the current
+implementation is able to classify traffic into 32767 distinct flows).
+Thus minimal flow queue configuration is:
+.Bd -literal -offset indent
+queue fq on em0 flows 1024
+.Ed
+.Pp
+Another value affecting the flow queue is a quantum of service.
+The lower the
+.Cm quantum
+the more advantage is given to streams of small packets at the expense
+of bulk transfers.
+The default value for
+.Cm quantum
+is selected based on the configured Maximum Transmission Unit (MTU)
+of the specified interface.
+.Pp
+An additional configuration option
+.Cm qlimit
+sets the queue depth shared among all flows.
+The default is 1024.
+.El
 .Sh TABLES
 Tables are named structures which can hold a collection of addresses and
 networks.
@@ -2695,9 +2733,12 @@ anchor-close   = "}"
 load-anchor    = "load anchor" string "from" filename
 
 queueopts-list = queueopts-list queueopts | queueopts
-queueopts      = [ "bandwidth" bandwidth ] | [ "min" bandwidth ] |
+queueopts      = ([ "bandwidth" bandwidth ] | [ "min" bandwidth ] |
                  [ "max" bandwidth ] | [ "parent" string ] |
-                 [ "default" ] | [ "qlimit" number ]
+                 [ "default" ]) |
+                 ([ "flows" number ] | [ "quantum" number ]) |
+                 [ "qlimit" number ]
+
 bandwidth      = bandwidth-spec [ "burst" bandwidth-spec "for" number "ms" ]
 bandwidth-spec = number ( "" | "K" | "M" | "G" )