MFC r1.6 r1.15 (HEAD)
authorThomas Nikolajsen <thomas@dragonflybsd.org>
Tue, 16 Sep 2008 21:46:59 +0000 (16 21:46 +0000)
committerThomas Nikolajsen <thomas@dragonflybsd.org>
Tue, 16 Sep 2008 21:46:59 +0000 (16 21:46 +0000)
Update pf.conf.5:
   - add line break after sentence
   - add description for `set keep-policy'
   - drop note that RIO isn't in GENERIC kernel,
  as this applies to OpenBSD when pf.conf.5 was imported;
  in DragonFly altq isn't in GENERIC kernel at all
   - fix GRAMMAR by adding `set keep-policy', and `no state',
  fixing scheduler defs and dropping unneeded parens & brackets
   - improve mark up a bit

usr.sbin/pfctl/parse.y
usr.sbin/pfctl/pf.conf.5

index 8f4963d..ffaa7a5 100644 (file)
@@ -1,5 +1,5 @@
 /*     $OpenBSD: parse.y,v 1.449 2004/03/20 23:20:20 david Exp $       */
-/*     $DragonFly: src/usr.sbin/pfctl/parse.y,v 1.5 2008/04/11 18:21:49 dillon Exp $ */
+/*     $DragonFly: src/usr.sbin/pfctl/parse.y,v 1.5.2.1 2008/09/16 21:46:59 thomas Exp $ */
 
 /*
  * Copyright (c) 2001 Markus Friedl.  All rights reserved.
@@ -519,7 +519,7 @@ option              : SET OPTIMIZATION STRING               {
                                YYERROR;
                        }
                        if (pfctl_set_hostid(pf, $3) != 0) {
-                               yyerror("error setting loginterface %08x", $3);
+                               yyerror("error setting hostid %08x", $3);
                                YYERROR;
                        }
                }
index 4fa2796..e41bdb5 100644 (file)
@@ -1,5 +1,5 @@
 .\"    $OpenBSD: pf.conf.5,v 1.291 2004/02/04 19:38:30 jmc Exp $
-.\"    $DragonFly: src/usr.sbin/pfctl/pf.conf.5,v 1.14 2008/04/15 23:00:52 swildner Exp $
+.\"    $DragonFly: src/usr.sbin/pfctl/pf.conf.5,v 1.14.2.1 2008/09/16 21:46:59 thomas Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -418,9 +418,20 @@ set optimization aggressive
 .It Ar set keep-policy keep_rule
 The
 .Ar keep-policy
-option sets the default state retention policy for all pass rules.
-Any keep/modulate/synproxy state directives in a pass rule will overriide
-the default.
+option sets the default state retention policy for all
+.Ar pass
+rules.
+See
+.Sx STATEFUL TRACKING OPTIONS
+or
+.Sx GRAMMAR
+(keep) for format of
+.Ar keep_rule .
+Any
+.Ar no Ns / Ns Ar keep Ns / Ns Ar modulate Ns / Ns Ar synproxy state
+directives in a
+.Ar pass
+rule will override the default.
 For example:
 .Bd -literal -offset indent
 set keep-policy keep state (pickups)
@@ -656,7 +667,7 @@ The
 .Ar scheduler
 defines the algorithm used to decide which packets get delayed, dropped, or
 sent out immediately.
-There are three
+There are four
 .Ar schedulers
 currently supported.
 .Bl -tag -width xxxx
@@ -716,12 +727,18 @@ are flat attached to the interface, thus,
 .Ar queues
 cannot have further child
 .Ar queues .
-Each queue must be given a unique priority and one must be marked
+Each queue must be given a unique
+.Ar priority
+and one must be marked
 as the default queue.
-Each queue implements a number of buckets (default 256) which sorts the
+Each queue implements a number of
+.Ar buckets
+(default 256) which sorts the
 traffic based on a hash key generated by the
 .Ar keep state
-facility in your pass rules.
+facility in your
+.Ar pass
+rules.
 Each bucket contains a list of packets controlled by
 .Ar qlimit .
 In order for
@@ -730,10 +747,11 @@ to function properly,
 .Ar keep state
 must be enabled on most of the rule sets that route packets to the queue.
 Any rules for which keep state is not enabled are added to the end of the
-queue.  If you do not wish keep state to do TCP sequence space checks use
-.Ar keep state ( no-pickups )
+queue.
+If you do not wish keep state to do TCP sequence space checks use
+.Ar "keep state (no-pickups)"
 or
-.Ar keep state ( hash-only ) .
+.Ar "keep state (hash-only)" .
 .Pp
 Packet selection operates as follows:
 The queues are scanned from highest priority to lowest priority.
@@ -747,7 +765,9 @@ regardless of whether it has reached its bandwidth limit or not.
 .Pp
 A
 .Ar fairq
-round robins between its buckets, extracting one packet from each bucket.
+round robins between its
+.Ar buckets ,
+extracting one packet from each bucket.
 This essentially prevents large backlogs of packets from high volume
 connections from destroying the interactive response of other connections.
 .Pp
@@ -757,12 +777,12 @@ parameter for a
 .Ar fairq
 is guaranteed minimum and more will be used if no higher priority traffic is
 present.
-Creating a queue with one bucket as a catch-all for pass rules
-not characterized by
+Creating a queue with one bucket as a catch-all for
+.Ar pass
+rules not characterized by
 .Ar keep state
 is supported.
-Such a queue serves as a basic priority queue with a bandwidth
-specification.
+Such a queue serves as a basic priority queue with a bandwidth specification.
 .El
 .Pp
 The interfaces on which queueing should be activated are declared using
@@ -840,7 +860,9 @@ must match a queue defined in the
 .Ar altq
 directive (e.g.\& mail), or, except for the
 .Ar priq
-.Ar scheduler ,
+and
+.Ar fairq
+.Ar schedulers ,
 in a parent
 .Ar queue
 declaration.
@@ -880,7 +902,7 @@ queues with a higher priority are served first unless they exceed their
 bandwidth specification.
 .Ar Cbq
 and
-.Ar Hfsc
+.Ar hfsc
 queues with a higher priority are preferred in the case of overload.
 .It Ar qlimit <limit>
 The maximum number of packets held in the queue.
@@ -893,7 +915,7 @@ this specified the maximum number of packets held per bucket.
 The
 .Ar scheduler
 can get additional parameters with
-.Ar <scheduler> Ns Li (\& Ar <parameters> No ) .
+.Ar "<scheduler>(<parameters>)" .
 Parameters are as follows:
 .Bl -tag -width Fl
 .It Ar default
@@ -907,7 +929,6 @@ queue length.
 Enables RIO on this queue.
 RIO is RED with IN/OUT, thus running
 RED two times more than RIO would achieve the same effect.
-RIO is currently not supported in the GENERIC kernel.
 .It Ar ecn
 Enables ECN (Explicit Congestion Notification) on this queue.
 ECN implies RED.
@@ -956,11 +977,14 @@ The maximum allowed bandwidth for the queue.
 The bandwidth share of a backlogged queue.
 .El
 .Pp
-<sc> is an acronym for
+.Ar <sc>
+is an acronym for
 .Ar service curve .
 .Pp
 The format for service curve specifications is
-.Ar ( m1 , d , m2 ) .
+.Ar m2
+or
+.Ar "(m1 d m2)" .
 .Ar m2
 controls the bandwidth assigned to the queue.
 .Ar m1
@@ -1746,7 +1770,8 @@ Subsequent traffic will flow because the filter is aware of the connection.
 You can turn on stateful inspection on all pass rules by default using
 the
 .Ar set keep-policy
-directive.  Any pass rule may specify or override the stateful inspection
+directive.
+Any pass rule may specify or override the stateful inspection
 default, including turning it off by specifying
 .Ar no state .
 .Pp
@@ -1830,11 +1855,13 @@ packets.
 This will cause
 .Xr pf 4
 to synchronize to existing connections, for instance
-if one flushes the state table.  If you do this you must use the
+if one flushes the state table.
+If you do this you must use the
 .Ar pickups
 option or
 .Ar keep state
-will blow up on TCP connections with window scaling turned on.  The
+will blow up on TCP connections with window scaling turned on.
+The
 .Ar pickups
 option tells keep state to skip sequence space checks on connections
 for which no window scaling information is known (meaning it didn't see
@@ -1998,9 +2025,10 @@ have state table entries.
 Limits the maximum number of simultaneous state entries that a single
 source address can create with this rule.
 .It Ar pickups
-Specify that mid-stream pickups are to be allowed.  The default
-is to NOT allow mid-stream pickups and implies flags S/SA for TCP
-connections.   If pickups are enabled, flags S/SA are not implied
+Specify that mid-stream pickups are to be allowed.
+The default is to NOT allow mid-stream pickups and implies flags
+S/SA for TCP connections.
+If pickups are enabled, flags S/SA are not implied
 for TCP connections and state can be created for any packet.
 .Pp
 The implied flags parameters need not be specified in either case
@@ -2013,16 +2041,20 @@ TCP pickups and sequence space comparisons must be disabled.
 .Pp
 This does not effect state representing fully quantified
 connections (for which the SYN/SYN-ACK passed through the routing
-engine).  Those connections continue to be fully validated.
+engine).
+Those connections continue to be fully validated.
 .It Ar hash-only
 Specify that mid-stream pickups are to be allowed, but unconditionally
 disables sequence space checks even if full state is available.
 .It Ar no-pickups
-Specify that mid-stream pickups are not to be allowed.  This is the
+Specify that mid-stream pickups are not to be allowed.
+This is the
 default and this keyword does not normally need to be specified.
 However, if you are concerned about rule set portability then
-specifying this keyword will at least result in an error from pfctl
-if it doesn't understand the feature.   TCP flags of S/SA are implied
+specifying this keyword will at least result in an error from
+.Xr pfctl 8
+if it doesn't understand the feature.
+TCP flags of S/SA are implied
 and do not need to explicitly specified.
 .El
 .Pp
@@ -2607,9 +2639,9 @@ Syntax for
 .Nm
 in BNF:
 .Bd -literal
-line           = option | pf-rule | nat-rule | binat-rule | rdr-rule |
+line           = option | pf-rule | nat-rule | binat-rule | rdr-rule |
                  antispoof-rule | altq-rule | queue-rule | anchor-rule |
-                 trans-anchors | load-anchors | table-rule )
+                 trans-anchors | load-anchors | table-rule
 
 option         = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] |
                  [ "optimization" [ "default" | "normal" |
@@ -2618,28 +2650,31 @@ option         = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] |
                  [ "limit" ( limit-item | "{" limit-list "}" ) ] |
                  [ "loginterface" ( interface-name | "none" ) ] |
                  [ "block-policy" ( "drop" | "return" ) ] |
+                 [ "keep-policy" keep ] |
                 [ "state-policy" ( "if-bound" | "group-bound" |
                  "floating" ) ]
                  [ "require-order" ( "yes" | "no" ) ]
                  [ "fingerprints" filename ] |
                  [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] )
 
-pf-rule        = action [ ( "in" | "out" ) ]
+pf-rule        = action [ "in" | "out" ]
                  [ "log" | "log-all" ] [ "quick" ]
                  [ "on" ifspec ] [ route ] [ af ] [ protospec ]
                  hosts [ filteropt-list ]
 
 filteropt-list = filteropt-list filteropt | filteropt
 filteropt      = user | group | flags | icmp-type | icmp6-type | tos |
-                 ( "keep" | "modulate" | "synproxy" ) "state"
-                 [ "(" state-opts ")" ] |
-                 "fragment" | "no-df" | "min-ttl" number |
+                 keep | "fragment" | "no-df" | "min-ttl" number |
                  "max-mss" number | "random-id" | "reassemble tcp" |
                  fragmentation | "allow-opts" |
                  "label" string | "tag" string | [ ! ] "tagged" string
                  "queue" ( string | "(" string [ [ "," ] string ] ")" ) |
                 "probability" number"%"
 
+keep           = "no" "state" |
+                 ( "keep" | "modulate" | "synproxy" ) "state"
+                 [ "(" state-opts ")" ]
+
 nat-rule       = [ "no" ] "nat" [ "pass" ] [ "on" ifspec ] [ af ]
                  [ protospec ] hosts [ "tag" string ]
                  [ "->" ( redirhost | "{" redirhost-list "}" )
@@ -2674,7 +2709,7 @@ altq-rule      = "altq on" interface-name queueopts-list
 queue-rule     = "queue" string [ "on" interface-name ] queueopts-list
                  subqueue
 
-anchor-rule    = "anchor" string [ ( "in" | "out" ) ] [ "on" ifspec ]
+anchor-rule    = "anchor" string [ "in" | "out" ] [ "on" ifspec ]
                  [ af ] [ "proto" ] [ protospec ] [ hosts ]
 
 trans-anchors  = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string
@@ -2683,18 +2718,18 @@ trans-anchors  = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string
 load-anchor    = "load anchor" anchorname:rulesetname "from" filename
 
 queueopts-list = queueopts-list queueopts | queueopts
-queueopts      = [ "bandwidth" bandwidth-spec ] |
-                 [ "qlimit" number ] | [ "tbrsize" number ] |
-                 [ "priority" number ] | [ schedulers ]
-schedulers     = ( cbq-def | priq-def | hfsc-def )
+queueopts      = "bandwidth" bandwidth-spec |
+                 "qlimit" number | "tbrsize" number |
+                 "priority" number | schedulers
+schedulers     = cbq-def | hfsc-def | priq-def | fairq-def
 bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" )
 
 action         = "pass" | "block" [ return ] | "scrub"
 return         = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] |
                  "return-icmp" [ "(" icmpcode ["," icmp6code ] ")" ] |
                  "return-icmp6" [ "(" icmp6code ")" ]
-icmpcode       = ( icmp-code-name | icmp-code-number )
-icmp6code      = ( icmp6-code-name | icmp6-code-number )
+icmpcode       = icmp-code-name | icmp-code-number
+icmp6code      = icmp6-code-name | icmp6-code-number
 
 ifspec         = ( [ "!" ] interface-name ) | "{" interface-list "}"
 interface-list = [ "!" ] interface-name [ [ "," ] interface-list ]
@@ -2717,16 +2752,16 @@ hosts          = "all" |
 ipspec         = "any" | host | "{" host-list "}"
 host           = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" )
 redirhost      = address [ "/" mask-bits ]
-routehost      = ( interface-name [ address [ "/" mask-bits ] ] )
-address        = interface-name | "(" interface-name ")" | hostname |
-                 ipv4-dotted-quad | ipv6-coloned-hex )
+routehost      = interface-name [ address [ "/" mask-bits ] ]
+address        = interface-name | "(" interface-name ")" | hostname |
+                 ipv4-dotted-quad | ipv6-coloned-hex
 host-list      = host [ [ "," ] host-list ]
 redirhost-list = redirhost [ [ "," ] redirhost-list ]
 routehost-list = routehost [ [ "," ] routehost-list ]
 
 port           = "port" ( unary-op | binary-op | "{" op-list "}" )
 portspec       = "port" ( number | name ) [ ":" ( "*" | number | name ) ]
-os             = "os"  ( os-name | "{" os-list "}" )
+os             = "os" ( os-name | "{" os-list "}" )
 user           = "user" ( unary-op | binary-op | "{" op-list "}" )
 group          = "group" ( unary-op | binary-op | "{" op-list "}" )
 
@@ -2752,11 +2787,11 @@ tos            = "tos" ( "lowdelay" | "throughput" | "reliability" |
                  [ "0x" ] number )
 
 state-opts     = state-opt [ [ "," ] state-opts ]
-state-opt      = "max" number | "no-sync" | timeout |
-                 "source-track" [ ( "rule" | "global" ) ] |
+state-opt      = "max" number | "no-sync" | timeout |
+                 "source-track" [ "rule" | "global" ] |
                 "max-src-nodes" number | "max-src-states" number |
                  "if-bound" | "group-bound" | "floating" |
-                "pickups" | "no-pickups" | "hash-only" )
+                "pickups" | "no-pickups" | "hash-only"
 
 fragmentation  = [ "fragment reassemble" | "fragment crop" |
                  "fragment drop-ovl" ]
@@ -2774,23 +2809,34 @@ limit-list     = limit-item [ [ "," ] limit-list ]
 limit-item     = ( "states" | "frags" | "src-nodes" ) number
 
 pooltype       = ( "bitmask" | "random" |
-                 "source-hash" [ ( hex-key | string-key ) ] |
+                 "source-hash" [ hex-key | string-key ] |
                  "round-robin" ) [ sticky-address ]
 
 subqueue       = string | "{" queue-list "}"
 queue-list     = string [ [ "," ] string ]
-cbq-def        = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ]
-priq-def       = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ]
-hfsc-def       = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ]
-cbq-opt        = ( "default" | "borrow" | "red" | "ecn" | "rio" )
-priq-opt       = ( "default" | "red" | "ecn" | "rio" )
-hfsc-opt       = ( "default" | "red" | "ecn" | "rio" |
-                 linkshare-sc | realtime-sc | upperlimit-sc )
+
+cbq-def        = "cbq" [ "(" cbq-opts ")" ]
+priq-def       = "priq" [ "(" priq-opts ")" ]
+hfsc-def       = "hfsc" [ "(" hfsc-opts ")" ]
+fairq-def      = "fairq" [ "(" fairq-opts ")" ]
+
+cbq-opts       = cbq-opt [ [ "," ] cbq-opts ]
+priq-opts      = priq-opt [ [ "," ] priq-opts ]
+hfsc-opts      = hfsc-opt [ [ "," ] hfsc-opts ]
+fairq-opts     = fairq-opt [ [ "," ] fairq-opts ]
+
+cbq-opt        = "default" | "borrow" | "red" | "ecn" | "rio"
+priq-opt       = "default" | "red" | "ecn" | "rio"
+hfsc-opt       = "default" | "red" | "ecn" | "rio" |
+                 linkshare-sc | realtime-sc | upperlimit-sc
+fairq-opt      = "default" | "red" | "ecn" | "rio" |
+                 "buckets" number | "hogs" number | linkshare-sc
+
 linkshare-sc   = "linkshare" sc-spec
 realtime-sc    = "realtime" sc-spec
 upperlimit-sc  = "upperlimit" sc-spec
-sc-spec        = bandwidth-spec |
-                 "(" bandwidth-spec number bandwidth-spec ")" )
+sc-spec        = bandwidth-spec |
+                 "(" bandwidth-spec number bandwidth-spec ")"
 .Ed
 .Sh SEE ALSO
 .Xr icmp 4 ,