Document the fact that 'flags S/SA keep state' is now the implicit default,

as well as 'no state' and 'flags any' options.

ok jmc@

1 files changed, 85 insertions, 83 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index c6dea2f5905..18a3b50561e 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.355 2006/09/12 13:39:37 jmc Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.356 2006/10/06 10:48:46 mcbride Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -93,8 +93,8 @@ For example,
 .Bd -literal -offset indent
 ext_if = \&"kue0\&"
 all_ifs = \&"{\&" $ext_if lo0 \&"}\&"
-pass out on $ext_if from any to any keep state
-pass in  on $ext_if proto tcp from any to any port 25 keep state
+pass out on $ext_if from any to any
+pass in  on $ext_if proto tcp from any to any port 25 
 .Ed
 .Sh TABLES
 Tables are named structures which can hold a collection of addresses and
@@ -359,8 +359,10 @@ set limit states 20000
 .Pp
 sets the maximum number of entries in the memory pool used by state table
 entries (generated by
-.Ar keep state
-rules) to 20000.
+.Ar pass
+rules which do not specify
+.Ar no state
+) to 20000.
 Using
 .Bd -literal -offset indent
 set limit frags 20000
@@ -987,13 +989,13 @@ queue  ssh_bulk bandwidth 50% priority 0 cbq(borrow)
 
 block return out on dc0 inet all queue std
 pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e
-      keep state queue developers
+      queue developers
 pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e
-      keep state queue employees
+      queue employees
 pass out on dc0 inet proto tcp from any to any port 22 \e
-      keep state queue(ssh_bulk, ssh_interactive)
+      queue(ssh_bulk, ssh_interactive)
 pass out on dc0 inet proto tcp from any to any port 25 \e
-      keep state queue mail
+      queue mail
 .Ed
 .Sh TRANSLATION
 Translation rules modify either the source or destination address of the
@@ -1212,12 +1214,9 @@ nor
 are specified, the rule will match packets in both directions.
 .It Ar log
 In addition to the action specified, a log message is generated.
