- rework Tables section in the introduction (pointed out by Theo)

- Macros and Tables can appear anywhere in pf.conf
- Since tables are no longer just a rule option, move the section up
  appropriately.

ok dhartmei@

1 files changed, 113 insertions, 109 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 9edde4fad5e..d4a2d837ab3 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.167 2003/01/23 01:51:55 mcbride Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.168 2003/01/23 13:46:45 mcbride Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -40,12 +40,28 @@ packet filter modifies, drops or passes packets according to rules or
 definitions specified in
 .Nm pf.conf .
 .Pp
-There are seven types of statement in
+There are seven types of statement; The following two statement types
+can be placed anywhere in 
 .Nm pf.conf :
 .Bl -tag -width xxxx
 .It Macros
 User-defined variables may be defined and later used, simplifying
-the configuration file.
+the configuration file. (Macros must be defined before the are referenced in
+.Nm pf.conf Ns ).
+.It Tables
+Tables provide a mechanism for increasing the performance and flexibility of
+rules with large numbers of source or destination addresses. 
+.El
+.Pp
+The five statement types below should be grouped and appear in
+.Nm pf.conf
+in the order shown above as this matches the operation of the underlying
+packet filtering engine. By default
+.Xr pfctl 8
+enforces this order (see
+.Pa set require-order
+below).
+.Bl -tag -width xxxx
 .It Options
 Options tune the behaviour of the packet filtering engine.
 .It Traffic Normalization (e.g. Pa scrub Ns )
@@ -59,21 +75,8 @@ other addresses.
 .It Packet Filtering
 Stateful and stateless packet filtering provides rule-based blocking or
 passing of packets.
-.It Table Definition
-Radix tables provide an effective way to match the source or destination
-address of packets against big and changing collections of addresses and
-CIDR networks.
 .El
 .Pp
-The types of statement should be grouped and appear in
-.Nm pf.conf
-in the order shown above as this matches the operation of the underlying
-packet filtering engine. By default
-.Xr pfctl 8
-enforces this order (see
-.Pa set require-order
-below).
-.Pp
 .Sh MACROS
 Much like
 .Xr cpp 1
@@ -96,6 +99,100 @@ For example,
     pass in  on $ext_if proto tcp from any to any port 25 keep state
 .Ed
 .Pp
+.Sh TABLES
+Tables are named structures which can hold a collection of addresses and
+networks.
+Lookups against tables in
+.Xr pf 4
+are quite fast, making a single rule with tables much more efficient, both in
+processor usage and memory consumption, than a large number of rules which
+differ only in IP address (either created explicitly or automatically by rule
+expansion).
+.Pp
+Tables can be used as the source or destination of filter rules,
+.Pa scrub
+rules
+or
+translation rules such as
+.Pa nat
+or
+.Pa rdr 
+(see below for details on the various rule types).
+Tables cannot be used for things like the redirect address of
+translation rules, nor can they be used in the routing options of
+filter rules.
+.Pp
+Tables can be defined with any of the following
+.Xr pfctl 8
+mechanisms. As with Macros, reserved words may not be used as table names.
+.Bl -tag -width "manually"
+.It Pa manually
+Persistent tables can be manually created with the
+.Pa create
+option of pfctl, before or after the ruleset has been loaded.
+.It Pa pf.conf
+Table definitions can be placed directly in this file, and loaded at the
+same time as other rules are loaded, atomically.
+Table definitions inside
+.Pa pf.conf
+use the
+.Pa table
+statement, and are especially useful to define non-persistent tables.
+The content of a pre-existing table defined without a list of addresses
+to initialize it is not altered when
+.Pa pf.conf
+is loaded.
+A table initialized with the empty list
+.Pa { }
+will be cleared on load.
+.El
+.Pp
+Tables may be defined with the following two attributes:
+.Bl -tag -width persist
+.It Pa persist
+The
+.Pa persist
+flag forces the kernel to keep the table even when no rules refer to it.
+If that flag is not set, the kernel will automatically remove the table
+when the last rule referring to it is flushed.
+.It Pa const
+The
+.Pa const
+flag prevents the user from altering the contents of the table once it
+has been created.
+Without that flag,
+.Xr pfctl 8
+can be used to add or remove addresses from the table at any time, even
+when running with
+.Xr securelevel 7
+= 2.
+.El
+.Pp
+For example,
+.Bd -literal
+    table <private> const {  10/8, 172.16/12, 192.168/16 }
+    table <badhosts> persist
+    block on fxp0 from { <private>, <badhosts> } to any
+.Ed
+.Pp
+creates a table called private, and then blocks all traffic coming from
+RFC 1918 style private network blocks.
+Later, addresses may be added to the rule with the following commands so that
+traffic from these hosts can be dropped:
+.Bd -literal
+    # pfctl -t badhosts -Tadd 204.92.77.111
+.Ed
+.Pp
+When no active rules which refer to the badhosts table exist (such as when the
+rules are flushed), the
+.Pa persist
+keyword ensures that the table will not be lost.
+.Pp
+In addition to being specified by IP address, hosts may also be specified
+by their hostname.
+When the resolver is called to add a hostname to a table,
+.Pa all
+resulting IPv4 and IPv6 addresses are placed into the table.
 .Sh OPTIONS
 .Xr pf 4
 may be tuned for various situations with the
