-.\" $OpenBSD: pf.conf.5,v 1.548 2015/10/22 11:02:48 sobrado Exp $
+.\" $OpenBSD: pf.conf.5,v 1.549 2015/10/26 00:49:34 schwarze Exp $
.\"
.\" Copyright (c) 2002, Daniel Hartmeier
.\" Copyright (c) 2003 - 2013 Henning Brauer <henning@openbsd.org>
.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd $Mdocdate: October 22 2015 $
+.Dd $Mdocdate: October 26 2015 $
.Dt PF.CONF 5
.Os
.Sh NAME
.Nm .
.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 Tables
-Tables provide a method for dealing with large numbers of addresses.
-.It Sy Anchors
-Anchors are containers for rules and tables.
-.It Sy Stateful Filtering
-Stateful filtering tracks packets by state.
-.It Sy Traffic Normalisation
-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
-Some example rulesets.
-.It Sy Grammar
-Complete BNF grammar reference.
+.Bl -inset
+.It Sx PACKET FILTERING
+including network address translation (NAT).
+.It Sx OPTIONS
+globally tune the behaviour of the packet filtering engine.
+.It Sx QUEUEING
+provides rule-based bandwidth control.
+.It Sx TABLES
+provide a method for dealing with large numbers of addresses.
+.It Sx ANCHORS
+are containers for rules and tables.
+.It Sx STATEFUL FILTERING
+tracks packets by state.
+.It Sx TRAFFIC NORMALISATION
+includes scrub, fragment handling, and blocking spoofed traffic.
+.It Sx OPERATING SYSTEM FINGERPRINTING
+is a method for detecting a host's operating system.
+.It Sx EXAMPLES
+provides some example rulesets.
+.It Sx GRAMMAR
+provides a complete BNF grammar reference.
.El
.Pp
The current line can be extended over multiple lines using a backslash
Macro names must start with a letter, digit, or underscore,
and may contain any of those characters.
Macro names may not be reserved words (for example
-.Ar pass ,
-.Ar in ,
-.Ar out ) .
+.Ic pass ,
+.Cm in ,
+.Cm out ) .
Macros are not expanded inside quotes.
.Pp
For example:
.Sh PACKET FILTERING
.Xr pf 4
has the ability to
-.Ar block ,
-.Ar pass ,
+.Ic block ,
+.Ic pass ,
and
-.Ar match
+.Ic match
packets based on attributes of their layer 3
and layer 4 headers.
Filter rules determine which of these actions are taken;
For each packet processed by the packet filter, the filter rules are
evaluated in sequential order, from first to last.
For
-.Ar block
+.Ic block
and
-.Ar pass ,
+.Ic pass ,
the last matching rule decides what action is taken;
if no rule matches the packet, the default action is to pass
the packet without creating a state.
For
-.Ar match ,
+.Ic match ,
rules are evaluated every time they match;
the pass/block state of a packet remains unchanged.
.Pp
.Xr pf 4
filters packets statefully:
the first time a packet matches a
-.Ar pass
+.Ic pass
rule, a state entry is created.
The packet filter examines each packet to see if it matches an existing state.
If it does, the packet is passed without evaluation of any rules.
removed.
.Pp
The following actions can be used in the filter:
-.Bl -tag -width xxxx
-.It Ar block
+.Bl -tag -width Ds
+.It Ic block
The packet is blocked.
There are a number of ways in which a
-.Ar block
+.Ic block
rule can behave when blocking a packet.
The default behaviour is to
-.Ar drop
+.Cm drop
packets silently, however this can be overridden or made
explicit either globally, by setting the
-.Ar block-policy
+.Cm block-policy
option, or on a per-rule basis with one of the following options:
.Pp
-.Bl -tag -width "return-icmp6XXX" -compact
-.It Ar drop
+.Bl -tag -width return-icmp6 -compact
+.It Cm drop
The packet is silently dropped.
-.It Ar return
+.It Cm return
This causes a TCP RST to be returned for TCP packets
and an ICMP UNREACHABLE for other types of packets.
-.It Ar return-icmp
-.It Ar return-icmp6
+.It Cm return-icmp
+.It Cm return-icmp6
This causes ICMP messages to be returned for packets which match the rule.
By default this is an ICMP UNREACHABLE message, however this
can be overridden by specifying a message as a code or number.
-.It Ar return-rst
+.It Cm return-rst
This applies only to TCP packets,
and issues a TCP RST which closes the connection.
An optional parameter,
-.Ar ttl ,
+.Cm ttl ,
may be given with a TTL value.
.El
.Pp
packets that match explicit rules is specify a first filter rule of:
.Pp
.Dl block all
-.It Ar match
+.It Ic match
The packet is matched.
This mechanism is used to provide fine grained filtering
without altering the block/pass state of a packet.
-.Ar match
-rules differ from block and pass rules in that
-parameters are set every time a packet matches the rule,
-not only on the last matching rule.
+.Ic match
+rules differ from
+.Ic block
+and
+.Ic pass
+rules in that parameters are set every time a packet matches the
+rule, not only on the last matching rule.
For the following parameters,
this means that the parameter effectively becomes
.Dq sticky
until explicitly overridden:
-.Ar nat-to ,
-.Ar binat-to ,
-.Ar rdr-to ,
-.Ar queue ,
-.Ar rtable ,
+.Cm nat-to ,
+.Cm binat-to ,
+.Cm rdr-to ,
+.Cm queue ,
+.Cm rtable ,
and
-.Ar scrub .
+.Cm scrub .
.Pp
-.Ar log
+.Cm log
is different still,
in that the action happens every time a rule matches
i.e. a single packet can get logged more than once.
-.It Ar pass
+.It Ic pass
The packet is passed;
state is created unless the
-.Ar no state
+.Cm no state
option is specified.
.El
.Pp
The following parameters can be used in the filter:
.Bl -tag -width Ds
-.It Ar in No or Ar out
+.It Cm in No or Cm out
A packet always comes in on, or goes out through, one interface.
-.Ar in
+.Cm in
and
-.Ar out
+.Cm out
apply to incoming and outgoing packets;
if neither are specified,
the rule will match packets in both directions.
-.It Ar log Pq Cm all | matches | to Ao Ar interface Ac | Cm user
+.It Cm log Op Cm all | matches | to Ar interface | Cm user
In addition to any action specified,
log the packet.
Only the packet that establishes the state is logged,
unless the
-.Ar no state
+.Cm no state
option is specified.
The logged packets are sent to a
.Xr pflog 4
-interface, by default pflog0;
+interface, by default
+.Pa pflog0 ;
pflog0 is monitored by the
.Xr pflogd 8
logging daemon which logs to the file
.Cm all
to force logging of all packets for a connection.
This is not necessary when
-.Ar no state
+.Cm no state
is explicitly specified.
.Pp
If
is specified,
it logs the packet on all subsequent matching rules.
It is often combined with
-.Cm to Aq Ar interface
+.Cm to Ar interface
to avoid adding noise to the default log file.
.Pp
The keyword
socket on the local host used to send or receive a packet,
in addition to the normal information.
.Pp
-To specify a logging interface other than pflog0,
+To specify a logging interface other than
+.Pa pflog0 ,
use the syntax
-.Cm to Aq Ar interface .
-.It Ar quick
+.Cm to Ar interface .
+.It Cm quick
If a packet matches a rule which has the
-.Ar quick
+.Cm quick
option set, this rule
is considered the last matching rule, and evaluation of subsequent rules
is skipped.
-.It Ar on Aq Ar interface
+.It Cm on Ar interface | Cm any
This rule applies only to packets coming in on, or going out through, this
particular interface or interface group.
For more information on interface groups,
.Ic group
keyword in
.Xr ifconfig 8 .
-.Ar any
+.Cm any
will match any existing interface except loopback ones.
-.It Ar on Ar rdomain Aq Ar number
+.It Cm on rdomain Ar number
This rule applies only to packets coming in on, or going out through, this
particular routing domain.
-.It Aq Ar af
+.It Cm inet | inet6
This rule applies only to packets of this address family.
-Supported values are
-.Ar inet
-and
-.Ar inet6 .
-.It Ar proto Aq Ar protocol
+.It Cm proto Ar protocol
This rule applies only to packets of this protocol.
Common protocols are ICMP, ICMP6, TCP, and UDP.
For a list of all the protocol name to number mappings used by
.Xr pfctl 8 ,
see the file
-.Em /etc/protocols .
+.Pa /etc/protocols .
.It Xo
-.Ar from Aq Ar source
-.Ar port Aq Ar source
-.Ar os Aq Ar source
-.Ar to Aq Ar dest
-.Ar port Aq Ar dest
+.Cm from Ar source
+.Cm port Ar source
+.Cm os Ar source
+.Cm to Ar dest
+.Cm port Ar dest
.Xc
This rule applies only to packets with the specified source and destination
addresses and ports.
symbolic host names, interface names or interface group names, or as any
of the following keywords:
.Pp
-.Bl -tag -width xxxxxxxxxxxxxx -compact
-.It Ar any
+.Bl -tag -width urpf-failed -compact
+.It Cm any
Any address.
-.It Ar no-route
+.It Cm no-route
Any address which is not currently routable.
-.It Ar route Aq Ar label
+.It Cm route Ar label
Any address matching the given
.Xr route 8
-label.
-.It Ar self
+.Ar label .
+.It Cm self
Expands to all addresses assigned to all interfaces.
-.It Aq Ar table
-Any address matching the given table.
-.It Ar urpf-failed
+.It Pf < Ar table Ns >
+Any address matching the given
+.Ar table .
+.It Cm urpf-failed
Any source address that fails a unicast reverse path forwarding (URPF)
check, i.e. packets coming in on an interface other than that which holds
the route back to the packet's source address.
hence addresses 10.1.1.10, 10.1.1.11, and 10.1.1.12.
.Pp
Interface names, interface group names, and
-.Ar self
+.Cm self
can have modifiers appended:
.Pp
-.Bl -tag -width xxxxxxxxxxxx -compact
-.It Ar :0
+.Bl -tag -width :broadcast -compact
+.It Cm :0
Do not include interface aliases.
-.It Ar :broadcast
+.It Cm :broadcast
Translates to the interface's broadcast address(es).
-.It Ar :network
+.It Cm :network
Translates to the network(s) attached to the interface.
-.It Ar :peer
+.It Cm :peer
Translates to the point-to-point interface's peer address(es).
.El
.Pp
Host names may also have the
-.Ar :0
-option appended to restrict the name resolution to the first of each
+.Cm :0
+modfier appended to restrict the name resolution to the first of each
v4 and v6 address found.
.Pp
Host name resolution and interface to address translation are done at
When the interface name is surrounded by parentheses, the rule is
automatically updated whenever the interface changes its address.
The ruleset does not need to be reloaded.
-This is especially useful with
-.Ar nat .
+This is especially useful with NAT.
.Pp
Ports can be specified either by number or by name.
For example, port 80 can be specified as
-.Em www .
+.Cm www .
For a list of all port name to number mappings used by
.Xr pfctl 8 ,
see the file
are binary operators (they take two arguments).
For instance:
.Bl -tag -width Ds
-.It port 2000:2004
+.It Li port 2000:2004
means
.Sq all ports \(>= 2000 and \(<= 2004 ,
hence ports 2000, 2001, 2002, 2003, and 2004.
-.It port 2000 >< 2004
+.It Li port 2000 >< 2004
means
.Sq all ports > 2000 and < 2004 ,
hence ports 2001, 2002, and 2003.
-.It port 2000 <> 2004
+.It Li port 2000 <> 2004
means
.Sq all ports < 2000 or > 2004 ,
hence ports 1\(en1999 and 2005\(en65535.
.Pp
The operating system of the source host can be specified in the case of TCP
rules with the
-.Ar os
+.Cm os
modifier.
See the
.Sx OPERATING SYSTEM FINGERPRINTING
section for more information.
.Pp
-The host, port, and OS specifications are optional,
-as in the following examples:
+The
+.Cm host ,
+.Cm port ,
+and
+.Cm os
+specifications are optional, as in the following examples:
.Bd -literal -offset indent
pass in all
pass in from any to any
The following additional parameters can be used in the filter:
.Pp
.Bl -tag -width Ds -compact
-.It Ar all
-This is equivalent to "from any to any".
+.It Cm all
+This is equivalent to
+.Ql from any to any .
.Pp
-.It Ar allow-opts
+.It Cm allow-opts
By default, IPv4 packets with IP options or IPv6 packets with routing
extension headers are blocked.
When
-.Ar allow-opts
+.Cm allow-opts
is specified for a
-.Ar pass
+.Ic pass
rule, packets that pass the filter based on that rule (last matching)
do so even if they contain IP options or routing extension headers.
For packets that match state, the rule that initially created the
state is used.
-The implicit
-.Ar pass
-rule that is used when a packet does not match any rules does not
-allow IP options.
+The implicit pass rule that is used when a packet does not match
+any rules does not allow IP options.
.Pp
-.It Ar divert-packet Ar port Aq Ar port
+.It Cm divert-packet port Ar port
Used to send matching packets to
.Xr divert 4
sockets bound to port
.Ar port .
If the default option of fragment reassembly is enabled, scrubbing with
-.Ar reassemble tcp
+.Cm reassemble tcp
is also enabled for
-.Ar divert-packet
+.Cm divert-packet
rules.
.Pp
-.It Ar divert-reply
+.It Cm divert-reply
Used to receive replies for sockets that are bound to addresses
which are not local to the machine.
See
.Xr setsockopt 2
for information on how to bind these sockets.
.Pp
-.It Xo Ar divert-to Aq Ar host
-.Ar port Aq Ar port
-.Xc
+.It Cm divert-to Ar host Cm port Ar port
Used to redirect packets to a local socket bound to
.Ar host
and
.Xr getsockname 2
on the socket will return the original destination address of the packet.
.Pp
-.It Ar flags Ao Ar a Ac Ns / Ns Ao Ar b Ac | Ar any
+.It Cm flags Ar a Ns / Ns Ar b | Cm any
This rule only applies to TCP packets that have the flags
-.Aq Ar a
+.Ar a
set out of set
-.Aq Ar b .
+.Ar b .
Flags not specified in
-.Aq Ar b
+.Ar b
are ignored.
For stateful connections, the default is
-.Ar flags S/SA .
+.Cm flags S/SA .
To indicate that flags should not be checked at all, specify
-.Ar flags any .
+.Cm 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
+.Bl -tag -width "flags /SFRA"
+.It Cm flags S/S
Flag SYN is set.
The other flags are ignored.
-.It Ar flags S/SA
+.It Cm 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.
-.It Ar flags /SFRA
+.It Cm flags /SFRA
If the first set is not specified, it defaults to none.
All of SYN, FIN, RST, and ACK must be unset.
.El
.Pp
Because
-.Ar flags S/SA
+.Cm flags S/SA
is applied by default (unless
-.Ar no state
+.Cm no state
is specified), only the initial SYN packet of a TCP handshake will create
a state for a TCP connection.
It is possible to be less restrictive, and allow state creation from
intermediate
.Pq non-SYN
packets, by specifying
-.Ar flags any .
+.Cm flags any .
This will cause
.Xr pf 4
to synchronize to existing connections, for instance
However, states created from such intermediate packets may be missing
connection details such as the TCP window scaling factor.
States which modify the packet flow, such as those affected by
-.Ar af-to ,
-.Ar modulate ,
-.Ar nat-to ,
-.Ar rdr-to ,
+.Cm af-to ,
+.Cm modulate state ,
+.Cm nat-to ,
+.Cm rdr-to ,
or
-.Ar synproxy state
+.Cm synproxy state
options, or scrubbed with
-.Ar reassemble tcp ,
+.Cm reassemble tcp ,
will also not be recoverable from intermediate packets.
Such connections will stall and time out.
.Pp
-.It Ar group Aq Ar group
+.It Cm group Ar group
Similar to
-.Ar user ,
-this rule only applies to packets of sockets owned by the specified group.
+.Cm user ,
+this rule only applies to packets of sockets owned by the specified
+.Ar group .
.Pp
-.It Xo Ar icmp-type Aq Ar type
-.Ar code Aq Ar code
-.Xc
-.It Xo Ar icmp6-type Aq Ar type
-.Ar code Aq Ar code
-.Xc
+.It Cm icmp-type Ar type Cm code Ar code
+.It Cm icmp6-type Ar type Cm code Ar code
This rule only applies to ICMP or ICMP6 packets with the specified type
and code.
Text names for ICMP types and codes are listed in
.Xr icmp6 4 .
The protocol and the ICMP type indicator
.Po
-.Ar icmp-type
+.Cm icmp-type
or
-.Ar icmp6-type
+.Cm icmp6-type
.Pc
must match.
.Pp
-.It Ar label Aq Ar string
+.It Cm label Ar string
Adds a label to the rule, which can be used to identify the rule.
For instance,
-.Dq pfctl -s labels
+.Ql pfctl -s labels
shows per-rule statistics for rules that have labels.
.Pp
The following macros can be used in labels:
.Pp
.Bl -tag -width "$srcaddrXXX" -compact -offset indent
-.It Ar $dstaddr
+.It Va $dstaddr
The destination IP address.
-.It Ar $dstport
+.It Va $dstport
The destination port specification.
-.It Ar $if
+.It Va $if
The interface.
-.It Ar $nr
+.It Va $nr
The rule number.
-.It Ar $proto
+.It Va $proto
The protocol name.
-.It Ar $srcaddr
+.It Va $srcaddr
The source IP address.
-.It Ar $srcport
+.It Va $srcport
The source port specification.
.El
.Pp
.Ed
.Pp
The macro expansion for the
-.Ar label
+.Cm label
directive occurs only at configuration file parse time, not during runtime.
.Pp
-.It Ar once
+.It Cm once
Creates a one shot rule that will remove itself from an active ruleset after
the first match.
In case this is the only rule in the anchor, the anchor will be destroyed
automatically after the rule is matched.
.Pp
-.It Ar probability Aq Ar number
+.It Cm probability Ar number Ns %
A probability attribute can be attached to a rule,
with a value set between 0 and 100%,
in which case the rule is honoured using the given probability value.
.Pp
.Dl block in proto icmp probability 20%
.Pp
-.It Ar prio Aq Ar number
+.It Cm prio Ar number
Only match packets which have the given queueing priority assigned.
.Pp
-.It Ar received-on Aq Ar interface
+.It Cm received-on Ar interface
Only match packets which were received on the specified
-.Ar interface
+.Cm interface
(or interface group).
-.Ar any
+.Cm any
will match any existing interface except loopback ones.
.Pp
-.It Ar rtable Aq Ar number
+.It Cm rtable Ar number
Used to select an alternate routing table for the routing lookup.
Only effective before the route lookup happened, i.e. when filtering inbound.
.Pp
-.It Xo Ar set prio Aq Ar priority
-.No \&| Po
-.Aq Ar priority ,
-.Aq Ar priority
-.Pc
-.Xc
+.It Cm set prio Ar priority | Pq Ar priority , priority
Packets matching this rule will be assigned a specific queueing priority.
Priorities are assigned as integers 0 through 7,
with a default priority of 3.
interface, the queueing priority will also be written as the priority
code point in the 802.1Q VLAN header.
If two priorities are given, packets which have a TOS of
-.Ar lowdelay
+.Cm lowdelay
and TCP ACKs with no data payload will be assigned to the second one.
Packets with a higher priority number are processed first,
and packets with the same priority are processed
.Ed
.Pp
The interface priority queues accessed by the
-.Ar set prio
+.Cm set prio
keyword are always enabled and do not require any additional
configuration, unlike the queues described below and in the
.Sx QUEUEING
section.
.Pp
-.It Xo Ar set queue Aq Ar queue
-.No \&| Po
-.Aq Ar queue ,
-.Aq Ar queue
-.Pc
-.Xc
-Packets matching this rule will be assigned to the specified queue.
+.It Cm set queue Ar queue | Pq Ar queue , queue
+Packets matching this rule will be assigned to the specified
+.Ar queue .
If two queues are given, packets which have a TOS of
-.Ar lowdelay
+.Cm lowdelay
and TCP ACKs with no data payload will be assigned to the second one.
See
.Sx QUEUEING
pass in proto tcp to port 22 set queue(ssh_bulk, ssh_prio)
.Ed
.Pp
-.It Xo Ar set tos Aq Ar string
-.No \&| Aq Ar number
-.Xc
+.It Cm set tos Ar string | number
Enforces a TOS for matching packets.
.Ar string
may be one of
-.Ar critical ,
-.Ar inetcontrol ,
-.Ar lowdelay ,
-.Ar netcontrol ,
-.Ar throughput ,
-.Ar reliability ,
+.Cm critical ,
+.Cm inetcontrol ,
+.Cm lowdelay ,
+.Cm netcontrol ,
+.Cm throughput ,
+.Cm reliability ,
or one of the DiffServ Code Points:
-.Ar ef ,
-.Ar af11 ... af43 ,
-.Ar cs0 ... cs7 ;
+.Cm ef ,
+.Cm af11 No ... Cm af43 ,
+.Cm cs0 No ... Cm cs7 ;
.Ar number
may be either a hex or decimal number.
.Pp
-.It Ar tag Aq Ar string
-Packets matching this rule will be tagged with the
-specified string.
+.It Cm tag Ar string
+Packets matching this rule will be tagged with the specified
+.Ar string .
The tag acts as an internal marker that can be used to
identify these packets later on.
This can be used, for example, to provide trust between
interfaces and to determine if packets have been
processed by translation rules.
Tags are
-.Qq sticky ,
+.Dq sticky ,
meaning that the packet will be tagged even if the rule
is not the last matching rule.
Further matching rules can replace the tag with a
A packet is only ever assigned one tag at a time.
Tags take the same macros as labels (see above).
.Pp
-.It Ar tagged Aq Ar string
+.It Oo Cm \&! Oc Ns Cm tagged Ar string
Used with filter or translation rules
to specify that packets must already
-be tagged with the given tag in order to match the rule.
+be tagged with the given
+.Ar string
+in order to match the rule.
Inverse tag matching can also be done
by specifying the
.Cm !\&
operator before the
-.Ar tagged
+.Cm tagged
keyword.
.Pp
-.It Xo Ar tos Aq Ar string
-.No \&| Aq Ar number
-.Xc
+.It Cm tos Ar string | number
This rule applies to packets with the specified TOS bits set.
.Ar string
may be one of
-.Ar critical ,
-.Ar inetcontrol ,
-.Ar lowdelay ,
-.Ar netcontrol ,
-.Ar throughput ,
-.Ar reliability ,
+.Cm critical ,
+.Cm inetcontrol ,
+.Cm lowdelay ,
+.Cm netcontrol ,
+.Cm throughput ,
+.Cm reliability ,
or one of the DiffServ Code Points:
-.Ar ef ,
-.Ar af11 ... af43 ,
-.Ar cs0 ... cs7 ;
+.Cm ef ,
+.Cm af11 No ... Cm af43 ,
+.Cm cs0 No ... Cm cs7 ;
.Ar number
may be either a hex or decimal number.
.Pp
pass all tos 16
.Ed
.Pp
-.It Ar user Aq Ar user
-This rule only applies to packets of sockets owned by the specified user.
+.It Cm user Ar user
+This rule only applies to packets of sockets owned by the specified
+.Ar user .
For outgoing connections initiated from the firewall, this is the user
that opened the connection.
For incoming connections to the firewall itself, this is the user that
.Xr pf 4
cannot determine if a connection is destined for the firewall itself.
To avoid false matches on just the destination port, combine a
-.Ar user
+.Cm user
rule with source or destination address
-.Ar self .
+.Cm self .
.Pp
All packets, both outgoing and incoming, of one connection are associated
with the same user and group.
Only TCP and UDP packets can be associated with users.
.Pp
-User and group refer to the effective (as opposed to the real) IDs, in
+The
+.Ar user
+and
+.Ar group
+arguments refer to the effective (as opposed to the real) IDs, in
case the socket is created by a setuid/setgid process.
User and group IDs are stored when a socket is created;
when a process creates a listening socket as root (for instance, by
and correctly direct return traffic for that connection.
.Pp
Different types of translation are possible with pf:
-.Bl -tag -width xxxxxxxx
-.It Ar af-to
+.Bl -tag -width binat-to
+.It Cm af-to
Translation between different address families (NAT64) is handled
using
-.Ar af-to
+.Cm af-to
rules.
Because address family translation overrides the routing table, it's
only possible to use
-.Ar af-to
+.Cm af-to
on inbound rules, and a source address for the resulting translation
must always be specified.
.Pp
.Pp
The current implementation will only extract IPv4 addresses from the
IPv6 addresses with a prefix length of /96 and greater.
-.It Ar binat-to
+.It Cm binat-to
A
-.Ar binat-to
+.Cm binat-to
rule specifies a bidirectional mapping between an external IP
netblock and an internal IP netblock.
It expands to an outbound
-.Ar nat-to
+.Cm nat-to
rule and an inbound
-.Ar rdr-to
+.Cm rdr-to
rule.
-.It Ar nat-to
+.It Cm nat-to
A
-.Ar nat-to
+.Cm 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.
+machines on an
+.Dq 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:
192.168.0.0 \(en 192.168.255.255 (i.e. 192.168/16)
.Ed
.Pp
-.Ar nat-to
+.Cm nat-to
is usually applied outbound.
If applied inbound, nat-to to a local IP address is not supported.
-.It Ar rdr-to
+.It Cm rdr-to
The packet is redirected to another destination and possibly a
different port.
-.Ar rdr-to
+.Cm rdr-to
can optionally specify port ranges instead of single ports.
For instance:
.Bl -tag -width Ds
redirects port 2000 to 4000, port 2001 to 4001, ..., port 2999 to 4999.
.El
.Pp
-.Ar rdr-to
+.Cm rdr-to
is usually applied inbound.
If applied outbound, rdr-to to a local IP address is not supported.
.El
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
+.Cm nat-to
options and explicitly in the case of
-.Ar rdr-to
+.Cm rdr-to
ones.
Port numbers are never translated with a
-.Ar binat-to
+.Cm binat-to
rule.
.Pp
Translation options apply only to packets that pass through the specified
any address.
.Pp
For
-.Ar af-to ,
-.Ar nat-to
+.Cm af-to ,
+.Cm nat-to
and
-.Ar rdr-to
+.Cm 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
+.It Cm bitmask
The
-.Ar bitmask
+.Cm bitmask
option applies the network portion of the redirection address to the address
to be modified (source with
-.Ar nat-to ,
+.Cm nat-to ,
destination with
-.Ar rdr-to ) .
-.It Ar least-states Op Ar sticky-address
+.Cm rdr-to ) .
+.It Cm least-states Op Cm sticky-address
The
-.Ar least-states
+.Cm least-states
option selects the address with the least active states from
a given address pool and considers given weights
associated with address(es).
Weights can be specified between 1 and 65535.
Addresses with higher weights are selected more often.
.Pp
-.Ar sticky-address
+.Cm 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
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 random Op Ar sticky-address
+.Ic set Cm timeout src.track .
+.It Cm random Op Cm sticky-address
The
-.Ar random
+.Cm random
option selects an address at random within the defined block of addresses.
-.Ar sticky-address
+.Cm sticky-address
is as described above.
-.It Ar round-robin Op Ar sticky-address
+.It Cm round-robin Op Cm sticky-address
The
-.Ar round-robin
+.Cm round-robin
option loops through the redirection address(es) and considers given weights
associated with address(es).
Weights can be specified between 1 and 65535.
Addresses with higher weights are selected more often.
-.Ar sticky-address
+.Cm sticky-address
is as described above.
-.It Ar source-hash Op Ar key
+.It Cm source-hash Op Ar key
The
-.Ar source-hash
+.Cm 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
.Xr pfctl 8
randomly generates a key for source-hash every time the
ruleset is reloaded.
-.It Ar static-port
+.It Cm static-port
With
-.Ar nat
+.Cm nat-to
rules, the
-.Ar static-port
+.Cm static-port
option prevents
.Xr pf 4
from modifying the source port on TCP and UDP packets.
.El
.Pp
When more than one redirection address or a table is specified,
-.Ar bitmask
+.Cm bitmask
is not permitted as a pool type.
.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.
When such a rule creates state, the route option is also applied to all
packets matching the same connection.
-.Bl -tag -width xxxx
-.It Ar dup-to
+.Bl -tag -width route-to
+.It Cm dup-to
The
-.Ar dup-to
+.Cm dup-to
option creates a duplicate of the packet and routes it like
-.Ar route-to .
+.Cm route-to .
The original packet gets routed as it normally would.
-.It Ar reply-to
+.It Cm reply-to
The
-.Ar reply-to
+.Cm reply-to
option is similar to
-.Ar route-to ,
+.Cm route-to ,
but routes packets that pass in the opposite direction (replies) to the
specified interface.
Opposite direction is only defined in the context of a state entry, and
-.Ar reply-to
+.Cm reply-to
is useful only in rules that create state.
It can be used on systems with multiple external connections to
route all outgoing packets of a connection through the interface
the incoming connection arrived through (symmetric routing enforcement).
-.It Ar route-to
+.It Cm route-to
The
-.Ar route-to
+.Cm route-to
option routes the packet to the specified interface with an optional address
for the next hop.
When a
-.Ar route-to
+.Cm route-to
rule creates state, only packets that pass in the same direction as the
filter rule specifies will be routed in this way.
Packets passing in the opposite direction (replies) are not affected
.El
.Pp
For the
-.Ar dup-to ,
-.Ar reply-to ,
+.Cm dup-to ,
+.Cm reply-to ,
and
-.Ar route-to
+.Cm route-to
route 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),
the methods
-.Ar least-states ,
-.Ar random ,
-.Ar round-robin ,
+.Cm least-states ,
+.Cm random ,
+.Cm round-robin ,
and
-.Ar source-hash ,
+.Cm source-hash ,
as described above,
can be used.
.Sh OPTIONS
.Xr pf 4
may be tuned for various situations using the
-.Ar set
+.Ic set
command.
.Bl -tag -width Ds
-.It Ar set block-policy
+.It Ic set Cm block-policy drop | return
The
-.Ar block-policy
+.Cm block-policy
option sets the default behaviour for the packet
-.Ar block
+.Ic block
action:
.Pp
-.Bl -tag -width xxxxxxxx -compact
-.It Ar drop
+.Bl -tag -width return -compact
+.It Cm drop
Packet is silently dropped.
-.It Ar return
+.It Cm 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
+.It Ic set Cm debug Ar level
Set the debug
.Ar level ,
which limits the severity of log messages printed by
These keywords correspond to the similar (LOG_) values specified to the
.Xr syslog 3
library routine.
-.It Ar set fingerprints
-Load fingerprints of known operating systems from the given filename.
+.It Cm set Cm fingerprints Ar filename
+Load fingerprints of known operating systems from the given
+.Ar filename .
By default fingerprints of known operating systems are automatically
loaded from
.Xr pf.os 5 ,
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
+.It Ic set Cm hostid Ar number
+The 32-bit hostid
+.Ar number
identifies this firewall's state table entries to other firewalls
in a
.Xr pfsync 4
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
+.It Ic set Cm limit Ar limit-item number
Sets hard limits on the memory pools used by the packet filter.
See
.Xr pool 9
For example,
to set the maximum number of entries in the memory pool used by state table
entries (generated by
-.Ar pass
+.Ic pass
rules which do not specify
-.Ar no state )
+.Cm no state )
to 20000:
.Pp
.Dl set limit states 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
+.Cm sticky-address
and
-.Ar src.track
+.Cm src.track
options) to 2000:
.Pp
.Dl set limit src-nodes 2000
.Bd -literal -offset indent
set limit { states 20000, frags 2000, src-nodes 2000 }
.Ed
-.It Ar set loginterface
+.It Ic set Cm loginterface Ar interface | Cm none
Enable collection of packet and byte count statistics for the given
interface or interface group.
These statistics can be viewed using:
One can disable the loginterface using:
.Pp
.Dl set loginterface none
-.It Ar set optimization
+.It Ic set Cm optimization Ar environment
Optimize state timeouts for one of the following network environments:
.Pp
.Bl -tag -width Ds -compact
-.It Ar aggressive
+.It Cm 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
+.It Cm 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
+.It Cm high-latency
A high-latency environment (such as a satellite connection).
-.It Ar normal
+.It Cm normal
A normal network environment.
Suitable for almost all networks.
-.It Ar satellite
+.It Cm satellite
Alias for
-.Ar high-latency .
+.Cm high-latency .
.El
-.It Ar set reassemble
+.It Ic set Cm reassemble yes | no Op Cm no-df
The
-.Ar reassemble
+.Cm reassemble
option is used to enable or disable the reassembly of fragmented packets,
and can be set to
-.Ar yes
+.Cm yes
(the default) or
-.Ar no .
+.Cm no .
If
-.Ar no-df
+.Cm no-df
is also specified, fragments with the
-.Ar dont-fragment
+.Dq dont-fragment
bit set are reassembled too,
instead of being dropped;
the reassembled packet will have the
-.Ar dont-fragment
+.Dq dont-fragment
bit cleared.
-.It Ar set ruleset-optimization
-.Bl -tag -width xxxxxxxx -compact
-.It Ar basic
+.It Ic set Cm ruleset-optimization Ar level
+.Bl -tag -width profile -compact
+.It Cm basic
Enable basic ruleset optimization.
This is the default behaviour.
Basic ruleset optimization does four things to improve the
.It
re-order the rules to improve evaluation performance
.El
-.It Ar none
+.Pp
+.It Cm none
Disable the ruleset optimizer.
-.It Ar profile
+.It Cm profile
Uses the currently loaded ruleset as a feedback profile to tailor the
-ordering of quick rules to actual network traffic.
+ordering of
+.Cm quick
+rules to actual network traffic.
.El
.Pp
It is important to note that the ruleset optimizer will modify the ruleset
.Xr pfctl 8 ,
overriding the settings in
.Nm .
-.It Ar set skip on Aq Ar ifspec
+.It Ic set Cm skip on 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.
.Ar ifspec
is only evaluated when the ruleset is loaded; interfaces created
later will not be skipped.
-.It Ar set state-defaults
+.It Ic set Cm state-defaults Ar state-option , ...
The
-.Ar state-defaults
+.Cm state-defaults
option sets the state options for states created from rules
without an explicit
-.Ar keep state .
+.Cm keep state .
For example:
.Pp
.Dl set state-defaults pflow, no-sync
-.It Ar set state-policy
+.It Ic set Cm state-policy if-bound | floating
The
-.Ar state-policy
+.Cm state-policy
option sets the default behaviour for states:
.Pp
.Bl -tag -width if-bound -compact
-.It Ar if-bound
+.It Cm if-bound
States are bound to an interface.
-.It Ar floating
+.It Cm floating
States can match packets on any interfaces (the default).
.El
-.It Ar set timeout
+.It Ic set Cm timeout Ar variable value
.Bl -tag -width "src.track" -compact
-.It Ar frag
+.It Cm frag
Seconds before an unassembled fragment is expired.
-.It Ar interval
+.It Cm interval
Interval between purging expired states and fragments.
-.It Ar src.track
+.It Cm src.track
Length of time to retain a source tracking entry after the last state
expires.
.El
firewall at the risk of dropping valid idle connections.
.Pp
.Bl -tag -width Ds -compact
-.It Ar tcp.closed
+.It Cm tcp.closed
The state after one endpoint sends an RST.
-.It Ar tcp.closing
+.It Cm tcp.closing
The state after the first FIN has been sent.
-.It Ar tcp.established
+.It Cm tcp.established
The fully established state.
-.It Ar tcp.finwait
+.It Cm 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
+.Cm tcp.finwait
(and possibly
-.Ar tcp.closing )
+.Cm tcp.closing )
can prevent blocking of such packets.
-.It Ar tcp.first
+.It Cm tcp.first
The state after the first packet.
-.It Ar tcp.opening
+.It Cm tcp.opening
The state after the second packet but before both endpoints have
acknowledged the connection.
.El
limited set of states:
.Pp
.Bl -tag -width Ds -compact
-.It Ar icmp.error
+.It Cm icmp.error
The state after an ICMP error came back in response to an ICMP packet.
-.It Ar icmp.first
+.It Cm icmp.first
The state after the first packet.
-.It Ar udp.first
+.It Cm udp.first
The state after the first packet.
-.It Ar udp.multiple
+.It Cm udp.multiple
The state if both hosts have sent packets.
-.It Ar udp.single
+.It Cm udp.single
The state if the source host sends more than one packet but the destination
host has never sent one back.
.El
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
+.It Cm other.first
+.It Cm other.multiple
+.It Cm 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
+.It Cm 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
+.It Cm adaptive.start
When the number of state entries exceeds this value, adaptive scaling
begins.
All timeout values are scaled linearly with factor
more bandwidth as long as the parent still has some available.
The maximum bandwidth that should be assigned to a given queue can be limited
using the
-.Ar max
+.Cm max
keyword.
Similarly, a minimum (reserved) bandwidth can be specified.
.Bd -literal -offset indent
.Ed
.Pp
All
-.Ar bandwidth
+.Cm bandwidth
values must be specified as an absolute value.
The suffixes
-.Ar K ,
-.Ar M ,
+.Cm K ,
+.Cm M ,
and
-.Ar G
+.Cm G
are used to represent bits, kilobits, megabits, and
gigabits per second, respectively.
The value must not exceed the interface bandwidth.
In addition to the bandwidth specifications queues support the following
options:
.Bl -tag -width xxxx
-.It Ar default
+.It Cm default
Packets not matched by another queue are assigned to this queue.
Exactly one default queue per interface is required.
-.It Ar on Aq Ar interface
+.It Cm on Ar interface
Specifies the interface the queue operates on.
If not given, it operates on all matching interfaces.
-.It Ar parent Aq Ar name
+.It Cm parent Ar name
Defines which parent queue the queue should be attached to.
Mandatory for all queues except root queues.
The parent queue must exist.
-.It Ar qlimit Aq Ar limit
+.It Cm qlimit Ar limit
The maximum number of packets held in the queue.
The default is 50.
.El
.Pp
Packets can be assigned to queues based on filter rules by using the
-.Ar queue
+.Cm 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
+.Cm lowdelay
and for TCP ACKs with no data payload.
.Pp
To continue the previous example, the examples below would specify the
Tables can be used as the source or destination of filter
or translation rules.
They can also be used for the redirect address of
-.Ar nat-to
+.Cm nat-to
and
-.Ar rdr-to
+.Cm rdr-to
and in the routing options of filter rules, but not for
-.Ar bitmask
+.Cm bitmask
pools.
.Pp
Tables can be defined with any of the following
mechanisms.
As with macros, reserved words may not be used as table names.
.Bl -tag -width "manually"
-.It Ar manually
+.It manually
Persistent tables can be manually created with the
-.Ar add
+.Cm add
or
-.Ar replace
+.Cm replace
option of
.Xr pfctl 8 ,
before or after the ruleset has been loaded.
-.It Pa pf.conf
+.It Nm
Table definitions can be placed directly in this file and loaded at the
same time as other rules are loaded, atomically.
Table definitions inside
.Nm
use the
-.Ar table
+.Ic table
statement, and are especially useful to define non-persistent tables.
The contents of a pre-existing table defined without a list of addresses
to initialize it is not altered when
.Pp
Tables may be defined with the following attributes:
.Bl -tag -width counters
-.It Ar const
+.It Cm const
The
-.Ar const
+.Cm const
flag prevents the user from altering the contents of the table once it
has been created.
Without that flag,
when running with
.Xr securelevel 7
= 2.
-.It Ar counters
+.It Cm counters
The
-.Ar counters
+.Cm counters
flag enables per-address packet and byte counters, which can be displayed with
.Xr pfctl 8 .
-.It Ar persist
+.It Cm persist
The
-.Ar persist
+.Cm persist
flag forces the kernel to keep the table even when no rules refer to it.
If the flag is not set, the kernel will automatically remove the table
when the last rule referring to it is flushed.
.El
.Pp
-This example
-creates a table called private,
+This example creates a table called
+.Dq private ,
to hold RFC 1918 private network blocks,
-and a table called badhosts,
+and a table called
+.Dq badhosts ,
which is initially empty.
A filter rule is set up to block all traffic coming from addresses listed in
either table:
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,
-.Ar all
+.Em all
resulting IPv4 and IPv6 addresses are placed into the table.
IP addresses can also be entered in a table by specifying a valid interface
name, a valid interface group, or the
-.Ar self
+.Cm self
keyword, in which case all addresses assigned to the interface(s) will be
added to the table.
.Sh ANCHORS
Besides the main ruleset,
.Nm
-can specify
-.Ar anchor
-attachment points.
+can specify anchor attachment points.
An anchor is a container that can hold rules,
address tables, and other anchors.
When evaluation of the main ruleset reaches an
-.Ar anchor
+.Ic anchor
rule,
.Xr pf 4
will proceed to evaluate all rules specified in that anchor.
.Ed
.Pp
The anchor can also be populated by adding a
-.Ar load anchor
+.Ic load anchor
rule after the anchor rule.
When
.Xr pfctl 8
.Ed
.Pp
Matching filter and translation rules marked with the
-.Ar quick
+.Cm quick
option are final and abort the evaluation of the rules in other
anchors and the main ruleset.
If the anchor itself is marked with the
-.Ar quick
+.Cm quick
option,
ruleset evaluation will terminate when the anchor is exited if the packet is
matched by any rule within the anchor.
An anchor references other anchor attachment points
using the following syntax:
.Bl -tag -width xxxx
-.It Ar anchor Aq Ar name
+.It Ic anchor Ar name
Evaluates the filter rules in the specified anchor.
.El
.Pp
all anchor rules specified in the main ruleset will reference
anchor attachment points underneath the main ruleset,
and anchor rules specified in a file loaded from a
-.Ar load anchor
+.Ic load anchor
rule will be attached under that anchor point.
.Pp
Anchors may end with the asterisk
Evaluation of the main ruleset will lead into the
spam/allowed anchor, which will evaluate the rules in the
spam/banned anchor, if any, before finally evaluating the
-.Ar pass
+.Ic pass
rule.
.Sh STATEFUL FILTERING
.Xr pf 4
which has several advantages.
For TCP connections, comparing a packet to a state involves checking
its sequence numbers, as well as TCP timestamps if a rule using the
-.Ar reassemble tcp
+.Cm reassemble tcp
parameter applies to the connection.
If these values are outside the narrow windows of expected
values, the packet is dropped.
connection arrives, it will be matched to the state and get passed.
.Pp
Finally, state tracking is required for
-.Ar nat-to
+.Cm nat-to
and
-.Ar rdr-to
+.Cm rdr-to
options, in order to track address and port translations and reverse the
translation on returning packets.
.Pp
.Pp
If stateless filtering of individual packets is desired,
the
-.Ar no state
+.Cm no state
keyword can be used to specify that state will not be created
if this is the last matching rule.
Note that packets which match neither block nor pass rules,
and thus are passed by default,
are effectively passed as if
-.Ar no state
+.Cm no state
had been specified.
.Pp
A number of parameters can also be set to affect how
.Em very
poor ISNs and thus are normally susceptible to ISN prediction exploits.
By applying a
-.Ar modulate state
+.Cm modulate state
rule to a TCP connection,
.Xr pf 4
will create a high quality random sequence number for each connection
endpoint.
.Pp
The
-.Ar modulate state
+.Cm modulate state
directive implicitly keeps state on the rule and is
only applicable to TCP connections.
.Pp
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.
The default
-.Ar flags
+.Cm flags
settings (or a more strict equivalent) should be used on
-.Ar modulate state
+.Cm modulate state
rules to prevent ACK storms.
.Pp
Note that alternative methods are available
passes packets that are part of a
TCP handshake between the endpoints.
The
-.Ar synproxy state
+.Cm synproxy state
option can be used to cause
.Xr pf 4
itself to complete the handshake with the active endpoint, perform a handshake
Once the handshakes are completed, the sequence number modulators
(see previous section) are used to translate further packets of the
connection.
-.Ar synproxy state
+.Cm synproxy state
includes
-.Ar modulate state .
+.Cm modulate state .
.Pp
Rules with
-.Ar synproxy
+.Cm synproxy state
will not work if
.Xr pf 4
operates on a
A number of options related to stateful tracking can be applied on a
per-rule basis.
One of
-.Ar keep state ,
-.Ar modulate state ,
+.Cm keep state ,
+.Cm modulate state ,
or
-.Ar synproxy state
+.Cm synproxy state
must be specified explicitly to apply these options to a rule.
.Pp
.Bl -tag -width xxxx -compact
-.It Ar floating
+.It Cm floating
States can match packets on any interfaces
(the opposite of
-.Ar if-bound ) .
+.Cm if-bound ) .
This is the default.
-.It Ar if-bound
+.It Cm if-bound
States are bound to an interface
(the opposite of
-.Ar floating ) .
-.It Ar max Aq Ar number
+.Cm floating ) .
+.It Cm max Ar number
Limits the number of concurrent states the rule may create.
When this limit is reached, further packets that would create
state are dropped until existing states time out.
-.It Ar no-sync
+.It Cm no-sync
Prevent state changes for states created by this rule from appearing on the
.Xr pfsync 4
interface.
-.It Ar pflow
+.It Cm pflow
States created by this rule are exported on the
.Xr pflow 4
interface.
-.It Ar sloppy
+.It Cm sloppy
Uses a sloppy TCP connection tracker that does not check sequence
numbers at all, which makes insertion and ICMP teardown attacks way
easier.
This is intended to be used in situations where one does not see all
packets of a connection, e.g. in asymmetric routing situations.
It cannot be used with
-.Ar modulate
+.Cm modulate state
or
-.Ar synproxy state .
-.It Xo Aq Ar timeout
-.Aq Ar seconds
-.Xc
-Changes the timeout values used for states created by this rule.
-For a list of all valid timeout names, see
+.Cm synproxy state .
+.It Ar timeout seconds
+Changes the
+.Ar timeout
+values used for states created by this rule.
+For a list of all valid
+.Ar timeout
+names, see
.Sx OPTIONS
above.
.El
.Ed
.Pp
When the
-.Ar source-track
+.Cm source-track
keyword is specified, the number of states per source IP is tracked.
.Pp
.Bl -tag -width xxxx -compact
-.It Ar source-track global
+.It Cm source-track global
The number of states created by all rules that use this option is limited.
Each rule can specify different
-.Ar max-src-nodes
+.Cm max-src-nodes
and
-.Ar max-src-states
+.Cm max-src-states
options, however state entries created by any participating rule count towards
each individual rule's limits.
-.It Ar source-track rule
+.It Cm source-track rule
The maximum number of states created by this rule is limited by the rule's
-.Ar max-src-nodes
+.Cm max-src-nodes
and
-.Ar max-src-states
+.Cm max-src-states
options.
Only state entries created by this particular rule count toward the rule's
limits.
The following limits can be set:
.Pp
.Bl -tag -width xxxx -compact
-.It Ar max-src-nodes Aq Ar number
+.It Cm max-src-nodes Ar number
Limits the maximum number of source addresses which can simultaneously
have state table entries.
-.It Ar max-src-states Aq Ar number
+.It Cm max-src-states Ar number
Limits the maximum number of simultaneous state entries that a single
source address can create with this rule.
.El
per source IP.
.Pp
.Bl -tag -width xxxx -compact
-.It Ar max-src-conn Aq Ar number
+.It Cm max-src-conn Ar number
Limits the maximum number of simultaneous TCP connections which have
completed the 3-way handshake that a single host can make.
-.It Xo Ar max-src-conn-rate Aq Ar number
-.No / Aq Ar seconds
-.Xc
+.It Cm max-src-conn-rate Ar number Ns / Ns Ar seconds
Limit the rate of new connections over a time interval.
The connection rate is an approximation calculated as a moving average.
.El
Because the 3-way handshake ensures that the source address is not being
spoofed, more aggressive action can be taken based on these limits.
With the
-.Ar overload Aq Ar table
+.Cm overload Pf < Ar table Ns >
state option, source IP addresses which hit either of the limits on
-established connections will be added to the named table.
+established connections will be added to the named
+.Ar table .
This table can be used in the ruleset to block further activity from
the offending host, redirect it to a tarpit process, or restrict its
bandwidth.
.Pp
The optional
-.Ar flush
+.Cm flush
keyword kills all states created by the matching rule which originate
from the host which exceeds these limits.
The
-.Ar global
-modifier to the flush command kills all states originating from the
+.Cm global
+modifier to the
+.Cm flush
+command kills all states originating from the
offending host, regardless of which rule created the state.
.Pp
For example, the following rules will protect the webserver against
hosts making more than 100 connections in 10 seconds.
Any host which connects faster than this rate will have its address added
-to the
-.Aq bad_hosts
-table and have all states originating from it flushed.
+to the <bad_hosts> table and have all states originating from it flushed.
Any new packets arriving from this host will be dropped unconditionally
by the block rule.
.Bd -literal -offset indent
Scrub involves sanitising packet content in such a way
that there are no ambiguities in packet interpretation on the receiving side.
It is invoked with the
-.Ar scrub
+.Cm scrub
option, added to regular rules.
.Pp
Parameters are specified enclosed in parentheses.
At least one of the following parameters must be specified:
.Bl -tag -width xxxx
-.It Ar max-mss Aq Ar number
+.It Cm max-mss Ar number
Enforces a maximum segment size (MSS) for matching TCP packets.
-.It Ar min-ttl Aq Ar number
+.It Cm min-ttl Ar number
Enforces a minimum TTL for matching IP packets.
-.It Ar no-df
+.It Cm no-df
Clears the
-.Ar dont-fragment
+.Dq dont-fragment
bit from a matching IPv4 packet.
Some operating systems have NFS implementations
which are known to generate fragmented packets with the
-.Ar dont-fragment
+.Dq dont-fragment
bit set.
.Xr pf 4
will drop such fragmented
-.Ar dont-fragment
+.Dq dont-fragment
packets unless
-.Ar no-df
+.Cm no-df
is specified.
.Pp
Unfortunately some operating systems also generate their
-.Ar dont-fragment
+.Dq dont-fragment
packets with a zero IP identification field.
Clearing the
-.Ar dont-fragment
+.Dq dont-fragment
bit on packets with a zero IP ID may cause deleterious results if an
upstream router later fragments the packet.
Using
-.Ar random-id
+.Cm random-id
is recommended in combination with
-.Ar no-df
+.Cm no-df
to ensure unique IP identifiers.
-.It Ar random-id
+.It Cm random-id
Replaces the IPv4 identification field with random values to compensate
for predictable values generated by many hosts.
This option only applies to packets that are not fragmented
after the optional fragment reassembly.
-.It Ar reassemble tcp
+.It Cm reassemble tcp
Statefully normalises TCP connections.
-.Ar reassemble tcp
+.Cm reassemble tcp
performs the following normalisations:
.Bl -ohang
.It TTL
Neither side of the connection is allowed to reduce their IP TTL.
An attacker may send a packet such that it reaches the firewall, affects
the firewall state, and expires before reaching the destination host.
-.Ar reassemble tcp
+.Cm reassemble tcp
will raise the TTL of all packets back up to the highest value seen on
the connection.
.It Timestamp Modulation
valid timestamps.
Timestamps merely need to be monotonically increasing and not derived off a
guessable base time.
-.Ar reassemble tcp
+.Cm reassemble tcp
will cause
-.Ar scrub
+.Cm scrub
to modulate the TCP timestamps with a random number.
.It Extended PAWS Checks
There is a problem with TCP on long fat pipes, in that a packet might get
numbers.
It protects against it by making sure the timestamp on each packet does
not go backwards.
-.Ar reassemble tcp
+.Cm reassemble tcp
also makes sure the timestamp on the packet does not go forward more
than the RFC allows.
By doing this,
fields (source/destination address, protocol), since subprotocol header
fields are not available (TCP/UDP port numbers, ICMP code/type).
The
-.Ar fragment
+.Cm fragment
option can be used to restrict filter rules to apply only to
fragments, but not complete packets.
Filter rules without the
-.Ar fragment
+.Cm fragment
option still apply to fragments, if they only specify IP header fields.
For instance:
.Bd -literal -offset indent
Spoofing is the faking of IP addresses,
typically for malicious purposes.
The
-.Ar antispoof
+.Ic antispoof
directive expands to a set of filter rules which will block all
traffic with a source IP from the network(s) directly connected
to the specified interface(s) from entering the system through
.Ed
.Pp
Caveat: Rules created by the
-.Ar antispoof
+.Ic antispoof
directive interfere with packets sent over loopback interfaces
to local addresses.
One should pass these explicitly.
.Ox ,
the only subtype is for a fingerprint that was
normalised by the
-.Ar no-df
+.Cm no-df
scrub option and would be specified as:
.Pp
.Dl \&"OpenBSD 3.3 no-df\&"
from hosts that aren't at the latest service pack.
.Pp
The
-.Ar unknown
+.Cm unknown
class can also be used as the fingerprint which will match packets for
which no operating system fingerprint is known.
.Pp
and multiple operating systems may have the same fingerprint.
.Sh EXAMPLES
In this example,
-the external interface is kue0.
+the external interface is
+.Pa kue0 .
We use a macro for the interface name, so it can be changed easily.
All incoming traffic is "normalised",
and everything is blocked and logged by default.
.Ed
.Pp
If a
-.Ar pass
+.Ic pass
rule is used with the
-.Ar quick
+.Cm quick
modifier, packets matching the translation rule are passed without
inspecting subsequent filter rules.
.Bd -literal -offset 4n
.Ed
.Pp
One more example uses
-.Ar rdr-to
+.Cm 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
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.
+using the
+.Cm 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
.Ed
.Pp
The bidirectional address translation example uses a single
-.Ar binat-to
+.Cm binat-to
rule that expands to a
-.Ar nat-to
+.Cm nat-to
and an
-.Ar rdr-to
+.Cm rdr-to
rule.
.Bd -literal -offset 4n
pass on $ext_if from 10.1.2.120 to any binat-to 192.0.2.17
pooltype = ( "bitmask" | "least-states" |
"random" | "round-robin" |
"source-hash" [ ( hex-key | string-key ) ] )
- [ sticky-address ]
+ [ "sticky-address" ]
include = "include" filename
.Ed
projects / openbsd / commitdiff