the recent changes to translation make the ordering of this document

slightly redundant: move the packet filtering section to the top,
and make translation a subsection;

ok henning

1 files changed, 854 insertions, 857 deletions

diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5
index 751afd3acd2..0f7365a1418 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.451 2009/09/02 14:50:01 henning Exp $
+.\"	$OpenBSD: pf.conf.5,v 1.452 2009/09/03 17:53:25 jmc Exp $
 .\"
 .\" Copyright (c) 2002, Daniel Hartmeier
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 2 2009 $
+.Dd $Mdocdate: September 3 2009 $
 .Dt PF.CONF 5
 .Os
 .Sh NAME
@@ -42,14 +42,12 @@ definitions specified in
 .Pp
 This is an overview of the sections in this manual page:
 .Bl -ohang
+.It Sy Packet Filtering
+Packet filtering, including network address translation (NAT).
 .It Sy Options
 Global options tune the behaviour of the packet filtering engine.
 .It Sy Queueing
 Queueing provides rule-based bandwidth control.
-.It Sy Translation
-Translation specifies how addresses are mapped to other addresses.
-.It Sy Packet Filtering
-Packet filtering provides rule-based blocking or passing of packets.
 .It Sy Tables
 Tables provide a method for dealing with large numbers of addresses.
 .It Sy Anchors
@@ -61,7 +59,7 @@ Including scrub, fragment handling, and blocking spoofed traffic.
 .It Sy Operating System Fingerprinting
 A method for detecting a host's operating system.
 .It Sy Examples
-Translation and filter examples.
+Some example rulesets.
 .El
 .Pp
 Comments can be put anywhere in the file using a hash mark
@@ -90,774 +88,6 @@ all_ifs = "{" $ext_if lo0 "}"
 pass out on $ext_if from any to any
 pass in  on $ext_if proto tcp from any to any port 25
 .Ed