@@ -1024,99 +1121,6 @@ option prevents
 .Xr pf 4
 from modifying the source port on tcp and udp packets.
 .El
-.Sh TABLES
-Tables are named structures which can hold a collection of addresses and
-networks.
-Lookups against tables in
-.Xr pf 4
-are quite fast, making a single rule with tables much more efficient, both in
-processor usage and memory consumption, than a large number of rules which
-differ only in IP address (either created explicitly or automatically by rule
-expansion).
-.Pp
-Tables can be used as the source or destination of filter rules,
-.Pa scrub
-rules
-or
-translation rules such as
-.Pa nat
-or
-.Pa rdr .
-Tables cannot be used for things like the redirect address of
-translation rules, nor can they be used in the routing options of
-filter rules.
-.Pp
-Tables can be defined with any of the following
-.Xr pfctl 8
-mechanisms:
-.Bl -tag -width "manually"
-.It Pa manually
-Persistent tables can be manually created with the
-.Pa create
-option of pfctl, before or after the ruleset has been loaded.
-.It Pa pf.conf
-Table definitions can be placed directly in this file, and loaded at the
-same time as other rules are loaded, atomically.
-Table definitions inside
-.Pa pf.conf
-use the
-.Pa table
-statement, and are especially useful to define non-persistent tables.
-The content of a pre-existing table defined without a list of addresses
-to initialize it is not altered when
-.Pa pf.conf
-is loaded.
-A table initialized with the empty list
-.Pa { }
-will be cleared on load.
-.El
-.Pp
-Tables may be defined with the following two attributes:
-.Bl -tag -width persist
-.It Pa persist
-The
-.Pa persist
-flag forces the kernel to keep the table even when no rules refer to it.
-If that flag is not set, the kernel will automatically remove the table
-when the last rule referring to it is flushed.
-.It Pa const
-The
-.Pa const
-flag prevents the user from altering the contents of the table once it
-has been created.
-Without that flag,
-.Xr pfctl 8
-can be used to add or remove addresses from the table at any time, even
-when running with
-.Xr securelevel 7
-= 2.
-.El
-.Pp
-For example,
-.Bd -literal
-    table <private> const {  10/8, 172.16/12, 192.168/16 }
-    table <badhosts> persist
-    block on fxp0 from { <private>, <badhosts> } to any
-.Ed
-.Pp
-creates a table called private, and then blocks all traffic coming from
-RFC 1918 style private network blocks.
-Later, addresses may be added to the rule with the following commands so that
-traffic from these hosts can be dropped:
-.Bd -literal
-    # pfctl -t badhosts -Tadd 204.92.77.111
-.Ed
-.Pp
-When no active rules which refer to the badhosts table exist (such as when the
-rules are flushed), the
-.Pa persist
-keyword ensures that the table will not be lost.
-.Pp
-In addition to being specified by IP address, hosts may also be specified
-by their hostname.
-When the resolver is called to add a hostname to a table,
-.Pa all
-resulting IPv4 and IPv6 addresses are placed into the table.
 .Sh STATEFUL INSPECTION
 .Xr pf 4
 is a stateful packet filter, which means it can track the state of