-All packets for that connection are logged, unless the
-.Ar keep state ,
-.Ar modulate state
-or
-.Ar synproxy state
-options are specified, in which case only the
+Unless the
+.Ar no state
+option is specified, only the
 packet that establishes the state is logged.
 (See
 .Ar keep state ,
@@ -1236,12 +1235,10 @@ in
 .Xr pcap 3
 binary format.
 .It Ar log (all)
-Used with
-.Ar keep state ,
-.Ar modulate state
-or
-.Ar synproxy state
-rules to force logging of all packets for a connection.
+Used to force logging of all packets for a connection.
+This is not necessary when
+.Ar no state
+is explicitly specified.
 As with
 .Ar log ,
 packets are logged to
@@ -1407,7 +1404,7 @@ pass in proto tcp from any port \*(Le 1024 to any
 pass in proto tcp from any to any port 25
 pass in proto tcp from 10.0.0.0/8 port \*(Gt 1024 \e
       to ! 10.1.2.3 port != ssh
-pass in proto tcp from any os "OpenBSD" flags S/SA
+pass in proto tcp from any os "OpenBSD"
 pass in proto tcp from route "DTAG"
 .Ed
 .It Ar all
@@ -1465,12 +1462,12 @@ The following example allows only selected users to open outgoing
 connections:
 .Bd -literal -offset indent
 block out proto { tcp, udp } all
-pass  out proto { tcp, udp } all \e
-      user { \*(Lt 1000, dhartmei } keep state
+pass  out proto { tcp, udp } all user { \*(Lt 1000, dhartmei } 
 .Ed
 .It Xo Ar flags Aq Ar a
 .Pf / Ns Aq Ar b
 .No \*(Ba / Ns Aq Ar b
+.No \*(Ba any
 .Xc
 This rule only applies to TCP packets that have the flags
 .Aq Ar a
@@ -1479,12 +1476,17 @@ set out of set
 Flags not specified in
 .Aq Ar b
 are ignored.
+For stateful connections, the default is
+.Ar flags S/SA .
+To indicate that flags should not be checkd at all, specify 
+.Ar flags any .
 The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R.
 .Bl -tag -width Fl
 .It Ar flags S/S
 Flag SYN is set.
 The other flags are ignored.
 .It Ar flags S/SA
+This is the default setting for stateful connections.
 Out of SYN and ACK, exactly SYN may be set.
 SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not.
 This is more restrictive than the previous example.
@@ -1764,17 +1766,15 @@ See
 for more ways to control the source tracking.
 .Sh STATEFUL INSPECTION
 .Xr pf 4
-is a stateful packet filter, which means it can track the state of
-a connection.
-Instead of passing all traffic to port 25, for instance, it is possible
-to pass only the initial packet, and then begin to keep state.
+is a stateful packet filter,
+which means it tracks the state of a connection.
+A connection 's state is tracked by default, unless
+.Ar no state
+is specified.
+Instead of passing all traffic to port 25, for instance, it will
+to pass only the initial packet, and then begin to keep state
 Subsequent traffic will flow because the filter is aware of the connection.
 .Pp
-If a packet matches a
-.Ar pass ... keep state
-rule, the filter creates a state for this connection and automatically
-lets pass all subsequent packets of that connection.
-.Pp
 Before any rules are evaluated, the filter checks whether the packet
 matches any state.
 If it does, the packet is passed without evaluation of any rules.
@@ -1823,22 +1823,39 @@ keywords to the
 .Ar keep state
 option.
 .Pp
-Specifying
+Because
+.Ar keep state
+and
 .Ar flags S/SA
-restricts state creation to the initial SYN
-packet of the TCP handshake.
+are enabled implicitly, they do not need to be specified.
+The following pass rules are equivalent to those in the example above:
+.Bd -literal -offset indent
+pass out proto tcp from any to any 
+pass in  proto tcp from any to any port 25
+.Ed
+.Pp
+By default, only the initial SYN packet of a TCP handshake will create a
+state for a TCP connection.
 One can also be less restrictive, and allow state creation from
 intermediate
 .Pq non-SYN
-packets.
+packets, by specifying an empty set of flags:
+.Ar flags /
 This will cause
 .Xr pf 4
 to synchronize to existing connections, for instance
 if one flushes the state table.
+However, states created from such intermediate packets may be missing 
+connection details such as the TCP window scaling factor.
+States created with 
+.Ar modulate state
+or scrubbed with 
+.Ar reassmble tcp
+will also not be recoverable from intermediate packets.
+Such connections will stall and time out.
 .Pp
-For UDP, which is stateless by nature,
-.Ar keep state
-will create state as well.
+.Xr pf 4
+will also create state for UDP packets, although it is stateless by nature.
 UDP packets are matched to states using only host addresses and ports.
 .Pp
 ICMP messages fall into two categories: ICMP error messages, which always
@@ -1886,25 +1903,10 @@ For instance:
 .Bd -literal -offset indent
 block all
 pass out proto tcp from any to any modulate state
-pass in  proto tcp from any to any port 25 flags S/SA modulate state
+pass in  proto tcp from any to any port 25 flags S/SFRA modulate state
 .Ed
 .Pp
-There are two caveats associated with state modulation:
-A
-.Ar modulate state
-rule can not be applied to a pre-existing but unmodulated connection.
-Such an application would desynchronize TCP's strict
-sequencing between the two endpoints.
-Instead,
-.Xr pf 4
-will treat the
-.Ar modulate state
-modifier as a
-.Ar keep state
-modifier and the pre-existing connection will be inferred without
-the protection conferred by modulation.
-.Pp
-The other caveat affects currently modulated states when the state table
+Note that modulated connections will not recover when the state table
 is lost (firewall reboot, flushing the state table, etc...).
 .Xr pf 4
 will not be able to infer a connection again after the state table flushes
@@ -1913,11 +1915,11 @@ When the state is lost, the connection may be left dangling until the
 respective endpoints time out the connection.
 It is possible on a fast local network for the endpoints to start an ACK
 storm while trying to resynchronize after the loss of the modulator.
-Using a
-.Ar flags S/SA
-modifier on
+The default 
+.Ar flags
+settings (or a more strict equivalent) should be used on
 .Ar modulate state
-rules between fast networks is suggested to prevent ACK storms.
+rules to prevent ACK storms.
 .Pp
 Note that alternative methods are available
 to prevent loss of the state table
@@ -1968,7 +1970,7 @@ operates on a
 .Pp
 Example:
 .Bd -literal -offset indent
-pass in proto tcp from any to any port www flags S/SA synproxy state
+pass in proto tcp from any to any port www synproxy state
 .Ed
 .Sh STATEFUL TRACKING OPTIONS
 All three of
@@ -1999,7 +2001,7 @@ above.
 Multiple options can be specified, separated by commas:
 .Bd -literal -offset indent
 pass in proto tcp from any to any \e
-      port www flags S/SA keep state \e
+      port www keep state \e
       (max 100, source-track rule, max-src-nodes 75, \e
       max-src-states 3, tcp.established 60, tcp.closing 5)
 .Ed
@@ -2082,7 +2084,7 @@ Any new packets arriving from this host will be dropped unconditionally
 by the block rule.
 .Bd -literal -offset indent
 block quick from \*(Ltbad_hosts\*(Gt
-pass in on $ext_if proto tcp to $webserver port www flags S/SA keep state \e
+pass in on $ext_if proto tcp to $webserver port www keep state \e
 	(max-src-conn-rate 100/10, overload \*(Ltbad_hosts\*(Gt flush global)
 .Ed
 .Sh OPERATING SYSTEM FINGERPRINTING
@@ -2140,12 +2142,12 @@ which no operating system fingerprint is known.
 .Pp
 Examples:
 .Bd -literal -offset indent
-pass  out proto tcp from any os OpenBSD keep state
+pass  out proto tcp from any os OpenBSD
 block out proto tcp from any os Doors
 block out proto tcp from any os "Doors PT"
 block out proto tcp from any os "Doors PT SP3"
 block out from any os "unknown"
-pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" keep state
+pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0"
 .Ed
 .Pp
 Operating system fingerprinting is limited only to the TCP SYN packet.
@@ -2355,9 +2357,9 @@ For example,
 ext_if = \&"kue0\&"
 block on $ext_if all
 anchor spam
-pass out on $ext_if all keep state
+pass out on $ext_if all
 pass in on $ext_if proto tcp from any \e
-      to $ext_if port smtp keep state
+      to $ext_if port smtp
 .Ed
 .Pp
 blocks all packets on the external interface by default, then evaluates
@@ -2405,8 +2407,8 @@ This allows conditional evaluation of anchors, like:
 .Bd -literal -offset indent
 block on $ext_if all
 anchor spam proto tcp from any to any port smtp
-pass out on $ext_if all keep state
-pass in on $ext_if proto tcp from any to $ext_if port smtp keep state
+pass out on $ext_if all
+pass in on $ext_if proto tcp from any to $ext_if port smtp
 .Ed
 .Pp
 The rules inside
@@ -2624,15 +2626,15 @@ block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e
 # so replies (like 0/0 for 8/0) will match queries
 # ICMP error messages (which always refer to a TCP/UDP packet) are
 # handled by the TCP/UDP states
-pass on $ext_if inet proto icmp all icmp-type 8 code 0 keep state
+pass on $ext_if inet proto icmp all icmp-type 8 code 0 
 
 # UDP
 
 # pass out all UDP connections and keep state
-pass out on $ext_if proto udp all keep state
+pass out on $ext_if proto udp all
 
 # pass in certain UDP connections and keep state (DNS)
-pass in on $ext_if proto udp from any to any port domain keep state
+pass in on $ext_if proto udp from any to any port domain
 
 # TCP
 
@@ -2641,7 +2643,7 @@ pass out on $ext_if proto tcp all modulate state
 
 # pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT)
 pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e
-      auth } flags S/SA keep state
+      auth }
 
 # Do not allow Windows 9x SMTP connections since they are typically
 # a viral worm. Alternately we could limit these OSes to 1 connection each.
@@ -2651,8 +2653,8 @@ block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e
 # IPv6
 # pass in/out all IPv6 traffic: note that we have to enable this in two
 # different ways, on both our physical interface and our tunnel
-pass quick on gif0 inet6 keep state
-pass quick on $ext_if proto ipv6 keep state
+pass quick on gif0 inet6
+pass quick on $ext_if proto ipv6
 
 # Packet Tagging
 
@@ -2662,12 +2664,12 @@ pass quick on $ext_if proto ipv6 keep state
 # outgoing packets (i.e., packets from the wireless network) are only
 # permitted to access port 80.
 
-pass in on $int_if from any to any tag INTNET keep state
-pass in on $wifi_if from any to any keep state
+pass in on $int_if from any to any tag INTNET
+pass in on $wifi_if from any to any
 
 block out on $ext_if from any to any
-pass out quick on $ext_if tagged INTNET keep state
-pass out on $ext_if proto tcp from any to any port 80 keep state
+pass out quick on $ext_if tagged INTNET
+pass out on $ext_if proto tcp from any to any port 80
 
 # tag incoming packets as they are redirected to spamd(8). use the tag
 # to pass those packets through the packet filter.
@@ -2676,7 +2678,7 @@ rdr on $ext_if inet proto tcp from \*(Ltspammers\*(Gt to port smtp \e
 	tag SPAMD -\*(Gt 127.0.0.1 port spamd
 
 block in on $ext_if
-pass in on $ext_if inet proto tcp tagged SPAMD keep state
+pass in on $ext_if inet proto tcp tagged SPAMD
 .Ed
 .Sh GRAMMAR
 Syntax for
@@ -2710,7 +2712,7 @@ logopt         = "all" | "user"
 
 filteropt-list = filteropt-list filteropt | filteropt
 filteropt      = user | group | flags | icmp-type | icmp6-type | tos |
-                 ( "keep" | "modulate" | "synproxy" ) "state"
+                 ( "no" | "keep" | "modulate" | "synproxy" ) "state"
                  [ "(" state-opts ")" ] |
                  "fragment" | "no-df" | "min-ttl" number |
                  "max-mss" number | "random-id" | "reassemble tcp" |
@@ -2819,7 +2821,7 @@ op-list        = ( unary-op | binary-op ) [ [ "," ] op-list ]
 os-name        = operating-system-name
 os-list        = os-name [ [ "," ] os-list ]
 
-flags          = "flags" [ flag-set ] "/" flag-set
+flags          = "flags" ( [ flag-set ] "/"  flag-set | "any" )
 flag-set       = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ]
                  [ "W" ]