-.Sh OPTIONS
-.Xr pf 4
-may be tuned for various situations using the
-.Ar set
-command.
-.Bl -tag -width Ds
-.It Ar set block-policy
-The
-.Ar block-policy
-option sets the default behaviour for the packet
-.Ar block
-action:
-.Pp
-.Bl -tag -width xxxxxxxx -compact
-.It Ar drop
-Packet is silently dropped.
-.It Ar return
-A TCP RST is returned for blocked TCP packets,
-an ICMP UNREACHABLE is returned for blocked UDP packets,
-and all other packets are silently dropped.
-.El
-.It Ar set debug
-Set the debug
-.Ar level
-to one of the following:
-.Pp
-.Bl -tag -width xxxxxxxx -compact
-.It Ar loud
-Generate debug messages for common conditions.
-.It Ar misc
-Generate debug messages for various errors.
-.It Ar none
-Don't generate debug messages.
-.It Ar urgent
-Generate debug messages only for serious errors.
-.El
-.It Ar set fingerprints
-Load fingerprints of known operating systems from the given filename.
-By default fingerprints of known operating systems are automatically
-loaded from
-.Xr pf.os 5 ,
-but can be overridden via this option.
-Setting this option may leave a small period of time where the fingerprints
-referenced by the currently active ruleset are inconsistent until the new
-ruleset finishes loading.
-.It Ar set hostid
-The 32-bit
-.Ar hostid
-identifies this firewall's state table entries to other firewalls
-in a
-.Xr pfsync 4
-failover cluster.
-By default the hostid is set to a pseudo-random value, however it may be
-desirable to manually configure it, for example to more easily identify the
-source of state table entries.
-The hostid may be specified in either decimal or hexadecimal.
-.It Ar set limit
-Sets hard limits on the memory pools used by the packet filter.
-See
-.Xr pool 9
-for an explanation of memory pools.
-.Pp
-For example,
-to set the maximum number of entries in the memory pool used by state table
-entries (generated by
-.Ar pass
-rules which do not specify
-.Ar no state )
-to 20000:
-.Pp
-.Dl set limit states 20000
-.Pp
-To set the maximum number of entries in the memory pool used for fragment
-reassembly to 20000:
-.Pp
-.Dl set limit frags 20000
-.Pp
-To set the maximum number of entries in the memory pool used for tracking
-source IP addresses (generated by the
-.Ar sticky-address
-and
-.Ar src.track
-options) to 2000:
-.Pp
-.Dl set limit src-nodes 2000
-.Pp
-To set limits on the memory pools used by tables:
-.Bd -literal -offset indent
-set limit tables 1000
-set limit table-entries 100000
-.Ed
-.Pp
-The first limits the number of tables that can exist to 1000.
-The second limits the overall number of addresses that can be stored
-in tables to 100000.
-.Pp
-Various limits can be combined on a single line:
-.Bd -literal -offset indent
-set limit { states 20000, frags 20000, src-nodes 2000 }
-.Ed
-.It Ar set loginterface
-Enable collection of packet and byte count statistics for the given
-interface or interface group.
-These statistics can be viewed using:
-.Pp
-.Dl # pfctl -s info
-.Pp
-In this example
-.Xr pf 4
-collects statistics on the interface named dc0:
-.Pp
-.Dl set loginterface dc0
-.Pp
-One can disable the loginterface using:
-.Pp
-.Dl set loginterface none
-.It Ar set optimization
-Optimize state timeouts for one of the following network environments:
-.Pp
-.Bl -tag -width Ds -compact
-.It Ar aggressive
-Aggressively expire connections.
-This can greatly reduce the memory usage of the firewall at the cost of
-dropping idle connections early.
-.It Ar conservative
-Extremely conservative settings.
-Avoid dropping legitimate connections at the
-expense of greater memory utilization (possibly much greater on a busy
-network) and slightly increased processor utilization.
-.It Ar high-latency
-A high-latency environment (such as a satellite connection).
-.It Ar normal
-A normal network environment.
-Suitable for almost all networks.
-.It Ar satellite
-Alias for
-.Ar high-latency .
-.El
-.It Ar set reassemble
-The
-.Ar reassemble
-option turns reassembly of fragmented packets on or off.
-If
-.Ar no-df
-is given, fragments with the
-.Ar dont-fragment
-bit set have it cleared before entering the fragment cache,
-and thus the reassembled packet doesn't have
-.Ar dont-fragment
-set either.
-Setting this option does not affect non-fragmented packets.
-Fragment reassembly is turned on by default.
-.It Ar set require-order
-If set to
-.Ar yes ,
-.Xr pfctl 8
-will enforce that statement types in the ruleset are listed in the
-following order, to match the operation of the underlying packet
-filtering engine:
-.Em options ,
-.Em queueing ,
-.Em translation ,
-.Em filtering .
-This option is disabled by default.
-.It Ar set ruleset-optimization
-.Bl -tag -width xxxxxxxx -compact
-.It Ar basic
-Enable basic ruleset optimization.
-This is the default behaviour.
-Basic ruleset optimization does four things to improve the
-performance of ruleset evaluations:
-.Pp
-.Bl -enum -compact
-.It
-remove duplicate rules
-.It
-remove rules that are a subset of another rule
-.It
-combine multiple rules into a table when advantageous
-.It
-re-order the rules to improve evaluation performance
-.El
-.It Ar none
-Disable the ruleset optimizer.
-.It Ar profile
-Uses the currently loaded ruleset as a feedback profile to tailor the
-ordering of quick rules to actual network traffic.
-.El
-.Pp
-It is important to note that the ruleset optimizer will modify the ruleset
-to improve performance.
-A side effect of the ruleset modification is that per-rule accounting
-statistics will have different meanings than before.
-If per-rule accounting is important for billing purposes or whatnot,
-either the ruleset optimizer should not be used or a label field should
-be added to all of the accounting rules to act as optimization barriers.
-.Pp
-Optimization can also be set as a command-line argument to
-.Xr pfctl 8 ,
-overriding the settings in
-.Nm .
-.It Ar set skip on Aq Ar ifspec
-List interfaces for which packets should not be filtered.
-Packets passing in or out on such interfaces are passed as if pf was
-disabled, i.e. pf does not process them in any way.
-This can be useful on loopback and other virtual interfaces, when
-packet filtering is not desired and can have unexpected effects.
-.It Ar set state-defaults
-The
-.Ar state-defaults
-option sets the state options for states created from rules
-without an explicit
-.Ar keep state .
-For example:
-.Pp
-.Dl set state-defaults pflow, no-sync
-.It Ar set state-policy
-The
-.Ar state-policy
-option sets the default behaviour for states:
-.Pp
-.Bl -tag -width if-bound -compact
-.It Ar if-bound
-States are bound to interface.
-.It Ar floating
-States can match packets on any interfaces (the default).
-.El
-.It Ar set timeout
-.Pp
-.Bl -tag -width "src.track" -compact
-.It Ar frag
-Seconds before an unassembled fragment is expired.
-.It Ar interval
-Interval between purging expired states and fragments.
-.It Ar src.track
-Length of time to retain a source tracking entry after the last state
-expires.
-.El
-.Pp
-When a packet matches a stateful connection, the seconds to live for the
-connection will be updated to that of the
-protocol and modifier
-which corresponds to the connection state.
-Each packet which matches this state will reset the TTL.
-Tuning these values may improve the performance of the
-firewall at the risk of dropping valid idle connections.
-.Pp
-.Bl -tag -width Ds -compact
-.It Ar tcp.closed
-The state after one endpoint sends an RST.
-.It Ar tcp.closing
-The state after the first FIN has been sent.
-.It Ar tcp.established
-The fully established state.
-.It Ar tcp.finwait
-The state after both FINs have been exchanged and the connection is closed.
-Some hosts (notably web servers on Solaris) send TCP packets even after closing
-the connection.
-Increasing
-.Ar tcp.finwait
-(and possibly
-.Ar tcp.closing )
-can prevent blocking of such packets.
-.It Ar tcp.first
-The state after the first packet.
-.It Ar tcp.opening
-The state before the destination host ever sends a packet.
-.El
-.Pp
-ICMP and UDP are handled in a fashion similar to TCP, but with a much more
-limited set of states:
-.Pp
-.Bl -tag -width Ds -compact
-.It Ar icmp.error
-The state after an ICMP error came back in response to an ICMP packet.
-.It Ar icmp.first
-The state after the first packet.
-.It Ar udp.first
-The state after the first packet.
-.It Ar udp.multiple
-The state if both hosts have sent packets.
-.It Ar udp.single
-The state if the source host sends more than one packet but the destination
-host has never sent one back.
-.El
-.Pp
-Other protocols are handled similarly to UDP:
-.Pp
-.Bl -tag -width xxxx -compact
-.It Ar other.first
-.It Ar other.multiple
-.It Ar other.single
-.El
-.Pp
-Timeout values can be reduced adaptively as the number of state table
-entries grows.
-.Pp
-.Bl -tag -width Ds -compact
-.It Ar adaptive.end
-When reaching this number of state entries, all timeout values become
-zero, effectively purging all state entries immediately.
-This value is used to define the scale factor; it should not actually
-be reached (set a lower state limit, see below).
-.It Ar adaptive.start
-When the number of state entries exceeds this value, adaptive scaling
-begins.
-All timeout values are scaled linearly with factor
-(adaptive.end \- number of states) / (adaptive.end \- adaptive.start).
-.El
-.Pp
-Adaptive timeouts are enabled by default, with an adaptive.start value
-equal to 60% of the state limit, and an adaptive.end value equal to
-120% of the state limit.
-They can be disabled by setting both adaptive.start and adaptive.end to 0.
-.Pp
-The adaptive timeout values can be defined both globally and for each rule.
-When used on a per-rule basis, the values relate to the number of
-states created by the rule, otherwise to the total number of
-states.
-.Pp
-For example:
-.Bd -literal -offset indent
-set timeout tcp.first 120
-set timeout tcp.established 86400
-set timeout { adaptive.start 6000, adaptive.end 12000 }
-set limit states 10000
-.Ed
-.Pp
-With 9000 state table entries, the timeout values are scaled to 50%
-(tcp.first 60, tcp.established 43200).
-.El
-.Sh QUEUEING
-Packets can be assigned to queues for the purpose of bandwidth
-control.
-At least two declarations are required to configure queues, and later
-any packet filtering rule can reference the defined queues by name.
-During the filtering component of
-.Nm ,
-the last referenced
-.Ar queue
-name is where any packets from
-.Ar pass
-rules will be queued, while for
-.Ar block
-rules it specifies where any resulting ICMP or TCP RST
-packets should be queued.
-The
-.Em scheduler
-defines the algorithm used to decide which packets get delayed, dropped, or
-sent out immediately.
-There are three schedulers currently supported:
-.Bl -tag -width xxxx
-.It Ar cbq
-Class Based Queueing.
-Queues attached to an interface build a tree,
-thus each queue can have further child queues.
-Each queue can have a
-.Ar priority
-and a
-.Ar bandwidth
-assigned.
-Priority mainly controls the time packets take to get sent out,
-while bandwidth has primarily effects on throughput.
-.Ar cbq
-achieves both partitioning and sharing of link bandwidth
-by hierarchically structured classes.
-Each class has its own queue
-and is assigned its share of bandwidth.
-A child class can borrow bandwidth from its parent class
-as long as excess bandwidth is available
-(see the option
-.Ar borrow ,
-below).
-.It Ar hfsc
-Hierarchical Fair Service Curve.
-Queues attached to an interface build a tree,
-thus each queue can have further child queues.
-Each queue can have a
-.Ar priority
-and a
-.Ar bandwidth
-assigned.
-Priority mainly controls the time packets take to get sent out,
-while bandwidth primarily affects throughput.
-.Ar hfsc
-supports both link-sharing and guaranteed real-time services.
-It employs a service curve based QoS model,
-and its unique feature is an ability to decouple
-delay and bandwidth allocation.
-.It Ar priq
-Priority Queueing.
-Queues are flat attached to the interface,
-thus queues cannot have further child queues.
-Each queue has a unique
-.Ar priority
-assigned, ranging from 0 to 15.
-Packets in the queue with the highest priority are processed first.
-.El
-.Pp
-The interfaces on which queueing should be activated are declared using
-the
-.Ar altq on
-declaration.
-.Ar altq on
-has the following keywords:
-.Bl -tag -width xxxx
-.It Aq Ar interface
-Queueing is enabled on the named interface.
-.It Aq Ar scheduler
-Specifies which queueing scheduler to use.
-.It Ar bandwidth Aq Ar bw
-The maximum bitrate for all queues on an
-interface may be specified using the
-.Ar bandwidth
-keyword.
-The value can be specified as an absolute value or as a
-percentage of the interface bandwidth.
-When using an absolute value, the suffixes
-.Ar b ,
-.Ar Kb ,
-.Ar Mb ,
-and
-.Ar Gb
-are used to represent bits, kilobits, megabits, and
-gigabits per second, respectively.
-The value must not exceed the interface bandwidth.
-If
-.Ar bandwidth
-is not specified, the interface bandwidth is used
-(but take note that some interfaces do not know their bandwidth,
-or can adapt their bandwidth rates).
-.It Ar qlimit Aq Ar limit
-The maximum number of packets held in the queue.
-The default is 50.
-.It Ar tbrsize Aq Ar size
-Adjusts the size, in bytes, of the token bucket regulator.
-If not specified, heuristics based on the
-interface bandwidth are used to determine the size.
-.It Ar queue Aq Ar list
-Defines a list of subqueues to create on an interface.
-.El
-.Pp
-In the following example, the interface dc0
-should queue up to 5Mbps in four second-level queues using
-Class Based Queueing.
-Those four queues will be shown in a later example.
-.Bd -literal -offset indent
-altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh }
-.Ed
-.Pp
-Once interfaces are activated for queueing using the
-.Ar altq
-directive, a sequence of
-.Ar queue
-directives may be defined.
-The name associated with a queue
-must match a queue defined in the altq
-directive or, except for the
-.Ar priq
-scheduler, in a parent queue declaration.
-The following keywords can be used:
-.Bl -tag -width xxxx
-.It Ar on Aq Ar interface
-Specifies the interface the queue operates on.
-If not given, it operates on all matching interfaces.
-.It Ar bandwidth Aq Ar bw
-Specifies the maximum bitrate to be processed by the queue.
-This value must not exceed the value of the parent
-.Ar queue
-and can be specified as an absolute value or a percentage of the parent
-queue's bandwidth.
-If not specified, defaults to 100% of the parent queue's bandwidth.
-The
-.Ar priq
-scheduler does not support bandwidth specification.
-.It Ar priority Aq Ar level
-Between queues a priority level can be set.
-For
-.Ar cbq
-and
-.Ar hfsc ,
-the range is 0 to 7 and for
-.Ar priq ,
-the range is 0 to 15.
-The default for all is 1.
-.Ar priq
-queues with a higher priority are always served first.
-.Ar cbq
-and
-.Ar hfsc
-queues with a higher priority are preferred in the case of overload.
-.It Ar qlimit Aq Ar limit
-The maximum number of packets held in the queue.
-The default is 50.
-.El
-.Pp
-The scheduler can specify additional parameters using the format
-.Ar scheduler Ns Pq Ar parameters .
-The parameters are:
-.Bl -tag -width Fl
-.It Ar default
-Packets not matched by another queue are assigned to this one.
-Exactly one default queue is required.
-.It Ar ecn
-Enables Explicit Congestion Notification (ECN) on this queue.
-ECN implies RED.
-.It Ar red
-Enables Random Early Detection (RED) on this queue.
-RED drops packets with a probability proportional to the average
-queue length.
-.\" .It Ar rio
-.\" Enables RIO on this queue.
-.\" RIO is RED with IN/OUT, thus running
-.\" RED two times more than RIO would achieve the same effect.
-.El
-.Pp
-The
-.Ar cbq
-scheduler supports an additional option:
-.Pp
-.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n
-.It Ar borrow
-The queue can borrow bandwidth from the parent.
-.El
-.Pp
-The
-.Ar hfsc
-scheduler supports some additional options:
-.Pp
-.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n
-.It Ar linkshare Aq Ar sc
-The bandwidth share of a backlogged queue.
-.It Ar realtime Aq Ar sc
-The minimum required bandwidth for the queue.
-.It Ar upperlimit Aq Ar sc
-The maximum allowed bandwidth for the queue.
-.El
-.Pp
-.Aq Ar sc
-is an abbreviation for
-.Ar service curve .
-.Pp
-The format for service curve specifications is
-.Ar ( m1 , d , m2 ) .
-.Ar m2
-controls the bandwidth assigned to the queue.
-.Ar m1
-and
-.Ar d
-are optional and can be used to control the initial bandwidth assignment.
-For the first
-.Ar d
-milliseconds the queue gets the bandwidth given as
-.Ar m1 ,
-afterwards the value given in
-.Ar m2 .
-.Pp
-Furthermore, with
-.Ar cbq
-and
-.Ar hfsc ,
-child queues can be specified as in an
-.Ar altq
-declaration, thus building a tree of queues using a part of
-their parent's bandwidth.
-.Pp
-Packets can be assigned to queues based on filter rules by using the
-.Ar queue
-keyword.
-Normally only one
-.Ar queue
-is specified; when a second one is specified it will instead be used for
-packets which have a TOS of
-.Ar lowdelay
-and for TCP ACKs with no data payload.
-.Pp
-To continue the previous example, the examples below would specify the
-four referenced
-queues, plus a few child queues.
-Interactive
-.Xr ssh 1
-sessions get priority over bulk transfers like
-.Xr scp 1
-and
-.Xr sftp 1 .
-The queues may then be referenced by filtering rules (see
-.Sx PACKET FILTERING
-below).
-.Bd -literal -offset 4n
-queue std bandwidth 10% cbq(default)
-queue http bandwidth 60% priority 2 cbq(borrow red) \e
-      { employees, developers }
-queue  developers bandwidth 75% cbq(borrow)
-queue  employees bandwidth 15%
-queue mail bandwidth 10% priority 0 cbq(borrow ecn)
-queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk }
-queue  ssh_interactive bandwidth 50% priority 7 cbq(borrow)
-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
-      queue developers
-pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e
-      queue employees
-pass out on dc0 inet proto tcp from any to any port 22 \e
-      queue(ssh_bulk, ssh_interactive)
-pass out on dc0 inet proto tcp from any to any port 25 \e
-      queue mail
-.Ed
-.Sh TRANSLATION
-Translation options modify either the source or destination address of the
-packets associated with a stateful connection.
-A stateful connection is automatically created to track packets matching
-such a rule as long as they are not blocked by the filtering section of
-.Nm .
-The translation engine modifies the specified address and/or port in the
-packet, recalculates IP, TCP, and UDP checksums as necessary, and passes it to
-the packet filter for evaluation.
-.Pp
-Since translation occurs before filtering,
-the filter engine will see packets as they look
-after any addresses and ports have been translated.
-Filter rules will therefore have to filter based on the translated
-address and port number.
-Packets that match a translation rule are only automatically passed if the
-.Ar pass
-modifier is given,
-otherwise they are still subject to
-.Ar block
-and
-.Ar pass
-rules.
-.Pp
-The state entry created permits
-.Xr pf 4
-to keep track of the original address for traffic associated with that state
-and correctly direct return traffic for that connection.
-.Pp
-Two types of translation are possible with pf:
-.Bl -tag -width xxxxxxxx
-.It Ar nat-to
-A
-.Ar nat-to
-option specifies that IP addresses are to be changed as the packet
-traverses the given interface.
-This technique allows one or more IP addresses
-on the translating host to support network traffic for a larger range of
-machines on an "inside" network.
-Although in theory any IP address can be used on the inside, it is strongly
-recommended that one of the address ranges defined by RFC 1918 be used.
-Those netblocks are:
-.Bd -literal -offset indent
-10.0.0.0 \(en 10.255.255.255 (all of net 10, i.e. 10/8)
-172.16.0.0 \(en 172.31.255.255 (i.e. 172.16/12)
-192.168.0.0 \(en 192.168.255.255 (i.e. 192.168/16)
-.Ed
-.It Pa rdr-to
-The packet is redirected to another destination and possibly a
-different port.
-.Ar rdr-to
-can optionally specify port ranges instead of single ports.
-For instance:
-.Bl -tag -width Ds
-.It match in ... port 2000:2999 rdr-to ... port 4000
-redirects ports 2000 to 2999 (inclusive) to port 4000.
-.Pp
-.It match in ... port 2000:2999 rdr-to ... port 4000:*
-redirects port 2000 to 4000, port 2001 to 4001, ..., port 2999 to 4999.
-.El
-.El
-.Pp
-In addition to modifying the address, some translation rules may modify
-source or destination ports for TCP or UDP connections;
-implicitly in the case of
-.Ar nat-to
-options and explicitly in the case of
-.Ar rdr-to
-ones.
-.Pp
-Translation options apply only to packets that pass through the specified
-interface, and if no interface is specified, translation is applied
-to packets on all interfaces.
-For instance, redirecting port 80 on an external interface to an internal
-web server will only work for connections originating from the outside.
-Connections to the address of the external interface from local hosts will
-not be redirected, since such packets do not actually pass through the
-external interface.
-Redirections cannot reflect packets back through the interface they arrive
-on, they can only be redirected to hosts connected to different interfaces
-or to the firewall itself.
-.Pp
-Note that redirecting external incoming connections to the loopback address
-will effectively allow an external host to connect to daemons
-bound solely to the loopback address, circumventing the traditional
-blocking of such connections on a real interface.
-For example:
-.Bd -literal -offset indent
-match in on ne3 inet proto tcp to port smtp rdr-to 127.0.0.1 \e
-      port spamd
-.Ed
-.Pp
-Unless this effect is desired, any of the local non-loopback addresses
-should be used instead as the redirection target, which allows external
-connections only to daemons bound to this address or not bound to
-any address.
-.Pp
-For
-.Ar nat-to
-and
-.Ar rdr-to
-options for which there is a single redirection address which has a
-subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP
-address), a variety of different methods for assigning this address can be
-used:
-.Bl -tag -width xxxx
-.It Ar bitmask
-The
-.Ar bitmask
-option applies the network portion of the redirection address to the address
-to be modified (source with
-.Ar nat-to ,
-destination with
-.Ar rdr-to ) .
-.It Ar random Op Ar sticky-address
-The
-.Ar random
-option selects an address at random within the defined block of addresses.
-.Pp
-.Ar sticky-address
-can be specified to ensure that multiple connections from the
-same source are mapped to the same redirection address.
-Associations are destroyed as soon as there are
-no longer states which refer to them;
-in order to make the mappings last
-beyond the lifetime of the states,
-increase the global options with
-.Ar set timeout src.track .
-.It Ar round-robin Op Ar sticky-address
-The
-.Ar round-robin
-option loops through the redirection address(es).
-.Ar sticky-address
-is as described above.
-.Pp
-When more than one redirection address is specified,
-.Ar round-robin
-is the only permitted pool type.
-.It Ar source-hash Op Ar key
-The
-.Ar source-hash
-option uses a hash of the source address to determine the redirection address,
-ensuring that the redirection address is always the same for a given source.
-An optional
-.Ar key
-can be specified after this keyword either in hex or as a string;
-by default
-.Xr pfctl 8
-randomly generates a key for source-hash every time the
-ruleset is reloaded.
-.It Ar static-port
-With
-.Ar nat
-rules, the
-.Ar static-port
-option prevents
-.Xr pf 4
-from modifying the source port on TCP and UDP packets.
-.El
 .Sh PACKET FILTERING
 .Xr pf 4
 has the ability to
@@ -1493,6 +723,165 @@ block out proto { tcp, udp } all
 pass  out proto { tcp, udp } all user { \*(Lt 1000, dhartmei }
 .Ed
 .El
+.Ss Translation
+Translation options modify either the source or destination address of the
+packets associated with a stateful connection.
+A stateful connection is automatically created to track packets matching
+such a rule as long as they are not blocked by the filtering section of
+.Nm .
+The translation engine modifies the specified address and/or port in the
+packet, recalculates IP, TCP, and UDP checksums as necessary, and passes it to
+the packet filter for evaluation.
+.Pp
+Since translation occurs before filtering,
+the filter engine will see packets as they look
+after any addresses and ports have been translated.
+Filter rules will therefore have to filter based on the translated
+address and port number.
+Packets that match a translation rule are only automatically passed if the
+.Ar pass
+modifier is given,
+otherwise they are still subject to
+.Ar block
+and
+.Ar pass
+rules.
+.Pp
+The state entry created permits
+.Xr pf 4
+to keep track of the original address for traffic associated with that state
+and correctly direct return traffic for that connection.
+.Pp
+Different types of translation are possible with pf:
+.Bl -tag -width xxxxxxxx
+.It Ar nat-to
+A
+.Ar nat-to
+option specifies that IP addresses are to be changed as the packet
+traverses the given interface.
+This technique allows one or more IP addresses
+on the translating host to support network traffic for a larger range of
+machines on an "inside" network.
+Although in theory any IP address can be used on the inside, it is strongly
+recommended that one of the address ranges defined by RFC 1918 be used.
+Those netblocks are:
+.Bd -literal -offset indent
+10.0.0.0 \(en 10.255.255.255 (all of net 10, i.e. 10/8)
+172.16.0.0 \(en 172.31.255.255 (i.e. 172.16/12)
+192.168.0.0 \(en 192.168.255.255 (i.e. 192.168/16)
+.Ed
+.It Pa rdr-to
+The packet is redirected to another destination and possibly a
+different port.
+.Ar rdr-to
+can optionally specify port ranges instead of single ports.
+For instance:
+.Bl -tag -width Ds
+.It match in ... port 2000:2999 rdr-to ... port 4000
+redirects ports 2000 to 2999 (inclusive) to port 4000.
+.Pp
+.It match in ... port 2000:2999 rdr-to ... port 4000:*
+redirects port 2000 to 4000, port 2001 to 4001, ..., port 2999 to 4999.
+.El
+.El
+.Pp
+In addition to modifying the address, some translation rules may modify
+source or destination ports for TCP or UDP connections;
+implicitly in the case of
+.Ar nat-to
+options and explicitly in the case of
+.Ar rdr-to
+ones.
+.Pp
+Translation options apply only to packets that pass through the specified
+interface, and if no interface is specified, translation is applied
+to packets on all interfaces.
+For instance, redirecting port 80 on an external interface to an internal
+web server will only work for connections originating from the outside.
+Connections to the address of the external interface from local hosts will
+not be redirected, since such packets do not actually pass through the
+external interface.
+Redirections cannot reflect packets back through the interface they arrive
+on, they can only be redirected to hosts connected to different interfaces
+or to the firewall itself.
+.Pp
+Note that redirecting external incoming connections to the loopback address
+will effectively allow an external host to connect to daemons
+bound solely to the loopback address, circumventing the traditional
+blocking of such connections on a real interface.
+For example:
+.Bd -literal -offset indent
+pass on egress proto tcp from any to any port smtp \e
+	rdr-to 127.0.0.1 port spamd
+.Ed
+.Pp
+Unless this effect is desired, any of the local non-loopback addresses
+should be used instead as the redirection target, which allows external
+connections only to daemons bound to this address or not bound to
+any address.
+.Pp
+For
+.Ar nat-to
+and
+.Ar rdr-to
+options for which there is a single redirection address which has a
+subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP
+address), a variety of different methods for assigning this address can be
+used:
+.Bl -tag -width xxxx
+.It Ar bitmask
+The
+.Ar bitmask
+option applies the network portion of the redirection address to the address
+to be modified (source with
+.Ar nat-to ,
+destination with
+.Ar rdr-to ) .
+.It Ar random Op Ar sticky-address
+The
+.Ar random
+option selects an address at random within the defined block of addresses.
+.Pp
+.Ar sticky-address
+can be specified to ensure that multiple connections from the
+same source are mapped to the same redirection address.
+Associations are destroyed as soon as there are
+no longer states which refer to them;
+in order to make the mappings last
+beyond the lifetime of the states,
+increase the global options with
+.Ar set timeout src.track .
+.It Ar round-robin Op Ar sticky-address
+The
+.Ar round-robin
+option loops through the redirection address(es).
+.Ar sticky-address
+is as described above.
+.Pp
+When more than one redirection address is specified,
+.Ar round-robin
+is the only permitted pool type.
+.It Ar source-hash Op Ar key
+The
+.Ar source-hash
+option uses a hash of the source address to determine the redirection address,
+ensuring that the redirection address is always the same for a given source.
+An optional
+.Ar key
+can be specified after this keyword either in hex or as a string;
+by default
+.Xr pfctl 8
+randomly generates a key for source-hash every time the
+ruleset is reloaded.
+.It Ar static-port
+With
+.Ar nat
+rules, the
+.Ar static-port
+option prevents
+.Xr pf 4
+from modifying the source port on TCP and UDP packets.
+.El
 .Ss Routing
 If a packet matches a rule with one of the following route options set,
 the packet filter will route the packet according to the type of route option.
@@ -1549,9 +938,617 @@ the methods
 .Ar round-robin ,
 and
 .Ar source-hash ,
-as described above in
-.Sx TRANSLATION ,
+as described above,
 can be used.
+.Sh OPTIONS
+.Xr pf 4
+may be tuned for various situations using the
+.Ar set
+command.
+.Bl -tag -width Ds
+.It Ar set block-policy
+The
+.Ar block-policy
+option sets the default behaviour for the packet
+.Ar block
+action:
+.Pp
+.Bl -tag -width xxxxxxxx -compact
+.It Ar drop
+Packet is silently dropped.
+.It Ar return
+A TCP RST is returned for blocked TCP packets,
+an ICMP UNREACHABLE is returned for blocked UDP packets,
+and all other packets are silently dropped.
+.El
+.It Ar set debug
+Set the debug
+.Ar level
+to one of the following:
+.Pp
+.Bl -tag -width xxxxxxxx -compact
+.It Ar loud
+Generate debug messages for common conditions.
+.It Ar misc
+Generate debug messages for various errors.
+.It Ar none
+Don't generate debug messages.
+.It Ar urgent
+Generate debug messages only for serious errors.
+.El
+.It Ar set fingerprints
+Load fingerprints of known operating systems from the given filename.
+By default fingerprints of known operating systems are automatically
+loaded from
+.Xr pf.os 5 ,
+but can be overridden via this option.
+Setting this option may leave a small period of time where the fingerprints
+referenced by the currently active ruleset are inconsistent until the new
+ruleset finishes loading.
+.It Ar set hostid
+The 32-bit
+.Ar hostid
+identifies this firewall's state table entries to other firewalls
+in a
+.Xr pfsync 4
+failover cluster.
+By default the hostid is set to a pseudo-random value, however it may be
+desirable to manually configure it, for example to more easily identify the
+source of state table entries.
+The hostid may be specified in either decimal or hexadecimal.
+.It Ar set limit
+Sets hard limits on the memory pools used by the packet filter.
+See
+.Xr pool 9
+for an explanation of memory pools.
+.Pp
+For example,
+to set the maximum number of entries in the memory pool used by state table
+entries (generated by
+.Ar pass
+rules which do not specify
+.Ar no state )
+to 20000:
+.Pp
+.Dl set limit states 20000
+.Pp
+To set the maximum number of entries in the memory pool used for fragment
+reassembly to 20000:
+.Pp
+.Dl set limit frags 20000
+.Pp
+To set the maximum number of entries in the memory pool used for tracking
+source IP addresses (generated by the
+.Ar sticky-address
+and
+.Ar src.track
+options) to 2000:
+.Pp
+.Dl set limit src-nodes 2000
+.Pp
+To set limits on the memory pools used by tables:
+.Bd -literal -offset indent
+set limit tables 1000
+set limit table-entries 100000
+.Ed
+.Pp
+The first limits the number of tables that can exist to 1000.
+The second limits the overall number of addresses that can be stored
+in tables to 100000.
+.Pp
+Various limits can be combined on a single line:
+.Bd -literal -offset indent
+set limit { states 20000, frags 20000, src-nodes 2000 }
+.Ed
+.It Ar set loginterface
+Enable collection of packet and byte count statistics for the given
+interface or interface group.
+These statistics can be viewed using:
+.Pp
+.Dl # pfctl -s info
+.Pp
+In this example
+.Xr pf 4
+collects statistics on the interface named dc0:
+.Pp
+.Dl set loginterface dc0
+.Pp
+One can disable the loginterface using:
+.Pp
+.Dl set loginterface none
+.It Ar set optimization
+Optimize state timeouts for one of the following network environments:
+.Pp
+.Bl -tag -width Ds -compact
+.It Ar aggressive
+Aggressively expire connections.
+This can greatly reduce the memory usage of the firewall at the cost of
+dropping idle connections early.
+.It Ar conservative
+Extremely conservative settings.
+Avoid dropping legitimate connections at the
+expense of greater memory utilization (possibly much greater on a busy
+network) and slightly increased processor utilization.
+.It Ar high-latency
+A high-latency environment (such as a satellite connection).
+.It Ar normal
+A normal network environment.
+Suitable for almost all networks.
+.It Ar satellite
+Alias for
+.Ar high-latency .
+.El
+.It Ar set reassemble
+The
+.Ar reassemble
+option turns reassembly of fragmented packets on or off.
+If
+.Ar no-df
+is given, fragments with the
+.Ar dont-fragment
+bit set have it cleared before entering the fragment cache,
+and thus the reassembled packet doesn't have
+.Ar dont-fragment
+set either.
+Setting this option does not affect non-fragmented packets.
+Fragment reassembly is turned on by default.
+.It Ar set require-order
+If set to
+.Ar yes ,
+.Xr pfctl 8
+will enforce that statement types in the ruleset are listed in the
+following order, to match the operation of the underlying packet
+filtering engine:
+.Em options ,
+.Em queueing ,
+.Em translation ,
+.Em filtering .
+This option is disabled by default.
+.It Ar set ruleset-optimization
+.Bl -tag -width xxxxxxxx -compact
+.It Ar basic
+Enable basic ruleset optimization.
+This is the default behaviour.
+Basic ruleset optimization does four things to improve the
+performance of ruleset evaluations:
+.Pp
+.Bl -enum -compact
+.It
+remove duplicate rules
+.It
+remove rules that are a subset of another rule
+.It
+combine multiple rules into a table when advantageous
+.It
+re-order the rules to improve evaluation performance
+.El
+.It Ar none
+Disable the ruleset optimizer.
+.It Ar profile
+Uses the currently loaded ruleset as a feedback profile to tailor the
+ordering of quick rules to actual network traffic.
+.El
+.Pp
+It is important to note that the ruleset optimizer will modify the ruleset
+to improve performance.
+A side effect of the ruleset modification is that per-rule accounting
+statistics will have different meanings than before.
+If per-rule accounting is important for billing purposes or whatnot,
+either the ruleset optimizer should not be used or a label field should
+be added to all of the accounting rules to act as optimization barriers.
+.Pp
+Optimization can also be set as a command-line argument to
+.Xr pfctl 8 ,
+overriding the settings in
+.Nm .
+.It Ar set skip on Aq Ar ifspec
+List interfaces for which packets should not be filtered.
+Packets passing in or out on such interfaces are passed as if pf was
+disabled, i.e. pf does not process them in any way.
+This can be useful on loopback and other virtual interfaces, when
+packet filtering is not desired and can have unexpected effects.
+.It Ar set state-defaults
+The
+.Ar state-defaults
+option sets the state options for states created from rules
+without an explicit
+.Ar keep state .
+For example:
+.Pp
+.Dl set state-defaults pflow, no-sync
+.It Ar set state-policy
+The
+.Ar state-policy
+option sets the default behaviour for states:
+.Pp
+.Bl -tag -width if-bound -compact
+.It Ar if-bound
+States are bound to interface.
+.It Ar floating
+States can match packets on any interfaces (the default).
+.El
+.It Ar set timeout
+.Pp
+.Bl -tag -width "src.track" -compact
+.It Ar frag
+Seconds before an unassembled fragment is expired.
+.It Ar interval
+Interval between purging expired states and fragments.
+.It Ar src.track
+Length of time to retain a source tracking entry after the last state
+expires.
+.El
+.Pp
+When a packet matches a stateful connection, the seconds to live for the
+connection will be updated to that of the
+protocol and modifier
+which corresponds to the connection state.
+Each packet which matches this state will reset the TTL.
+Tuning these values may improve the performance of the
+firewall at the risk of dropping valid idle connections.
+.Pp
+.Bl -tag -width Ds -compact
+.It Ar tcp.closed
+The state after one endpoint sends an RST.
+.It Ar tcp.closing
+The state after the first FIN has been sent.
+.It Ar tcp.established
+The fully established state.
+.It Ar tcp.finwait
+The state after both FINs have been exchanged and the connection is closed.
+Some hosts (notably web servers on Solaris) send TCP packets even after closing
+the connection.
+Increasing
+.Ar tcp.finwait
+(and possibly
+.Ar tcp.closing )
+can prevent blocking of such packets.
+.It Ar tcp.first
+The state after the first packet.
+.It Ar tcp.opening
+The state before the destination host ever sends a packet.
+.El
+.Pp
+ICMP and UDP are handled in a fashion similar to TCP, but with a much more
+limited set of states:
+.Pp
+.Bl -tag -width Ds -compact
+.It Ar icmp.error
+The state after an ICMP error came back in response to an ICMP packet.
+.It Ar icmp.first
+The state after the first packet.
+.It Ar udp.first
+The state after the first packet.
+.It Ar udp.multiple
+The state if both hosts have sent packets.
+.It Ar udp.single
+The state if the source host sends more than one packet but the destination
+host has never sent one back.
+.El
+.Pp
+Other protocols are handled similarly to UDP:
+.Pp
+.Bl -tag -width xxxx -compact
+.It Ar other.first
+.It Ar other.multiple
+.It Ar other.single
+.El
+.Pp
+Timeout values can be reduced adaptively as the number of state table
+entries grows.
+.Pp
+.Bl -tag -width Ds -compact
+.It Ar adaptive.end
+When reaching this number of state entries, all timeout values become
+zero, effectively purging all state entries immediately.
+This value is used to define the scale factor; it should not actually
+be reached (set a lower state limit, see below).
+.It Ar adaptive.start
+When the number of state entries exceeds this value, adaptive scaling
+begins.
+All timeout values are scaled linearly with factor
+(adaptive.end \- number of states) / (adaptive.end \- adaptive.start).
+.El
+.Pp
+Adaptive timeouts are enabled by default, with an adaptive.start value
+equal to 60% of the state limit, and an adaptive.end value equal to
+120% of the state limit.
+They can be disabled by setting both adaptive.start and adaptive.end to 0.
+.Pp
+The adaptive timeout values can be defined both globally and for each rule.
+When used on a per-rule basis, the values relate to the number of
+states created by the rule, otherwise to the total number of
+states.
+.Pp
+For example:
+.Bd -literal -offset indent
+set timeout tcp.first 120
+set timeout tcp.established 86400
+set timeout { adaptive.start 6000, adaptive.end 12000 }
+set limit states 10000
+.Ed
+.Pp
+With 9000 state table entries, the timeout values are scaled to 50%
+(tcp.first 60, tcp.established 43200).
+.El
+.Sh QUEUEING
+Packets can be assigned to queues for the purpose of bandwidth
+control.
+At least two declarations are required to configure queues, and later
+any packet filtering rule can reference the defined queues by name.
+During the filtering component of
+.Nm ,
+the last referenced
+.Ar queue
+name is where any packets from
+.Ar pass
+rules will be queued, while for
+.Ar block
+rules it specifies where any resulting ICMP or TCP RST
+packets should be queued.
+The
+.Em scheduler
+defines the algorithm used to decide which packets get delayed, dropped, or
+sent out immediately.
+There are three schedulers currently supported:
+.Bl -tag -width xxxx
+.It Ar cbq
+Class Based Queueing.
+Queues attached to an interface build a tree,
+thus each queue can have further child queues.
+Each queue can have a
+.Ar priority
+and a
+.Ar bandwidth
+assigned.
+Priority mainly controls the time packets take to get sent out,
+while bandwidth has primarily effects on throughput.
+.Ar cbq
+achieves both partitioning and sharing of link bandwidth
+by hierarchically structured classes.
+Each class has its own queue
+and is assigned its share of bandwidth.
+A child class can borrow bandwidth from its parent class
+as long as excess bandwidth is available
+(see the option
+.Ar borrow ,
+below).
+.It Ar hfsc
+Hierarchical Fair Service Curve.
+Queues attached to an interface build a tree,
+thus each queue can have further child queues.
+Each queue can have a
+.Ar priority
+and a
+.Ar bandwidth
+assigned.
+Priority mainly controls the time packets take to get sent out,
+while bandwidth primarily affects throughput.
+.Ar hfsc
+supports both link-sharing and guaranteed real-time services.
+It employs a service curve based QoS model,
+and its unique feature is an ability to decouple
+delay and bandwidth allocation.
+.It Ar priq
+Priority Queueing.
+Queues are flat attached to the interface,
+thus queues cannot have further child queues.
+Each queue has a unique
+.Ar priority
+assigned, ranging from 0 to 15.
+Packets in the queue with the highest priority are processed first.
+.El
+.Pp
+The interfaces on which queueing should be activated are declared using
+the
+.Ar altq on
+declaration.
+.Ar altq on
+has the following keywords:
+.Bl -tag -width xxxx
+.It Aq Ar interface
+Queueing is enabled on the named interface.
+.It Aq Ar scheduler
+Specifies which queueing scheduler to use.
+.It Ar bandwidth Aq Ar bw
+The maximum bitrate for all queues on an
+interface may be specified using the
+.Ar bandwidth
+keyword.
+The value can be specified as an absolute value or as a
+percentage of the interface bandwidth.
+When using an absolute value, the suffixes
+.Ar b ,
+.Ar Kb ,
+.Ar Mb ,
+and
+.Ar Gb
+are used to represent bits, kilobits, megabits, and
+gigabits per second, respectively.
+The value must not exceed the interface bandwidth.
+If
+.Ar bandwidth
+is not specified, the interface bandwidth is used
+(but take note that some interfaces do not know their bandwidth,
+or can adapt their bandwidth rates).
+.It Ar qlimit Aq Ar limit
+The maximum number of packets held in the queue.
+The default is 50.
+.It Ar tbrsize Aq Ar size
+Adjusts the size, in bytes, of the token bucket regulator.
+If not specified, heuristics based on the
+interface bandwidth are used to determine the size.
+.It Ar queue Aq Ar list
+Defines a list of subqueues to create on an interface.
+.El
+.Pp
+In the following example, the interface dc0
+should queue up to 5Mbps in four second-level queues using
+Class Based Queueing.
+Those four queues will be shown in a later example.
+.Bd -literal -offset indent
+altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh }
+.Ed
+.Pp
+Once interfaces are activated for queueing using the
+.Ar altq
+directive, a sequence of
+.Ar queue
+directives may be defined.
+The name associated with a queue
+must match a queue defined in the altq
+directive or, except for the
+.Ar priq
+scheduler, in a parent queue declaration.
+The following keywords can be used:
+.Bl -tag -width xxxx
+.It Ar on Aq Ar interface
+Specifies the interface the queue operates on.
+If not given, it operates on all matching interfaces.
+.It Ar bandwidth Aq Ar bw
+Specifies the maximum bitrate to be processed by the queue.
+This value must not exceed the value of the parent
+.Ar queue
+and can be specified as an absolute value or a percentage of the parent
+queue's bandwidth.
+If not specified, defaults to 100% of the parent queue's bandwidth.
+The
+.Ar priq
+scheduler does not support bandwidth specification.
+.It Ar priority Aq Ar level
+Between queues a priority level can be set.
+For
+.Ar cbq
+and
+.Ar hfsc ,
+the range is 0 to 7 and for
+.Ar priq ,
+the range is 0 to 15.
+The default for all is 1.
+.Ar priq
+queues with a higher priority are always served first.
+.Ar cbq
+and
+.Ar hfsc
+queues with a higher priority are preferred in the case of overload.
+.It Ar qlimit Aq Ar limit
+The maximum number of packets held in the queue.
+The default is 50.
+.El
+.Pp
+The scheduler can specify additional parameters using the format
+.Ar scheduler Ns Pq Ar parameters .
+The parameters are:
+.Bl -tag -width Fl
+.It Ar default
+Packets not matched by another queue are assigned to this one.
+Exactly one default queue is required.
+.It Ar ecn
+Enables Explicit Congestion Notification (ECN) on this queue.
+ECN implies RED.
+.It Ar red
+Enables Random Early Detection (RED) on this queue.
+RED drops packets with a probability proportional to the average
+queue length.
+.\" .It Ar rio
+.\" Enables RIO on this queue.
+.\" RIO is RED with IN/OUT, thus running
+.\" RED two times more than RIO would achieve the same effect.
+.El
+.Pp
+The
+.Ar cbq
+scheduler supports an additional option:
+.Pp
+.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n
+.It Ar borrow
+The queue can borrow bandwidth from the parent.
+.El
+.Pp
+The
+.Ar hfsc
+scheduler supports some additional options:
+.Pp
+.Bl -tag -width "upperlimit XXXXXXX" -compact -offset 3n
+.It Ar linkshare Aq Ar sc
+The bandwidth share of a backlogged queue.
+.It Ar realtime Aq Ar sc
+The minimum required bandwidth for the queue.
+.It Ar upperlimit Aq Ar sc
+The maximum allowed bandwidth for the queue.
+.El
+.Pp
+.Aq Ar sc
+is an abbreviation for
+.Ar service curve .
+.Pp
+The format for service curve specifications is
+.Ar ( m1 , d , m2 ) .
+.Ar m2
+controls the bandwidth assigned to the queue.
+.Ar m1
+and
+.Ar d
+are optional and can be used to control the initial bandwidth assignment.
+For the first
+.Ar d
+milliseconds the queue gets the bandwidth given as
+.Ar m1 ,
+afterwards the value given in
+.Ar m2 .
+.Pp
+Furthermore, with
+.Ar cbq
+and
+.Ar hfsc ,
+child queues can be specified as in an
+.Ar altq
+declaration, thus building a tree of queues using a part of
+their parent's bandwidth.
+.Pp
+Packets can be assigned to queues based on filter rules by using the
+.Ar queue
+keyword.
+Normally only one
+.Ar queue
+is specified; when a second one is specified it will instead be used for
+packets which have a TOS of
+.Ar lowdelay
+and for TCP ACKs with no data payload.
+.Pp
+To continue the previous example, the examples below would specify the
+four referenced
+queues, plus a few child queues.
+Interactive
+.Xr ssh 1
+sessions get priority over bulk transfers like
+.Xr scp 1
+and
+.Xr sftp 1 .
+The queues may then be referenced by filtering rules (see
+.Sx PACKET FILTERING ,
+above).
+.Bd -literal -offset 4n
+queue std bandwidth 10% cbq(default)
+queue http bandwidth 60% priority 2 cbq(borrow red) \e
+      { employees, developers }
+queue  developers bandwidth 75% cbq(borrow)
+queue  employees bandwidth 15%
+queue mail bandwidth 10% priority 0 cbq(borrow ecn)
+queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk }
+queue  ssh_interactive bandwidth 50% priority 7 cbq(borrow)
+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
+      queue developers
+pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e
+      queue employees
+pass out on dc0 inet proto tcp from any to any port 22 \e
+      queue(ssh_bulk, ssh_interactive)
+pass out on dc0 inet proto tcp from any to any port 25 \e
+      queue mail
+.Ed
 .Sh TABLES
 Tables are named structures which can hold a collection of addresses and
 networks.
@@ -2386,84 +2383,7 @@ appear as any operating system he chooses;
 an operating system patch could change the stack behavior and no fingerprints
 will match it until the database is updated;
 and multiple operating systems may have the same fingerprint.
-.Sh TRANSLATION EXAMPLES
-This example maps incoming requests on port 80 to port 8080, on
-which a daemon is running (because, for example, it is not run as root,
-and therefore lacks permission to bind to port 80).
-.Bd -literal -offset 4n
-match in on $ext_if proto tcp from any to any port 80 \e
-      rdr-to 127.0.0.1 port 8080
-.Ed
-.Pp
-If the
-.Ar pass
-modifier is given, packets matching the translation rule are passed without
-inspecting the filter rules.
-.Bd -literal -offset 4n
-match in on $ext_if proto tcp from any to any port 80 \e
-      rdr-to 127.0.0.1 port 8080
-.Ed
-.Pp
-In the example below, vlan12 is configured as 192.168.168.1;
-the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111
-when they are going out any interface except vlan12.
-This has the net effect of making traffic from the 192.168.168.0/24
-network appear as though it is the Internet routable address
-204.92.77.111 to nodes behind any interface on the router except
-for the nodes on vlan12.
-Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.
-.Bd -literal -offset 4n
-match out on ! vlan12 from 192.168.168.0/24 to any nat-to 204.92.77.111
-.Ed
-.Pp
-In the example below, the machine sits between a fake internal
-144.19.74.* network, and a routable external IP of 204.92.77.100.
-The last rule excludes protocol AH from being translated.
-.Bd -literal -offset 4n
-pass out on $ext_if from 144.19.74.0/24 nat-to 204.92.77.100
-pass out on $ext_if proto ah from 144.19.74.0/24
-.Ed
-.Pp
-In the example below, packets bound for one specific server, as well as those
-generated by the sysadmins are not proxied; all other connections are.
-.Bd -literal -offset 4n
-match in on $int_if proto { tcp, udp } from any to any port 80 \e
-      rdr-to 127.0.0.1 port 80
-pass in on $int_if proto { tcp, udp } from any to $server port 80
-pass in on $int_if proto { tcp, udp } from $sysadmins to any port 80
-.Ed
-.Pp
-This example maps outgoing packets' source port
-to an assigned proxy port instead of an arbitrary port.
-In this case, proxy outgoing isakmp with port 500 on the gateway.
-.Bd -literal -offset 4n
-match out on $ext_if inet proto udp from any port isakmp to any \e
-    nat-to ($ext_if) port 500
-.Ed
-.Pp
-One more example uses
-.Ar rdr-to
-to redirect a TCP and UDP port to an internal machine.
-.Bd -literal -offset 4n
-match in on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e
-      rdr-to 10.1.2.151 port 22
-match in on $ext_if inet proto udp from any to ($ext_if) port 8080 \e
-      rdr-to 10.1.2.151 port 53
-.Ed
-.Pp
-In this example, a NAT gateway is set up to translate internal addresses
-using a pool of public addresses (192.0.2.16/28).
-A given source address is always translated to the same pool address by
-using the source-hash keyword.
-The gateway also translates incoming web server connections
-to a group of web servers on the internal network.
-.Bd -literal -offset 4n
-match out on $ext_if inet from any to any nat-to 192.0.2.16/28 \e
-    source-hash
-match in  on $ext_if proto tcp from any to any port 80 \e
-    rdr-to { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin
-.Ed
-.Sh FILTER EXAMPLES
+.Sh EXAMPLES
 In this example,
 the external interface is kue0.
 We use a macro for the interface name, so it can be changed easily.
@@ -2556,6 +2476,83 @@ match in on $ext_if inet proto tcp from \*(Ltspammers\*(Gt to port smtp \e
 block in on $ext_if
 pass in on $ext_if inet proto tcp tagged SPAMD
 .Ed
+.Pp
+This example maps incoming requests on port 80 to port 8080, on
+which a daemon is running (because, for example, it is not run as root,
+and therefore lacks permission to bind to port 80).
+.Bd -literal -offset 4n
+match in on $ext_if proto tcp from any to any port 80 \e
+      rdr-to 127.0.0.1 port 8080
+.Ed
+.Pp
+If the
+.Ar pass
+modifier is given, packets matching the translation rule are passed without
+inspecting the filter rules.
+.Bd -literal -offset 4n
+match in on $ext_if proto tcp from any to any port 80 \e
+      rdr-to 127.0.0.1 port 8080
+.Ed
+.Pp
+In the example below, vlan12 is configured as 192.168.168.1;
+the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111
+when they are going out any interface except vlan12.
+This has the net effect of making traffic from the 192.168.168.0/24
+network appear as though it is the Internet routable address
+204.92.77.111 to nodes behind any interface on the router except
+for the nodes on vlan12.
+Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.
+.Bd -literal -offset 4n
+match out on ! vlan12 from 192.168.168.0/24 to any nat-to 204.92.77.111
+.Ed
+.Pp
+In the example below, the machine sits between a fake internal
+144.19.74.* network, and a routable external IP of 204.92.77.100.
+The last rule excludes protocol AH from being translated.
+.Bd -literal -offset 4n
+pass out on $ext_if from 144.19.74.0/24 nat-to 204.92.77.100
+pass out on $ext_if proto ah from 144.19.74.0/24
+.Ed
+.Pp
+In the example below, packets bound for one specific server, as well as those
+generated by the sysadmins are not proxied; all other connections are.
+.Bd -literal -offset 4n
+match in on $int_if proto { tcp, udp } from any to any port 80 \e
+      rdr-to 127.0.0.1 port 80
+pass in on $int_if proto { tcp, udp } from any to $server port 80
+pass in on $int_if proto { tcp, udp } from $sysadmins to any port 80
+.Ed
+.Pp
+This example maps outgoing packets' source port
+to an assigned proxy port instead of an arbitrary port.
+In this case, proxy outgoing isakmp with port 500 on the gateway.
+.Bd -literal -offset 4n
+match out on $ext_if inet proto udp from any port isakmp to any \e
+    nat-to ($ext_if) port 500
+.Ed
+.Pp
+One more example uses
+.Ar rdr-to
+to redirect a TCP and UDP port to an internal machine.
+.Bd -literal -offset 4n
+match in on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e
+      rdr-to 10.1.2.151 port 22
+match in on $ext_if inet proto udp from any to ($ext_if) port 8080 \e
+      rdr-to 10.1.2.151 port 53
+.Ed
+.Pp
+In this example, a NAT gateway is set up to translate internal addresses
+using a pool of public addresses (192.0.2.16/28).
+A given source address is always translated to the same pool address by
+using the source-hash keyword.
+The gateway also translates incoming web server connections
+to a group of web servers on the internal network.
+.Bd -literal -offset 4n
+match out on $ext_if inet from any to any nat-to 192.0.2.16/28 \e
+    source-hash
+match in  on $ext_if proto tcp from any to any port 80 \e
+    rdr-to { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin
+.Ed
 .Sh GRAMMAR
 Syntax for
 .Nm
@@ -2601,8 +2598,8 @@ filteropt      = user | group | flags | icmp-type | icmp6-type |
 		 "rdr-to" ( redirhost | "{" redirhost-list "}" )
 		 [ portspec ] [ pooltype ] |
 		 "nat-to" ( redirhost | "{" redirhost-list "}" )
-		 [ portspec ] [ pooltype ] [ "static-port" ] 
-		 [ "fastroute" | route ] 
+		 [ portspec ] [ pooltype ] [ "static-port" ]
+		 [ "fastroute" | route ]
 
 scrubopts      = scrubopt [ [ "," ] scrubopts ]
 scrubopt       = "no-df" | "min-ttl" number | "max-mss" number |