xref: /freebsd/share/man/man5/pf.conf.5 (revision 79d939126a819f31882343b5733c2073452a4218)
1.\"    $FreeBSD$
2.\"	$OpenBSD: pf.conf.5,v 1.406 2009/01/31 19:37:12 sobrado Exp $
3.\"
4.\" Copyright (c) 2002, Daniel Hartmeier
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\"    - Redistributions of source code must retain the above copyright
12.\"      notice, this list of conditions and the following disclaimer.
13.\"    - Redistributions in binary form must reproduce the above
14.\"      copyright notice, this list of conditions and the following
15.\"      disclaimer in the documentation and/or other materials provided
16.\"      with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
24.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
28.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29.\" POSSIBILITY OF SUCH DAMAGE.
30.\"
31.Dd March 9, 2022
32.Dt PF.CONF 5
33.Os
34.Sh NAME
35.Nm pf.conf
36.Nd packet filter configuration file
37.Sh DESCRIPTION
38The
39.Xr pf 4
40packet filter modifies, drops or passes packets according to rules or
41definitions specified in
42.Nm pf.conf .
43.Sh STATEMENT ORDER
44There are eight types of statements in
45.Nm pf.conf :
46.Bl -tag -width xxxx
47.It Cm Macros
48User-defined variables may be defined and used later, simplifying
49the configuration file.
50Macros must be defined before they are referenced in
51.Nm pf.conf .
52.It Cm Tables
53Tables provide a mechanism for increasing the performance and flexibility of
54rules with large numbers of source or destination addresses.
55.It Cm Options
56Options tune the behaviour of the packet filtering engine.
57.It Cm Ethernet Filtering
58Ethernet filtering provides rule-based blocking or passing of Ethernet packets.
59.It Cm Traffic Normalization Li (e.g. Em scrub )
60Traffic normalization protects internal machines against inconsistencies
61in Internet protocols and implementations.
62.It Cm Queueing
63Queueing provides rule-based bandwidth control.
64.It Cm Translation Li (Various forms of NAT)
65Translation rules specify how addresses are to be mapped or redirected to
66other addresses.
67.It Cm Packet Filtering
68Packet filtering provides rule-based blocking or passing of packets.
69.El
70.Pp
71With the exception of
72.Cm macros
73and
74.Cm tables ,
75the types of statements should be grouped and appear in
76.Nm pf.conf
77in the order shown above, as this matches the operation of the underlying
78packet filtering engine.
79By default
80.Xr pfctl 8
81enforces this order (see
82.Ar set require-order
83below).
84.Pp
85Comments can be put anywhere in the file using a hash mark
86.Pq Sq # ,
87and extend to the end of the current line.
88.Pp
89Additional configuration files can be included with the
90.Ic include
91keyword, for example:
92.Bd -literal -offset indent
93include "/etc/pf/sub.filter.conf"
94.Ed
95.Sh MACROS
96Macros can be defined that will later be expanded in context.
97Macro names must start with a letter, and may contain letters, digits
98and underscores.
99Macro names may not be reserved words (for example
100.Ar pass ,
101.Ar in ,
102.Ar out ) .
103Macros are not expanded inside quotes.
104.Pp
105For example,
106.Bd -literal -offset indent
107ext_if = \&"kue0\&"
108all_ifs = \&"{\&" $ext_if lo0 \&"}\&"
109pass out on $ext_if from any to any
110pass in  on $ext_if proto tcp from any to any port 25
111.Ed
112.Sh TABLES
113Tables are named structures which can hold a collection of addresses and
114networks.
115Lookups against tables in
116.Xr pf 4
117are relatively fast, making a single rule with tables much more efficient,
118in terms of
119processor usage and memory consumption, than a large number of rules which
120differ only in IP address (either created explicitly or automatically by rule
121expansion).
122.Pp
123Tables can be used as the source or destination of filter rules,
124.Ar scrub
125rules
126or
127translation rules such as
128.Ar nat
129or
130.Ar rdr
131(see below for details on the various rule types).
132Tables can also be used for the redirect address of
133.Ar nat
134and
135.Ar rdr
136rules and in the routing options of filter rules, but only for
137.Ar round-robin
138pools.
139.Pp
140Tables can be defined with any of the following
141.Xr pfctl 8
142mechanisms.
143As with macros, reserved words may not be used as table names.
144.Bl -tag -width "manually"
145.It Ar manually
146Persistent tables can be manually created with the
147.Ar add
148or
149.Ar replace
150option of
151.Xr pfctl 8 ,
152before or after the ruleset has been loaded.
153.It Pa pf.conf
154Table definitions can be placed directly in this file, and loaded at the
155same time as other rules are loaded, atomically.
156Table definitions inside
157.Nm pf.conf
158use the
159.Ar table
160statement, and are especially useful to define non-persistent tables.
161The contents of a pre-existing table defined without a list of addresses
162to initialize it is not altered when
163.Nm pf.conf
164is loaded.
165A table initialized with the empty list,
166.Li { } ,
167will be cleared on load.
168.El
169.Pp
170Tables may be defined with the following attributes:
171.Bl -tag -width persist
172.It Ar persist
173The
174.Ar persist
175flag forces the kernel to keep the table even when no rules refer to it.
176If the flag is not set, the kernel will automatically remove the table
177when the last rule referring to it is flushed.
178.It Ar const
179The
180.Ar const
181flag prevents the user from altering the contents of the table once it
182has been created.
183Without that flag,
184.Xr pfctl 8
185can be used to add or remove addresses from the table at any time, even
186when running with
187.Xr securelevel 7
188= 2.
189.It Ar counters
190The
191.Ar counters
192flag enables per-address packet and byte counters which can be displayed with
193.Xr pfctl 8 .
194Note that this feature carries significant memory overhead for large tables.
195.El
196.Pp
197For example,
198.Bd -literal -offset indent
199table \*(Ltprivate\*(Gt const { 10/8, 172.16/12, 192.168/16 }
200table \*(Ltbadhosts\*(Gt persist
201block on fxp0 from { \*(Ltprivate\*(Gt, \*(Ltbadhosts\*(Gt } to any
202.Ed
203.Pp
204creates a table called private, to hold RFC 1918 private network
205blocks, and a table called badhosts, which is initially empty.
206A filter rule is set up to block all traffic coming from addresses listed in
207either table.
208The private table cannot have its contents changed and the badhosts table
209will exist even when no active filter rules reference it.
210Addresses may later be added to the badhosts table, so that traffic from
211these hosts can be blocked by using
212.Bd -literal -offset indent
213# pfctl -t badhosts -Tadd 204.92.77.111
214.Ed
215.Pp
216A table can also be initialized with an address list specified in one or more
217external files, using the following syntax:
218.Bd -literal -offset indent
219table \*(Ltspam\*(Gt persist file \&"/etc/spammers\&" file \&"/etc/openrelays\&"
220block on fxp0 from \*(Ltspam\*(Gt to any
221.Ed
222.Pp
223The files
224.Pa /etc/spammers
225and
226.Pa /etc/openrelays
227list IP addresses, one per line.
228Any lines beginning with a # are treated as comments and ignored.
229In addition to being specified by IP address, hosts may also be
230specified by their hostname.
231When the resolver is called to add a hostname to a table,
232.Em all
233resulting IPv4 and IPv6 addresses are placed into the table.
234IP addresses can also be entered in a table by specifying a valid interface
235name, a valid interface group or the
236.Em self
237keyword, in which case all addresses assigned to the interface(s) will be
238added to the table.
239.Sh OPTIONS
240.Xr pf 4
241may be tuned for various situations using the
242.Ar set
243command.
244.Bl -tag -width xxxx
245.It Ar set timeout
246.Pp
247.Bl -tag -width "src.track" -compact
248.It Ar interval
249Interval between purging expired states and fragments.
250.It Ar frag
251Seconds before an unassembled fragment is expired.
252.It Ar src.track
253Length of time to retain a source tracking entry after the last state
254expires.
255.El
256.Pp
257When a packet matches a stateful connection, the seconds to live for the
258connection will be updated to that of the
259.Ar proto.modifier
260which corresponds to the connection state.
261Each packet which matches this state will reset the TTL.
262Tuning these values may improve the performance of the
263firewall at the risk of dropping valid idle connections.
264.Pp
265.Bl -tag -width xxxx -compact
266.It Ar tcp.first
267The state after the first packet.
268.It Ar tcp.opening
269The state before the destination host ever sends a packet.
270.It Ar tcp.established
271The fully established state.
272.It Ar tcp.closing
273The state after the first FIN has been sent.
274.It Ar tcp.finwait
275The state after both FINs have been exchanged and the connection is closed.
276Some hosts (notably web servers on Solaris) send TCP packets even after closing
277the connection.
278Increasing
279.Ar tcp.finwait
280(and possibly
281.Ar tcp.closing )
282can prevent blocking of such packets.
283.It Ar tcp.closed
284The state after one endpoint sends an RST.
285.El
286.Pp
287ICMP and UDP are handled in a fashion similar to TCP, but with a much more
288limited set of states:
289.Pp
290.Bl -tag -width xxxx -compact
291.It Ar udp.first
292The state after the first packet.
293.It Ar udp.single
294The state if the source host sends more than one packet but the destination
295host has never sent one back.
296.It Ar udp.multiple
297The state if both hosts have sent packets.
298.It Ar icmp.first
299The state after the first packet.
300.It Ar icmp.error
301The state after an ICMP error came back in response to an ICMP packet.
302.El
303.Pp
304Other protocols are handled similarly to UDP:
305.Pp
306.Bl -tag -width xxxx -compact
307.It Ar other.first
308.It Ar other.single
309.It Ar other.multiple
310.El
311.Pp
312Timeout values can be reduced adaptively as the number of state table
313entries grows.
314.Pp
315.Bl -tag -width xxxx -compact
316.It Ar adaptive.start
317When the number of state entries exceeds this value, adaptive scaling
318begins.
319All timeout values are scaled linearly with factor
320(adaptive.end - number of states) / (adaptive.end - adaptive.start).
321.It Ar adaptive.end
322When reaching this number of state entries, all timeout values become
323zero, effectively purging all state entries immediately.
324This value is used to define the scale factor, it should not actually
325be reached (set a lower state limit, see below).
326.El
327.Pp
328Adaptive timeouts are enabled by default, with an adaptive.start value
329equal to 60% of the state limit, and an adaptive.end value equal to
330120% of the state limit.
331They can be disabled by setting both adaptive.start and adaptive.end to 0.
332.Pp
333The adaptive timeout values can be defined both globally and for each rule.
334When used on a per-rule basis, the values relate to the number of
335states created by the rule, otherwise to the total number of
336states.
337.Pp
338For example:
339.Bd -literal -offset indent
340set timeout tcp.first 120
341set timeout tcp.established 86400
342set timeout { adaptive.start 6000, adaptive.end 12000 }
343set limit states 10000
344.Ed
345.Pp
346With 9000 state table entries, the timeout values are scaled to 50%
347(tcp.first 60, tcp.established 43200).
348.It Ar set loginterface
349Enable collection of packet and byte count statistics for the given
350interface or interface group.
351These statistics can be viewed using
352.Bd -literal -offset indent
353# pfctl -s info
354.Ed
355.Pp
356In this example
357.Xr pf 4
358collects statistics on the interface named dc0:
359.Bd -literal -offset indent
360set loginterface dc0
361.Ed
362.Pp
363One can disable the loginterface using:
364.Bd -literal -offset indent
365set loginterface none
366.Ed
367.It Ar set limit
368Sets hard limits on the memory pools used by the packet filter.
369See
370.Xr zone 9
371for an explanation of memory pools.
372.Pp
373For example,
374.Bd -literal -offset indent
375set limit states 20000
376.Ed
377.Pp
378sets the maximum number of entries in the memory pool used by state table
379entries (generated by
380.Ar pass
381rules which do not specify
382.Ar no state )
383to 20000.
384Using
385.Bd -literal -offset indent
386set limit frags 20000
387.Ed
388.Pp
389sets the maximum number of entries in the memory pool used for fragment
390reassembly (generated by
391.Ar scrub
392rules) to 20000.
393Using
394.Bd -literal -offset indent
395set limit src-nodes 2000
396.Ed
397.Pp
398sets the maximum number of entries in the memory pool used for tracking
399source IP addresses (generated by the
400.Ar sticky-address
401and
402.Ar src.track
403options) to 2000.
404Using
405.Bd -literal -offset indent
406set limit tables 1000
407set limit table-entries 100000
408.Ed
409.Pp
410sets limits on the memory pools used by tables.
411The first limits the number of tables that can exist to 1000.
412The second limits the overall number of addresses that can be stored
413in tables to 100000.
414.Pp
415Various limits can be combined on a single line:
416.Bd -literal -offset indent
417set limit { states 20000, frags 20000, src-nodes 2000 }
418.Ed
419.It Ar set ruleset-optimization
420.Bl -tag -width xxxxxxxx -compact
421.It Ar none
422Disable the ruleset optimizer.
423.It Ar basic
424Enable basic ruleset optimization.
425This is the default behaviour.
426Basic ruleset optimization does four things to improve the
427performance of ruleset evaluations:
428.Pp
429.Bl -enum -compact
430.It
431remove duplicate rules
432.It
433remove rules that are a subset of another rule
434.It
435combine multiple rules into a table when advantageous
436.It
437re-order the rules to improve evaluation performance
438.El
439.Pp
440.It Ar profile
441Uses the currently loaded ruleset as a feedback profile to tailor the
442ordering of quick rules to actual network traffic.
443.El
444.Pp
445It is important to note that the ruleset optimizer will modify the ruleset
446to improve performance.
447A side effect of the ruleset modification is that per-rule accounting
448statistics will have different meanings than before.
449If per-rule accounting is important for billing purposes or whatnot,
450either the ruleset optimizer should not be used or a label field should
451be added to all of the accounting rules to act as optimization barriers.
452.Pp
453Optimization can also be set as a command-line argument to
454.Xr pfctl 8 ,
455overriding the settings in
456.Nm .
457.It Ar set optimization
458Optimize state timeouts for one of the following network environments:
459.Pp
460.Bl -tag -width xxxx -compact
461.It Ar normal
462A normal network environment.
463Suitable for almost all networks.
464.It Ar high-latency
465A high-latency environment (such as a satellite connection).
466.It Ar satellite
467Alias for
468.Ar high-latency .
469.It Ar aggressive
470Aggressively expire connections.
471This can greatly reduce the memory usage of the firewall at the cost of
472dropping idle connections early.
473.It Ar conservative
474Extremely conservative settings.
475Avoid dropping legitimate connections at the
476expense of greater memory utilization (possibly much greater on a busy
477network) and slightly increased processor utilization.
478.El
479.Pp
480For example:
481.Bd -literal -offset indent
482set optimization aggressive
483.Ed
484.It Ar set block-policy
485The
486.Ar block-policy
487option sets the default behaviour for the packet
488.Ar block
489action:
490.Pp
491.Bl -tag -width xxxxxxxx -compact
492.It Ar drop
493Packet is silently dropped.
494.It Ar return
495A TCP RST is returned for blocked TCP packets,
496an ICMP UNREACHABLE is returned for blocked UDP packets,
497and all other packets are silently dropped.
498.El
499.Pp
500For example:
501.Bd -literal -offset indent
502set block-policy return
503.Ed
504.It Ar set fail-policy
505The
506.Ar fail-policy
507option sets the behaviour of rules which should pass a packet but were
508unable to do so.
509This might happen when a nat or route-to rule uses an empty table as list
510of targets or if a rule fails to create state or source node.
511The following
512.Ar block
513actions are possible:
514.Pp
515.Bl -tag -width xxxxxxxx -compact
516.It Ar drop
517Incoming packet is silently dropped.
518.It Ar return
519Incoming packet is dropped and TCP RST is returned for TCP packets,
520an ICMP UNREACHABLE is returned for UDP packets,
521and no response is sent for other packets.
522.El
523.Pp
524For example:
525.Bd -literal -offset indent
526set fail-policy return
527.Ed
528.It Ar set state-policy
529The
530.Ar state-policy
531option sets the default behaviour for states:
532.Pp
533.Bl -tag -width group-bound -compact
534.It Ar if-bound
535States are bound to interface.
536.It Ar floating
537States can match packets on any interfaces (the default).
538.El
539.Pp
540For example:
541.Bd -literal -offset indent
542set state-policy if-bound
543.Ed
544.It Ar set syncookies never | always | adaptive
545When
546.Cm syncookies
547are active, pf will answer each incoming TCP SYN with a syncookie SYNACK,
548without allocating any resources.
549Upon reception of the client's ACK in response to the syncookie
550SYNACK, pf will evaluate the ruleset and create state if the ruleset
551permits it, complete the three way handshake with the target host and
552continue the connection with synproxy in place.
553This allows pf to be resilient against large synflood attacks which would
554run the state table against its limits otherwise.
555Due to the blind answers to every incoming SYN syncookies share the caveats of
556synproxy, namely seemingly accepting connections that will be dropped later on.
557.Pp
558.Bl -tag -width adaptive -compact
559.It Cm never
560pf will never send syncookie SYNACKs (the default).
561.It Cm always
562pf will always send syncookie SYNACKs.
563.It Cm adaptive
564pf will enable syncookie mode when a given percentage of the state table
565is used up by half-open TCP connections, as in, those that saw the initial
566SYN but didn't finish the three way handshake.
567The thresholds for entering and leaving syncookie mode can be specified using
568.Bd -literal -offset indent
569set syncookies adaptive (start 25%, end 12%)
570.Ed
571.El
572.It Ar set state-defaults
573The
574.Ar state-defaults
575option sets the state options for states created from rules
576without an explicit
577.Ar keep state .
578For example:
579.Bd -literal -offset indent
580set state-defaults no-sync
581.Ed
582.It Ar set hostid
583The 32-bit
584.Ar hostid
585identifies this firewall's state table entries to other firewalls
586in a
587.Xr pfsync 4
588failover cluster.
589By default the hostid is set to a pseudo-random value, however it may be
590desirable to manually configure it, for example to more easily identify the
591source of state table entries.
592.Bd -literal -offset indent
593set hostid 1
594.Ed
595.Pp
596The hostid may be specified in either decimal or hexadecimal.
597.It Ar set require-order
598By default
599.Xr pfctl 8
600enforces an ordering of the statement types in the ruleset to:
601.Em options ,
602.Em normalization ,
603.Em queueing ,
604.Em translation ,
605.Em filtering .
606Setting this option to
607.Ar no
608disables this enforcement.
609There may be non-trivial and non-obvious implications to an out of
610order ruleset.
611Consider carefully before disabling the order enforcement.
612.It Ar set fingerprints
613Load fingerprints of known operating systems from the given filename.
614By default fingerprints of known operating systems are automatically
615loaded from
616.Xr pf.os 5
617in
618.Pa /etc
619but can be overridden via this option.
620Setting this option may leave a small period of time where the fingerprints
621referenced by the currently active ruleset are inconsistent until the new
622ruleset finishes loading.
623.Pp
624For example:
625.Pp
626.Dl set fingerprints \&"/etc/pf.os.devel\&"
627.It Ar set skip on Aq Ar ifspec
628List interfaces for which packets should not be filtered.
629Packets passing in or out on such interfaces are passed as if pf was
630disabled, i.e. pf does not process them in any way.
631This can be useful on loopback and other virtual interfaces, when
632packet filtering is not desired and can have unexpected effects.
633For example:
634.Pp
635.Dl set skip on lo0
636.It Ar set debug
637Set the debug
638.Ar level
639to one of the following:
640.Pp
641.Bl -tag -width xxxxxxxxxxxx -compact
642.It Ar none
643Don't generate debug messages.
644.It Ar urgent
645Generate debug messages only for serious errors.
646.It Ar misc
647Generate debug messages for various errors.
648.It Ar loud
649Generate debug messages for common conditions.
650.El
651.It Ar set keepcounters
652Preserve rule counters across rule updates.
653Usually rule counters are reset to zero on every update of the ruleset.
654With
655.Ar keepcounters
656set pf will attempt to find matching rules between old and new rulesets
657and preserve the rule counters.
658.El
659.Sh ETHERNET FILTERING
660.Xr pf 4
661has the ability to
662.Ar block
663and
664.Ar pass
665packets based on attributes of their Ethernet (layer 2) header.
666.Pp
667For each packet processed by the packet filter, the filter rules are
668evaluated in sequential order, from first to last.
669The last matching rule decides what action is taken.
670If no rule matches the packet, the default action is to pass
671the packet.
672.Pp
673The folliwing actions can be used in the filter:
674.Bl -tag -width xxxx
675.It Ar block
676The packet is blocked.
677Unlike for layer 3 traffic the packet is always silently dropped.
678.It Ar pass
679The packet is passed;
680no state is created for layer 2 traffic.
681.El
682.Sh PARAMETERS
683The rule parameters specify the packets to which a rule applies.
684A packet always comes in on, or goes out through, one interface.
685Most parameters are optional.
686If a parameter is specified, the rule only applies to packets with
687matching attributes.
688Certain parameters can be expressed as lists, in which case
689.Xr pfctl 8
690generates all needed rule combinations.
691.Bl -tag -width xxxx
692.It Ar in No or Ar out
693This rule applies to incoming or outgoing packets.
694If neither
695.Ar in
696nor
697.Ar out
698are specified, the rule will match packets in both directions.
699.It Ar quick
700If a packet matches a rule which has the
701.Ar quick
702option set, this rule
703is considered the last matching rule, and evaluation of subsequent rules
704is skipped.
705.It Ar on Aq Ar interface
706This rule applies only to packets coming in on, or going out through, this
707particular interface or interface group.
708For more information on interface groups,
709see the
710.Ic group
711keyword in
712.Xr ifconfig 8 .
713.It Ar proto Aq Ar protocol
714This rule applies only to packets of this protocol.
715Note that Ethernet protocol numbers are different from those used in
716.Xr ip 4
717and
718.Xr ip6 4 .
719.It Xo
720.Ar from Aq Ar source
721.Ar to Aq Ar dest
722.Xc
723This rule applies only to packets with the specified source and destination
724MAC addresses.
725.It Xo Ar queue Aq Ar queue
726.Xc
727Packets matching this rule will be assigned to the specified queue.
728See
729.Sx QUEUEING
730for setup details.
731.Pp
732.It Ar tag Aq Ar string
733Packets matching this rule will be tagged with the
734specified string.
735The tag acts as an internal marker that can be used to
736identify these packets later on.
737This can be used, for example, to provide trust between
738interfaces and to determine if packets have been
739processed by translation rules.
740Tags are
741.Qq sticky ,
742meaning that the packet will be tagged even if the rule
743is not the last matching rule.
744Further matching rules can replace the tag with a
745new one but will not remove a previously applied tag.
746A packet is only ever assigned one tag at a time.
747.It Ar tagged Aq Ar string
748Used to specify that packets must already be tagged with the given tag in order
749to match the rule.
750Inverse tag matching can also be done by specifying the !  operator before the
751tagged keyword.
752.Sh TRAFFIC NORMALIZATION
753Traffic normalization is used to sanitize packet content in such
754a way that there are no ambiguities in packet interpretation on
755the receiving side.
756The normalizer does IP fragment reassembly to prevent attacks
757that confuse intrusion detection systems by sending overlapping
758IP fragments.
759Packet normalization is invoked with the
760.Ar scrub
761directive.
762.Pp
763.Ar scrub
764has the following options:
765.Bl -tag -width xxxx
766.It Ar no-df
767Clears the
768.Ar dont-fragment
769bit from a matching IP packet.
770Some operating systems are known to generate fragmented packets with the
771.Ar dont-fragment
772bit set.
773This is particularly true with NFS.
774.Ar Scrub
775will drop such fragmented
776.Ar dont-fragment
777packets unless
778.Ar no-df
779is specified.
780.Pp
781Unfortunately some operating systems also generate their
782.Ar dont-fragment
783packets with a zero IP identification field.
784Clearing the
785.Ar dont-fragment
786bit on packets with a zero IP ID may cause deleterious results if an
787upstream router later fragments the packet.
788Using the
789.Ar random-id
790modifier (see below) is recommended in combination with the
791.Ar no-df
792modifier to ensure unique IP identifiers.
793.It Ar min-ttl Aq Ar number
794Enforces a minimum TTL for matching IP packets.
795.It Ar max-mss Aq Ar number
796Enforces a maximum MSS for matching TCP packets.
797.It Xo Ar set-tos Aq Ar string
798.No \*(Ba Aq Ar number
799.Xc
800Enforces a
801.Em TOS
802for matching IP packets.
803.Em TOS
804may be
805given as one of
806.Ar critical ,
807.Ar inetcontrol ,
808.Ar lowdelay ,
809.Ar netcontrol ,
810.Ar throughput ,
811.Ar reliability ,
812or one of the DiffServ Code Points:
813.Ar ef ,
814.Ar va ,
815.Ar af11 No ... Ar af43 ,
816.Ar cs0 No ... Ar cs7 ;
817or as either hex or decimal.
818.It Ar random-id
819Replaces the IP identification field with random values to compensate
820for predictable values generated by many hosts.
821This option only applies to packets that are not fragmented
822after the optional fragment reassembly.
823.It Ar fragment reassemble
824Using
825.Ar scrub
826rules, fragments can be reassembled by normalization.
827In this case, fragments are buffered until they form a complete
828packet, and only the completed packet is passed on to the filter.
829The advantage is that filter rules have to deal only with complete
830packets, and can ignore fragments.
831The drawback of caching fragments is the additional memory cost.
832.It Ar reassemble tcp
833Statefully normalizes TCP connections.
834.Ar scrub reassemble tcp
835rules may not have the direction (in/out) specified.
836.Ar reassemble tcp
837performs the following normalizations:
838.Pp
839.Bl -tag -width timeout -compact
840.It ttl
841Neither side of the connection is allowed to reduce their IP TTL.
842An attacker may send a packet such that it reaches the firewall, affects
843the firewall state, and expires before reaching the destination host.
844.Ar reassemble tcp
845will raise the TTL of all packets back up to the highest value seen on
846the connection.
847.It timestamp modulation
848Modern TCP stacks will send a timestamp on every TCP packet and echo
849the other endpoint's timestamp back to them.
850Many operating systems will merely start the timestamp at zero when
851first booted, and increment it several times a second.
852The uptime of the host can be deduced by reading the timestamp and multiplying
853by a constant.
854Also observing several different timestamps can be used to count hosts
855behind a NAT device.
856And spoofing TCP packets into a connection requires knowing or guessing
857valid timestamps.
858Timestamps merely need to be monotonically increasing and not derived off a
859guessable base time.
860.Ar reassemble tcp
861will cause
862.Ar scrub
863to modulate the TCP timestamps with a random number.
864.It extended PAWS checks
865There is a problem with TCP on long fat pipes, in that a packet might get
866delayed for longer than it takes the connection to wrap its 32-bit sequence
867space.
868In such an occurrence, the old packet would be indistinguishable from a
869new packet and would be accepted as such.
870The solution to this is called PAWS: Protection Against Wrapped Sequence
871numbers.
872It protects against it by making sure the timestamp on each packet does
873not go backwards.
874.Ar reassemble tcp
875also makes sure the timestamp on the packet does not go forward more
876than the RFC allows.
877By doing this,
878.Xr pf 4
879artificially extends the security of TCP sequence numbers by 10 to 18
880bits when the host uses appropriately randomized timestamps, since a
881blind attacker would have to guess the timestamp as well.
882.El
883.El
884.Pp
885For example,
886.Bd -literal -offset indent
887scrub in on $ext_if all fragment reassemble
888.Ed
889.Pp
890The
891.Ar no
892option prefixed to a scrub rule causes matching packets to remain unscrubbed,
893much in the same way as
894.Ar drop quick
895works in the packet filter (see below).
896This mechanism should be used when it is necessary to exclude specific packets
897from broader scrub rules.
898.Sh QUEUEING with ALTQ
899The ALTQ system is currently not available in the GENERIC kernel nor as
900loadable modules.
901In order to use the herein after called queueing options one has to use a
902custom built kernel.
903Please refer to
904.Xr altq 4
905to learn about the related kernel options.
906.Pp
907Packets can be assigned to queues for the purpose of bandwidth
908control.
909At least two declarations are required to configure queues, and later
910any packet filtering rule can reference the defined queues by name.
911During the filtering component of
912.Nm pf.conf ,
913the last referenced
914.Ar queue
915name is where any packets from
916.Ar pass
917rules will be queued, while for
918.Ar block
919rules it specifies where any resulting ICMP or TCP RST
920packets should be queued.
921The
922.Ar scheduler
923defines the algorithm used to decide which packets get delayed, dropped, or
924sent out immediately.
925There are three
926.Ar schedulers
927currently supported.
928.Bl -tag -width xxxx
929.It Ar cbq
930Class Based Queueing.
931.Ar Queues
932attached to an interface build a tree, thus each
933.Ar queue
934can have further child
935.Ar queues .
936Each queue can have a
937.Ar priority
938and a
939.Ar bandwidth
940assigned.
941.Ar Priority
942mainly controls the time packets take to get sent out, while
943.Ar bandwidth
944has primarily effects on throughput.
945.Ar cbq
946achieves both partitioning and sharing of link bandwidth
947by hierarchically structured classes.
948Each class has its own
949.Ar queue
950and is assigned its share of
951.Ar bandwidth .
952A child class can borrow bandwidth from its parent class
953as long as excess bandwidth is available
954(see the option
955.Ar borrow ,
956below).
957.It Ar priq
958Priority Queueing.
959.Ar Queues
960are flat attached to the interface, thus,
961.Ar queues
962cannot have further child
963.Ar queues .
964Each
965.Ar queue
966has a unique
967.Ar priority
968assigned, ranging from 0 to 15.
969Packets in the
970.Ar queue
971with the highest
972.Ar priority
973are processed first.
974.It Ar hfsc
975Hierarchical Fair Service Curve.
976.Ar Queues
977attached to an interface build a tree, thus each
978.Ar queue
979can have further child
980.Ar queues .
981Each queue can have a
982.Ar priority
983and a
984.Ar bandwidth
985assigned.
986.Ar Priority
987mainly controls the time packets take to get sent out, while
988.Ar bandwidth
989primarily affects throughput.
990.Ar hfsc
991supports both link-sharing and guaranteed real-time services.
992It employs a service curve based QoS model,
993and its unique feature is an ability to decouple
994.Ar delay
995and
996.Ar bandwidth
997allocation.
998.El
999.Pp
1000The interfaces on which queueing should be activated are declared using
1001the
1002.Ar altq on
1003declaration.
1004.Ar altq on
1005has the following keywords:
1006.Bl -tag -width xxxx
1007.It Aq Ar interface
1008Queueing is enabled on the named interface.
1009.It Aq Ar scheduler
1010Specifies which queueing scheduler to use.
1011Currently supported values
1012are
1013.Ar cbq
1014for Class Based Queueing,
1015.Ar priq
1016for Priority Queueing and
1017.Ar hfsc
1018for the Hierarchical Fair Service Curve scheduler.
1019.It Ar bandwidth Aq Ar bw
1020The maximum bitrate for all queues on an
1021interface may be specified using the
1022.Ar bandwidth
1023keyword.
1024The value can be specified as an absolute value or as a
1025percentage of the interface bandwidth.
1026When using an absolute value, the suffixes
1027.Ar b ,
1028.Ar Kb ,
1029.Ar Mb ,
1030and
1031.Ar Gb
1032are used to represent bits, kilobits, megabits, and
1033gigabits per second, respectively.
1034The value must not exceed the interface bandwidth.
1035If
1036.Ar bandwidth
1037is not specified, the interface bandwidth is used
1038(but take note that some interfaces do not know their bandwidth,
1039or can adapt their bandwidth rates).
1040.It Ar qlimit Aq Ar limit
1041The maximum number of packets held in the queue.
1042The default is 50.
1043.It Ar tbrsize Aq Ar size
1044Adjusts the size, in bytes, of the token bucket regulator.
1045If not specified, heuristics based on the
1046interface bandwidth are used to determine the size.
1047.It Ar queue Aq Ar list
1048Defines a list of subqueues to create on an interface.
1049.El
1050.Pp
1051In the following example, the interface dc0
1052should queue up to 5Mbps in four second-level queues using
1053Class Based Queueing.
1054Those four queues will be shown in a later example.
1055.Bd -literal -offset indent
1056altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh }
1057.Ed
1058.Pp
1059Once interfaces are activated for queueing using the
1060.Ar altq
1061directive, a sequence of
1062.Ar queue
1063directives may be defined.
1064The name associated with a
1065.Ar queue
1066must match a queue defined in the
1067.Ar altq
1068directive (e.g. mail), or, except for the
1069.Ar priq
1070.Ar scheduler ,
1071in a parent
1072.Ar queue
1073declaration.
1074The following keywords can be used:
1075.Bl -tag -width xxxx
1076.It Ar on Aq Ar interface
1077Specifies the interface the queue operates on.
1078If not given, it operates on all matching interfaces.
1079.It Ar bandwidth Aq Ar bw
1080Specifies the maximum bitrate to be processed by the queue.
1081This value must not exceed the value of the parent
1082.Ar queue
1083and can be specified as an absolute value or a percentage of the parent
1084queue's bandwidth.
1085If not specified, defaults to 100% of the parent queue's bandwidth.
1086The
1087.Ar priq
1088scheduler does not support bandwidth specification.
1089.It Ar priority Aq Ar level
1090Between queues a priority level can be set.
1091For
1092.Ar cbq
1093and
1094.Ar hfsc ,
1095the range is 0 to 7 and for
1096.Ar priq ,
1097the range is 0 to 15.
1098The default for all is 1.
1099.Ar Priq
1100queues with a higher priority are always served first.
1101.Ar Cbq
1102and
1103.Ar Hfsc
1104queues with a higher priority are preferred in the case of overload.
1105.It Ar qlimit Aq Ar limit
1106The maximum number of packets held in the queue.
1107The default is 50.
1108.El
1109.Pp
1110The
1111.Ar scheduler
1112can get additional parameters with
1113.Xo Aq Ar scheduler
1114.Pf ( Aq Ar parameters ) .
1115.Xc
1116Parameters are as follows:
1117.Bl -tag -width Fl
1118.It Ar default
1119Packets not matched by another queue are assigned to this one.
1120Exactly one default queue is required.
1121.It Ar red
1122Enable RED (Random Early Detection) on this queue.
1123RED drops packets with a probability proportional to the average
1124queue length.
1125.It Ar rio
1126Enables RIO on this queue.
1127RIO is RED with IN/OUT, thus running
1128RED two times more than RIO would achieve the same effect.
1129RIO is currently not supported in the GENERIC kernel.
1130.It Ar ecn
1131Enables ECN (Explicit Congestion Notification) on this queue.
1132ECN implies RED.
1133.El
1134.Pp
1135The
1136.Ar cbq
1137.Ar scheduler
1138supports an additional option:
1139.Bl -tag -width Fl
1140.It Ar borrow
1141The queue can borrow bandwidth from the parent.
1142.El
1143.Pp
1144The
1145.Ar hfsc
1146.Ar scheduler
1147supports some additional options:
1148.Bl -tag -width Fl
1149.It Ar realtime Aq Ar sc
1150The minimum required bandwidth for the queue.
1151.It Ar upperlimit Aq Ar sc
1152The maximum allowed bandwidth for the queue.
1153.It Ar linkshare Aq Ar sc
1154The bandwidth share of a backlogged queue.
1155.El
1156.Pp
1157.Aq Ar sc
1158is an acronym for
1159.Ar service curve .
1160.Pp
1161The format for service curve specifications is
1162.Ar ( m1 , d , m2 ) .
1163.Ar m2
1164controls the bandwidth assigned to the queue.
1165.Ar m1
1166and
1167.Ar d
1168are optional and can be used to control the initial bandwidth assignment.
1169For the first
1170.Ar d
1171milliseconds the queue gets the bandwidth given as
1172.Ar m1 ,
1173afterwards the value given in
1174.Ar m2 .
1175.Pp
1176Furthermore, with
1177.Ar cbq
1178and
1179.Ar hfsc ,
1180child queues can be specified as in an
1181.Ar altq
1182declaration, thus building a tree of queues using a part of
1183their parent's bandwidth.
1184.Pp
1185Packets can be assigned to queues based on filter rules by using the
1186.Ar queue
1187keyword.
1188Normally only one
1189.Ar queue
1190is specified; when a second one is specified it will instead be used for
1191packets which have a
1192.Em TOS
1193of
1194.Em lowdelay
1195and for TCP ACKs with no data payload.
1196.Pp
1197To continue the previous example, the examples below would specify the
1198four referenced
1199queues, plus a few child queues.
1200Interactive
1201.Xr ssh 1
1202sessions get priority over bulk transfers like
1203.Xr scp 1
1204and
1205.Xr sftp 1 .
1206The queues may then be referenced by filtering rules (see
1207.Sx PACKET FILTERING
1208below).
1209.Bd -literal
1210queue std bandwidth 10% cbq(default)
1211queue http bandwidth 60% priority 2 cbq(borrow red) \e
1212      { employees, developers }
1213queue  developers bandwidth 75% cbq(borrow)
1214queue  employees bandwidth 15%
1215queue mail bandwidth 10% priority 0 cbq(borrow ecn)
1216queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk }
1217queue  ssh_interactive bandwidth 50% priority 7 cbq(borrow)
1218queue  ssh_bulk bandwidth 50% priority 0 cbq(borrow)
1219
1220block return out on dc0 inet all queue std
1221pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e
1222      queue developers
1223pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e
1224      queue employees
1225pass out on dc0 inet proto tcp from any to any port 22 \e
1226      queue(ssh_bulk, ssh_interactive)
1227pass out on dc0 inet proto tcp from any to any port 25 \e
1228      queue mail
1229.Ed
1230.Sh QUEUEING with dummynet
1231Queueing can also be done with
1232.Xr dummynet 4 .
1233Queues and pipes can be created with
1234.Xr dnctl 8 .
1235.Pp
1236Packets can be assigned to queues and pipes using
1237.Ar dnqueue
1238and
1239.Ar dnpipe
1240respectively.
1241.Pp
1242Both
1243.Ar dnqueue
1244and
1245.Ar dnpipe
1246take either a single pipe or queue number or two numbers as arguments.
1247The first pipe or queue number will be used to shape the traffic in the rule
1248direction, the second will be used to shape the traffic in the reverse
1249direction.
1250If the rule does not specify a direction the first packet to create state will
1251be shaped according to the first number, and the response traffic according to
1252the second.
1253.Pp
1254If the
1255.Xr dummynet 4
1256module is not loaded any traffic sent into a queue or pipe will be dropped.
1257.Sh TRANSLATION
1258Translation rules modify either the source or destination address of the
1259packets associated with a stateful connection.
1260A stateful connection is automatically created to track packets matching
1261such a rule as long as they are not blocked by the filtering section of
1262.Nm pf.conf .
1263The translation engine modifies the specified address and/or port in the
1264packet, recalculates IP, TCP and UDP checksums as necessary, and passes it to
1265the packet filter for evaluation.
1266.Pp
1267Since translation occurs before filtering the filter
1268engine will see packets as they look after any
1269addresses and ports have been translated.
1270Filter rules will therefore have to filter based on the translated
1271address and port number.
1272Packets that match a translation rule are only automatically passed if
1273the
1274.Ar pass
1275modifier is given, otherwise they are
1276still subject to
1277.Ar block
1278and
1279.Ar pass
1280rules.
1281.Pp
1282The state entry created permits
1283.Xr pf 4
1284to keep track of the original address for traffic associated with that state
1285and correctly direct return traffic for that connection.
1286.Pp
1287Various types of translation are possible with pf:
1288.Bl -tag -width xxxx
1289.It Ar binat
1290A
1291.Ar binat
1292rule specifies a bidirectional mapping between an external IP netblock
1293and an internal IP netblock.
1294.It Ar nat
1295A
1296.Ar nat
1297rule specifies that IP addresses are to be changed as the packet
1298traverses the given interface.
1299This technique allows one or more IP addresses
1300on the translating host to support network traffic for a larger range of
1301machines on an "inside" network.
1302Although in theory any IP address can be used on the inside, it is strongly
1303recommended that one of the address ranges defined by RFC 1918 be used.
1304These netblocks are:
1305.Bd -literal
130610.0.0.0 - 10.255.255.255 (all of net 10, i.e., 10/8)
1307172.16.0.0 - 172.31.255.255 (i.e., 172.16/12)
1308192.168.0.0 - 192.168.255.255 (i.e., 192.168/16)
1309.Ed
1310.It Pa rdr
1311The packet is redirected to another destination and possibly a
1312different port.
1313.Ar rdr
1314rules can optionally specify port ranges instead of single ports.
1315rdr ... port 2000:2999 -\*(Gt ... port 4000
1316redirects ports 2000 to 2999 (inclusive) to port 4000.
1317rdr ... port 2000:2999 -\*(Gt ... port 4000:*
1318redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999.
1319.El
1320.Pp
1321In addition to modifying the address, some translation rules may modify
1322source or destination ports for
1323.Xr tcp 4
1324or
1325.Xr udp 4
1326connections; implicitly in the case of
1327.Ar nat
1328rules and explicitly in the case of
1329.Ar rdr
1330rules.
1331Port numbers are never translated with a
1332.Ar binat
1333rule.
1334.Pp
1335Evaluation order of the translation rules is dependent on the type
1336of the translation rules and of the direction of a packet.
1337.Ar binat
1338rules are always evaluated first.
1339Then either the
1340.Ar rdr
1341rules are evaluated on an inbound packet or the
1342.Ar nat
1343rules on an outbound packet.
1344Rules of the same type are evaluated in the same order in which they
1345appear in the ruleset.
1346The first matching rule decides what action is taken.
1347.Pp
1348The
1349.Ar no
1350option prefixed to a translation rule causes packets to remain untranslated,
1351much in the same way as
1352.Ar drop quick
1353works in the packet filter (see below).
1354If no rule matches the packet it is passed to the filter engine unmodified.
1355.Pp
1356Translation rules apply only to packets that pass through
1357the specified interface, and if no interface is specified,
1358translation is applied to packets on all interfaces.
1359For instance, redirecting port 80 on an external interface to an internal
1360web server will only work for connections originating from the outside.
1361Connections to the address of the external interface from local hosts will
1362not be redirected, since such packets do not actually pass through the
1363external interface.
1364Redirections cannot reflect packets back through the interface they arrive
1365on, they can only be redirected to hosts connected to different interfaces
1366or to the firewall itself.
1367.Pp
1368Note that redirecting external incoming connections to the loopback
1369address, as in
1370.Bd -literal -offset indent
1371rdr on ne3 inet proto tcp to port smtp -\*(Gt 127.0.0.1 port spamd
1372.Ed
1373.Pp
1374will effectively allow an external host to connect to daemons
1375bound solely to the loopback address, circumventing the traditional
1376blocking of such connections on a real interface.
1377Unless this effect is desired, any of the local non-loopback addresses
1378should be used as redirection target instead, which allows external
1379connections only to daemons bound to this address or not bound to
1380any address.
1381.Pp
1382See
1383.Sx TRANSLATION EXAMPLES
1384below.
1385.Sh PACKET FILTERING
1386.Xr pf 4
1387has the ability to
1388.Ar block
1389,
1390.Ar pass
1391and
1392.Ar match
1393packets based on attributes of their layer 3 (see
1394.Xr ip 4
1395and
1396.Xr ip6 4 )
1397and layer 4 (see
1398.Xr icmp 4 ,
1399.Xr icmp6 4 ,
1400.Xr tcp 4 ,
1401.Xr udp 4 )
1402headers.
1403In addition, packets may also be
1404assigned to queues for the purpose of bandwidth control.
1405.Pp
1406For each packet processed by the packet filter, the filter rules are
1407evaluated in sequential order, from first to last.
1408For
1409.Ar block
1410and
1411.Ar pass
1412, the last matching rule decides what action is taken.
1413For
1414.Ar match
1415, rules are evaulated every time they match; the pass/block state of a packet
1416remains unchanged.
1417If no rule matches the packet, the default action is to pass
1418the packet.
1419.Pp
1420The following actions can be used in the filter:
1421.Bl -tag -width xxxx
1422.It Ar block
1423The packet is blocked.
1424There are a number of ways in which a
1425.Ar block
1426rule can behave when blocking a packet.
1427The default behaviour is to
1428.Ar drop
1429packets silently, however this can be overridden or made
1430explicit either globally, by setting the
1431.Ar block-policy
1432option, or on a per-rule basis with one of the following options:
1433.Pp
1434.Bl -tag -width xxxx -compact
1435.It Ar drop
1436The packet is silently dropped.
1437.It Ar return-rst
1438This applies only to
1439.Xr tcp 4
1440packets, and issues a TCP RST which closes the
1441connection.
1442.It Ar return-icmp
1443.It Ar return-icmp6
1444This causes ICMP messages to be returned for packets which match the rule.
1445By default this is an ICMP UNREACHABLE message, however this
1446can be overridden by specifying a message as a code or number.
1447.It Ar return
1448This causes a TCP RST to be returned for
1449.Xr tcp 4
1450packets and an ICMP UNREACHABLE for UDP and other packets.
1451.El
1452.Pp
1453Options returning ICMP packets currently have no effect if
1454.Xr pf 4
1455operates on a
1456.Xr if_bridge 4 ,
1457as the code to support this feature has not yet been implemented.
1458.Pp
1459The simplest mechanism to block everything by default and only pass
1460packets that match explicit rules is specify a first filter rule of:
1461.Bd -literal -offset indent
1462block all
1463.Ed
1464.It Ar match
1465The packet is matched.
1466This mechanism is used to provide fine grained filtering without altering the
1467block/pass state of a packet.
1468.Ar match
1469rules differ from
1470.Ar block
1471and
1472.Ar pass
1473rules in that parameters are set every time a packet matches the rule, not only
1474on the last matching rule.
1475For the following parameters, this means that the parameter effectively becomes
1476"sticky" until explicitly overridden:
1477.Ar queue ,
1478.Ar dnpipe ,
1479.Ar dnqueue
1480.
1481.It Ar pass
1482The packet is passed;
1483state is created unless the
1484.Ar no state
1485option is specified.
1486.El
1487.Pp
1488By default
1489.Xr pf 4
1490filters packets statefully; the first time a packet matches a
1491.Ar pass
1492rule, a state entry is created; for subsequent packets the filter checks
1493whether the packet matches any state.
1494If it does, the packet is passed without evaluation of any rules.
1495After the connection is closed or times out, the state entry is automatically
1496removed.
1497.Pp
1498This has several advantages.
1499For TCP connections, comparing a packet to a state involves checking
1500its sequence numbers, as well as TCP timestamps if a
1501.Ar scrub reassemble tcp
1502rule applies to the connection.
1503If these values are outside the narrow windows of expected
1504values, the packet is dropped.
1505This prevents spoofing attacks, such as when an attacker sends packets with
1506a fake source address/port but does not know the connection's sequence
1507numbers.
1508Similarly,
1509.Xr pf 4
1510knows how to match ICMP replies to states.
1511For example,
1512.Bd -literal -offset indent
1513pass out inet proto icmp all icmp-type echoreq
1514.Ed
1515.Pp
1516allows echo requests (such as those created by
1517.Xr ping 8 )
1518out statefully, and matches incoming echo replies correctly to states.
1519.Pp
1520Also, looking up states is usually faster than evaluating rules.
1521If there are 50 rules, all of them are evaluated sequentially in O(n).
1522Even with 50000 states, only 16 comparisons are needed to match a
1523state, since states are stored in a binary search tree that allows
1524searches in O(log2 n).
1525.Pp
1526Furthermore, correct handling of ICMP error messages is critical to
1527many protocols, particularly TCP.
1528.Xr pf 4
1529matches ICMP error messages to the correct connection, checks them against
1530connection parameters, and passes them if appropriate.
1531For example if an ICMP source quench message referring to a stateful TCP
1532connection arrives, it will be matched to the state and get passed.
1533.Pp
1534Finally, state tracking is required for
1535.Ar nat , binat No and Ar rdr
1536rules, in order to track address and port translations and reverse the
1537translation on returning packets.
1538.Pp
1539.Xr pf 4
1540will also create state for other protocols which are effectively stateless by
1541nature.
1542UDP packets are matched to states using only host addresses and ports,
1543and other protocols are matched to states using only the host addresses.
1544.Pp
1545If stateless filtering of individual packets is desired,
1546the
1547.Ar no state
1548keyword can be used to specify that state will not be created
1549if this is the last matching rule.
1550A number of parameters can also be set to affect how
1551.Xr pf 4
1552handles state tracking.
1553See
1554.Sx STATEFUL TRACKING OPTIONS
1555below for further details.
1556.Sh PARAMETERS
1557The rule parameters specify the packets to which a rule applies.
1558A packet always comes in on, or goes out through, one interface.
1559Most parameters are optional.
1560If a parameter is specified, the rule only applies to packets with
1561matching attributes.
1562Certain parameters can be expressed as lists, in which case
1563.Xr pfctl 8
1564generates all needed rule combinations.
1565.Bl -tag -width xxxx
1566.It Ar in No or Ar out
1567This rule applies to incoming or outgoing packets.
1568If neither
1569.Ar in
1570nor
1571.Ar out
1572are specified, the rule will match packets in both directions.
1573.It Ar log
1574In addition to the action specified, a log message is generated.
1575Only the packet that establishes the state is logged,
1576unless the
1577.Ar no state
1578option is specified.
1579The logged packets are sent to a
1580.Xr pflog 4
1581interface, by default
1582.Ar pflog0 .
1583This interface is monitored by the
1584.Xr pflogd 8
1585logging daemon, which dumps the logged packets to the file
1586.Pa /var/log/pflog
1587in
1588.Xr pcap 3
1589binary format.
1590.It Ar log (all)
1591Used to force logging of all packets for a connection.
1592This is not necessary when
1593.Ar no state
1594is explicitly specified.
1595As with
1596.Ar log ,
1597packets are logged to
1598.Xr pflog 4 .
1599.It Ar log (user)
1600Logs the
1601.Ux
1602user ID of the user that owns the socket and the PID of the process that
1603has the socket open where the packet is sourced from or destined to
1604(depending on which socket is local).
1605This is in addition to the normal information logged.
1606.Pp
1607Only the first packet
1608logged via
1609.Ar log (all, user)
1610will have the user credentials logged when using stateful matching.
1611.It Ar log (to Aq Ar interface )
1612Send logs to the specified
1613.Xr pflog 4
1614interface instead of
1615.Ar pflog0 .
1616.It Ar quick
1617If a packet matches a rule which has the
1618.Ar quick
1619option set, this rule
1620is considered the last matching rule, and evaluation of subsequent rules
1621is skipped.
1622.It Ar on Aq Ar interface
1623This rule applies only to packets coming in on, or going out through, this
1624particular interface or interface group.
1625For more information on interface groups,
1626see the
1627.Ic group
1628keyword in
1629.Xr ifconfig 8 .
1630.It Aq Ar af
1631This rule applies only to packets of this address family.
1632Supported values are
1633.Ar inet
1634and
1635.Ar inet6 .
1636.It Ar proto Aq Ar protocol
1637This rule applies only to packets of this protocol.
1638Common protocols are
1639.Xr icmp 4 ,
1640.Xr icmp6 4 ,
1641.Xr tcp 4 ,
1642and
1643.Xr udp 4 .
1644For a list of all the protocol name to number mappings used by
1645.Xr pfctl 8 ,
1646see the file
1647.Pa /etc/protocols .
1648.It Xo
1649.Ar from Aq Ar source
1650.Ar port Aq Ar source
1651.Ar os Aq Ar source
1652.Ar to Aq Ar dest
1653.Ar port Aq Ar dest
1654.Xc
1655This rule applies only to packets with the specified source and destination
1656addresses and ports.
1657.Pp
1658Addresses can be specified in CIDR notation (matching netblocks), as
1659symbolic host names, interface names or interface group names, or as any
1660of the following keywords:
1661.Pp
1662.Bl -tag -width xxxxxxxxxxxxxx -compact
1663.It Ar any
1664Any address.
1665.It Ar no-route
1666Any address which is not currently routable.
1667.It Ar urpf-failed
1668Any source address that fails a unicast reverse path forwarding (URPF)
1669check, i.e. packets coming in on an interface other than that which holds
1670the route back to the packet's source address.
1671.It Aq Ar table
1672Any address that matches the given table.
1673.El
1674.Pp
1675Ranges of addresses are specified by using the
1676.Sq -
1677operator.
1678For instance:
1679.Dq 10.1.1.10 - 10.1.1.12
1680means all addresses from 10.1.1.10 to 10.1.1.12,
1681hence addresses 10.1.1.10, 10.1.1.11, and 10.1.1.12.
1682.Pp
1683Interface names and interface group names can have modifiers appended:
1684.Pp
1685.Bl -tag -width xxxxxxxxxxxx -compact
1686.It Ar :network
1687Translates to the network(s) attached to the interface.
1688.It Ar :broadcast
1689Translates to the interface's broadcast address(es).
1690.It Ar :peer
1691Translates to the point-to-point interface's peer address(es).
1692.It Ar :0
1693Do not include interface aliases.
1694.El
1695.Pp
1696Host names may also have the
1697.Ar :0
1698option appended to restrict the name resolution to the first of each
1699v4 and non-link-local v6 address found.
1700.Pp
1701Host name resolution and interface to address translation are done at
1702ruleset load-time.
1703When the address of an interface (or host name) changes (under DHCP or PPP,
1704for instance), the ruleset must be reloaded for the change to be reflected
1705in the kernel.
1706Surrounding the interface name (and optional modifiers) in parentheses
1707changes this behaviour.
1708When the interface name is surrounded by parentheses, the rule is
1709automatically updated whenever the interface changes its address.
1710The ruleset does not need to be reloaded.
1711This is especially useful with
1712.Ar nat .
1713.Pp
1714Ports can be specified either by number or by name.
1715For example, port 80 can be specified as
1716.Em www .
1717For a list of all port name to number mappings used by
1718.Xr pfctl 8 ,
1719see the file
1720.Pa /etc/services .
1721.Pp
1722Ports and ranges of ports are specified by using these operators:
1723.Bd -literal -offset indent
1724=	(equal)
1725!=	(unequal)
1726\*(Lt	(less than)
1727\*(Le	(less than or equal)
1728\*(Gt	(greater than)
1729\*(Ge	(greater than or equal)
1730:	(range including boundaries)
1731\*(Gt\*(Lt	(range excluding boundaries)
1732\*(Lt\*(Gt	(except range)
1733.Ed
1734.Pp
1735.Sq \*(Gt\*(Lt ,
1736.Sq \*(Lt\*(Gt
1737and
1738.Sq \&:
1739are binary operators (they take two arguments).
1740For instance:
1741.Bl -tag -width Fl
1742.It Ar port 2000:2004
1743means
1744.Sq all ports \*(Ge 2000 and \*(Le 2004 ,
1745hence ports 2000, 2001, 2002, 2003 and 2004.
1746.It Ar port 2000 \*(Gt\*(Lt 2004
1747means
1748.Sq all ports \*(Gt 2000 and \*(Lt 2004 ,
1749hence ports 2001, 2002 and 2003.
1750.It Ar port 2000 \*(Lt\*(Gt 2004
1751means
1752.Sq all ports \*(Lt 2000 or \*(Gt 2004 ,
1753hence ports 1-1999 and 2005-65535.
1754.El
1755.Pp
1756The operating system of the source host can be specified in the case of TCP
1757rules with the
1758.Ar OS
1759modifier.
1760See the
1761.Sx OPERATING SYSTEM FINGERPRINTING
1762section for more information.
1763.Pp
1764The host, port and OS specifications are optional, as in the following examples:
1765.Bd -literal -offset indent
1766pass in all
1767pass in from any to any
1768pass in proto tcp from any port \*(Le 1024 to any
1769pass in proto tcp from any to any port 25
1770pass in proto tcp from 10.0.0.0/8 port \*(Gt 1024 \e
1771      to ! 10.1.2.3 port != ssh
1772pass in proto tcp from any os "OpenBSD"
1773.Ed
1774.It Ar all
1775This is equivalent to "from any to any".
1776.It Ar group Aq Ar group
1777Similar to
1778.Ar user ,
1779this rule only applies to packets of sockets owned by the specified group.
1780.It Ar user Aq Ar user
1781This rule only applies to packets of sockets owned by the specified user.
1782For outgoing connections initiated from the firewall, this is the user
1783that opened the connection.
1784For incoming connections to the firewall itself, this is the user that
1785listens on the destination port.
1786For forwarded connections, where the firewall is not a connection endpoint,
1787the user and group are
1788.Em unknown .
1789.Pp
1790All packets, both outgoing and incoming, of one connection are associated
1791with the same user and group.
1792Only TCP and UDP packets can be associated with users; for other protocols
1793these parameters are ignored.
1794.Pp
1795User and group refer to the effective (as opposed to the real) IDs, in
1796case the socket is created by a setuid/setgid process.
1797User and group IDs are stored when a socket is created;
1798when a process creates a listening socket as root (for instance, by
1799binding to a privileged port) and subsequently changes to another
1800user ID (to drop privileges), the credentials will remain root.
1801.Pp
1802User and group IDs can be specified as either numbers or names.
1803The syntax is similar to the one for ports.
1804The value
1805.Em unknown
1806matches packets of forwarded connections.
1807.Em unknown
1808can only be used with the operators
1809.Cm =
1810and
1811.Cm != .
1812Other constructs like
1813.Cm user \*(Ge unknown
1814are invalid.
1815Forwarded packets with unknown user and group ID match only rules
1816that explicitly compare against
1817.Em unknown
1818with the operators
1819.Cm =
1820or
1821.Cm != .
1822For instance
1823.Cm user \*(Ge 0
1824does not match forwarded packets.
1825The following example allows only selected users to open outgoing
1826connections:
1827.Bd -literal -offset indent
1828block out proto { tcp, udp } all
1829pass  out proto { tcp, udp } all user { \*(Lt 1000, dhartmei }
1830.Ed
1831.It Xo Ar flags Aq Ar a
1832.Pf / Ns Aq Ar b
1833.No \*(Ba / Ns Aq Ar b
1834.No \*(Ba any
1835.Xc
1836This rule only applies to TCP packets that have the flags
1837.Aq Ar a
1838set out of set
1839.Aq Ar b .
1840Flags not specified in
1841.Aq Ar b
1842are ignored.
1843For stateful connections, the default is
1844.Ar flags S/SA .
1845To indicate that flags should not be checked at all, specify
1846.Ar flags any .
1847The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R.
1848.Bl -tag -width Fl
1849.It Ar flags S/S
1850Flag SYN is set.
1851The other flags are ignored.
1852.It Ar flags S/SA
1853This is the default setting for stateful connections.
1854Out of SYN and ACK, exactly SYN may be set.
1855SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not.
1856This is more restrictive than the previous example.
1857.It Ar flags /SFRA
1858If the first set is not specified, it defaults to none.
1859All of SYN, FIN, RST and ACK must be unset.
1860.El
1861.Pp
1862Because
1863.Ar flags S/SA
1864is applied by default (unless
1865.Ar no state
1866is specified), only the initial SYN packet of a TCP handshake will create
1867a state for a TCP connection.
1868It is possible to be less restrictive, and allow state creation from
1869intermediate
1870.Pq non-SYN
1871packets, by specifying
1872.Ar flags any .
1873This will cause
1874.Xr pf 4
1875to synchronize to existing connections, for instance
1876if one flushes the state table.
1877However, states created from such intermediate packets may be missing
1878connection details such as the TCP window scaling factor.
1879States which modify the packet flow, such as those affected by
1880.Ar nat , binat No or Ar rdr
1881rules,
1882.Ar modulate No or Ar synproxy state
1883options, or scrubbed with
1884.Ar reassemble tcp
1885will also not be recoverable from intermediate packets.
1886Such connections will stall and time out.
1887.It Xo Ar icmp-type Aq Ar type
1888.Ar code Aq Ar code
1889.Xc
1890.It Xo Ar icmp6-type Aq Ar type
1891.Ar code Aq Ar code
1892.Xc
1893This rule only applies to ICMP or ICMPv6 packets with the specified type
1894and code.
1895Text names for ICMP types and codes are listed in
1896.Xr icmp 4
1897and
1898.Xr icmp6 4 .
1899This parameter is only valid for rules that cover protocols ICMP or
1900ICMP6.
1901The protocol and the ICMP type indicator
1902.Po
1903.Ar icmp-type
1904or
1905.Ar icmp6-type
1906.Pc
1907must match.
1908.It Xo Ar tos Aq Ar string
1909.No \*(Ba Aq Ar number
1910.Xc
1911This rule applies to packets with the specified
1912.Em TOS
1913bits set.
1914.Em TOS
1915may be
1916given as one of
1917.Ar critical ,
1918.Ar inetcontrol ,
1919.Ar lowdelay ,
1920.Ar netcontrol ,
1921.Ar throughput ,
1922.Ar reliability ,
1923or one of the DiffServ Code Points:
1924.Ar ef ,
1925.Ar va ,
1926.Ar af11 No ... Ar af43 ,
1927.Ar cs0 No ... Ar cs7 ;
1928or as either hex or decimal.
1929.Pp
1930For example, the following rules are identical:
1931.Bd -literal -offset indent
1932pass all tos lowdelay
1933pass all tos 0x10
1934pass all tos 16
1935.Ed
1936.It Ar allow-opts
1937By default, IPv4 packets with IP options or IPv6 packets with routing
1938extension headers are blocked.
1939When
1940.Ar allow-opts
1941is specified for a
1942.Ar pass
1943rule, packets that pass the filter based on that rule (last matching)
1944do so even if they contain IP options or routing extension headers.
1945For packets that match state, the rule that initially created the
1946state is used.
1947The implicit
1948.Ar pass
1949rule that is used when a packet does not match any rules does not
1950allow IP options.
1951.It Ar label Aq Ar string
1952Adds a label (name) to the rule, which can be used to identify the rule.
1953For instance,
1954pfctl -s labels
1955shows per-rule statistics for rules that have labels.
1956.Pp
1957The following macros can be used in labels:
1958.Pp
1959.Bl -tag -width $srcaddr -compact -offset indent
1960.It Ar $if
1961The interface.
1962.It Ar $srcaddr
1963The source IP address.
1964.It Ar $dstaddr
1965The destination IP address.
1966.It Ar $srcport
1967The source port specification.
1968.It Ar $dstport
1969The destination port specification.
1970.It Ar $proto
1971The protocol name.
1972.It Ar $nr
1973The rule number.
1974.El
1975.Pp
1976For example:
1977.Bd -literal -offset indent
1978ips = \&"{ 1.2.3.4, 1.2.3.5 }\&"
1979pass in proto tcp from any to $ips \e
1980      port \*(Gt 1023 label \&"$dstaddr:$dstport\&"
1981.Ed
1982.Pp
1983expands to
1984.Bd -literal -offset indent
1985pass in inet proto tcp from any to 1.2.3.4 \e
1986      port \*(Gt 1023 label \&"1.2.3.4:\*(Gt1023\&"
1987pass in inet proto tcp from any to 1.2.3.5 \e
1988      port \*(Gt 1023 label \&"1.2.3.5:\*(Gt1023\&"
1989.Ed
1990.Pp
1991The macro expansion for the
1992.Ar label
1993directive occurs only at configuration file parse time, not during runtime.
1994.It Ar ridentifier Aq Ar number
1995Add an identifier (number) to the rule, which can be used to correlate the rule
1996to pflog entries, even after ruleset updates.
1997.It Xo Ar queue Aq Ar queue
1998.No \*(Ba ( Aq Ar queue ,
1999.Aq Ar queue )
2000.Xc
2001Packets matching this rule will be assigned to the specified queue.
2002If two queues are given, packets which have a
2003.Em TOS
2004of
2005.Em lowdelay
2006and TCP ACKs with no data payload will be assigned to the second one.
2007See
2008.Sx QUEUEING
2009for setup details.
2010.Pp
2011For example:
2012.Bd -literal -offset indent
2013pass in proto tcp to port 25 queue mail
2014pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio)
2015.Ed
2016.It Cm set prio Ar priority | Pq Ar priority , priority
2017Packets matching this rule will be assigned a specific queueing priority.
2018Priorities are assigned as integers 0 through 7.
2019If the packet is transmitted on a
2020.Xr vlan 4
2021interface, the queueing priority will be written as the priority
2022code point in the 802.1Q VLAN header.
2023If two priorities are given, packets which have a TOS of
2024.Cm lowdelay
2025and TCP ACKs with no data payload will be assigned to the second one.
2026.Pp
2027For example:
2028.Bd -literal -offset indent
2029pass in proto tcp to port 25 set prio 2
2030pass in proto tcp to port 22 set prio (2, 5)
2031.Ed
2032.It Ar tag Aq Ar string
2033Packets matching this rule will be tagged with the
2034specified string.
2035The tag acts as an internal marker that can be used to
2036identify these packets later on.
2037This can be used, for example, to provide trust between
2038interfaces and to determine if packets have been
2039processed by translation rules.
2040Tags are
2041.Qq sticky ,
2042meaning that the packet will be tagged even if the rule
2043is not the last matching rule.
2044Further matching rules can replace the tag with a
2045new one but will not remove a previously applied tag.
2046A packet is only ever assigned one tag at a time.
2047Packet tagging can be done during
2048.Ar nat ,
2049.Ar rdr ,
2050.Ar binat
2051or
2052.Ar ether
2053rules in addition to filter rules.
2054Tags take the same macros as labels (see above).
2055.It Ar tagged Aq Ar string
2056Used with filter, translation or scrub rules
2057to specify that packets must already
2058be tagged with the given tag in order to match the rule.
2059Inverse tag matching can also be done
2060by specifying the
2061.Cm !\&
2062operator before the
2063.Ar tagged
2064keyword.
2065.It Ar rtable Aq Ar number
2066Used to select an alternate routing table for the routing lookup.
2067Only effective before the route lookup happened, i.e. when filtering inbound.
2068.It Xo Ar divert-to Aq Ar host
2069.Ar port Aq Ar port
2070.Xc
2071Used to redirect packets to a local socket bound to
2072.Ar host
2073and
2074.Ar port .
2075The packets will not be modified, so
2076.Xr getsockname 2
2077on the socket will return the original destination address of the packet.
2078.It Ar divert-reply
2079Used to receive replies for sockets that are bound to addresses
2080which are not local to the machine.
2081See
2082.Xr setsockopt 2
2083for information on how to bind these sockets.
2084.It Ar probability Aq Ar number
2085A probability attribute can be attached to a rule, with a value set between
20860 and 1, bounds not included.
2087In that case, the rule will be honoured using the given probability value
2088only.
2089For example, the following rule will drop 20% of incoming ICMP packets:
2090.Bd -literal -offset indent
2091block in proto icmp probability 20%
2092.Ed
2093.It Ar prio Aq Ar number
2094Only match packets which have the given queueing priority assigned.
2095.El
2096.Sh ROUTING
2097If a packet matches a rule with a route option set, the packet filter will
2098route the packet according to the type of route option.
2099When such a rule creates state, the route option is also applied to all
2100packets matching the same connection.
2101.Bl -tag -width xxxx
2102.It Ar route-to
2103The
2104.Ar route-to
2105option routes the packet to the specified interface with an optional address
2106for the next hop.
2107When a
2108.Ar route-to
2109rule creates state, only packets that pass in the same direction as the
2110filter rule specifies will be routed in this way.
2111Packets passing in the opposite direction (replies) are not affected
2112and are routed normally.
2113.It Ar reply-to
2114The
2115.Ar reply-to
2116option is similar to
2117.Ar route-to ,
2118but routes packets that pass in the opposite direction (replies) to the
2119specified interface.
2120Opposite direction is only defined in the context of a state entry, and
2121.Ar reply-to
2122is useful only in rules that create state.
2123It can be used on systems with multiple external connections to
2124route all outgoing packets of a connection through the interface
2125the incoming connection arrived through (symmetric routing enforcement).
2126.It Ar dup-to
2127The
2128.Ar dup-to
2129option creates a duplicate of the packet and routes it like
2130.Ar route-to .
2131The original packet gets routed as it normally would.
2132.El
2133.Sh POOL OPTIONS
2134For
2135.Ar nat
2136and
2137.Ar rdr
2138rules, (as well as for the
2139.Ar route-to ,
2140.Ar reply-to
2141and
2142.Ar dup-to
2143rule options) for which there is a single redirection address which has a
2144subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP
2145address), a variety of different methods for assigning this address can be
2146used:
2147.Bl -tag -width xxxx
2148.It Ar bitmask
2149The
2150.Ar bitmask
2151option applies the network portion of the redirection address to the address
2152to be modified (source with
2153.Ar nat ,
2154destination with
2155.Ar rdr ) .
2156.It Ar random
2157The
2158.Ar random
2159option selects an address at random within the defined block of addresses.
2160.It Ar source-hash
2161The
2162.Ar source-hash
2163option uses a hash of the source address to determine the redirection address,
2164ensuring that the redirection address is always the same for a given source.
2165An optional key can be specified after this keyword either in hex or as a
2166string; by default
2167.Xr pfctl 8
2168randomly generates a key for source-hash every time the
2169ruleset is reloaded.
2170.It Ar round-robin
2171The
2172.Ar round-robin
2173option loops through the redirection address(es).
2174.Pp
2175When more than one redirection address is specified,
2176.Ar round-robin
2177is the only permitted pool type.
2178.It Ar static-port
2179With
2180.Ar nat
2181rules, the
2182.Ar static-port
2183option prevents
2184.Xr pf 4
2185from modifying the source port on TCP and UDP packets.
2186.It Xo Ar map-e-portset Aq Ar psid-offset
2187.No / Aq Ar psid-len
2188.No / Aq Ar psid
2189.Xc
2190With
2191.Ar nat
2192rules, the
2193.Ar map-e-portset
2194option enables the source port translation of MAP-E (RFC 7597) Customer Edge.
2195In order to make the host act as a MAP-E Customer Edge, setting up a tunneling
2196interface and pass rules for encapsulated packets are required in addition
2197to the map-e-portset nat rule.
2198.Pp
2199For example:
2200.Bd -literal -offset indent
2201nat on $gif_mape_if from $int_if:network to any \e
2202      -> $ipv4_mape_src map-e-portset 6/8/0x34
2203.Ed
2204.Pp
2205sets PSID offset 6, PSID length 8, PSID 0x34.
2206.El
2207.Pp
2208Additionally, the
2209.Ar sticky-address
2210option can be specified to help ensure that multiple connections from the
2211same source are mapped to the same redirection address.
2212This option can be used with the
2213.Ar random
2214and
2215.Ar round-robin
2216pool options.
2217Note that by default these associations are destroyed as soon as there are
2218no longer states which refer to them; in order to make the mappings last
2219beyond the lifetime of the states, increase the global options with
2220.Ar set timeout src.track .
2221See
2222.Sx STATEFUL TRACKING OPTIONS
2223for more ways to control the source tracking.
2224.Sh STATE MODULATION
2225Much of the security derived from TCP is attributable to how well the
2226initial sequence numbers (ISNs) are chosen.
2227Some popular stack implementations choose
2228.Em very
2229poor ISNs and thus are normally susceptible to ISN prediction exploits.
2230By applying a
2231.Ar modulate state
2232rule to a TCP connection,
2233.Xr pf 4
2234will create a high quality random sequence number for each connection
2235endpoint.
2236.Pp
2237The
2238.Ar modulate state
2239directive implicitly keeps state on the rule and is
2240only applicable to TCP connections.
2241.Pp
2242For instance:
2243.Bd -literal -offset indent
2244block all
2245pass out proto tcp from any to any modulate state
2246pass in  proto tcp from any to any port 25 flags S/SFRA modulate state
2247.Ed
2248.Pp
2249Note that modulated connections will not recover when the state table
2250is lost (firewall reboot, flushing the state table, etc...).
2251.Xr pf 4
2252will not be able to infer a connection again after the state table flushes
2253the connection's modulator.
2254When the state is lost, the connection may be left dangling until the
2255respective endpoints time out the connection.
2256It is possible on a fast local network for the endpoints to start an ACK
2257storm while trying to resynchronize after the loss of the modulator.
2258The default
2259.Ar flags
2260settings (or a more strict equivalent) should be used on
2261.Ar modulate state
2262rules to prevent ACK storms.
2263.Pp
2264Note that alternative methods are available
2265to prevent loss of the state table
2266and allow for firewall failover.
2267See
2268.Xr carp 4
2269and
2270.Xr pfsync 4
2271for further information.
2272.Sh SYN PROXY
2273By default,
2274.Xr pf 4
2275passes packets that are part of a
2276.Xr tcp 4
2277handshake between the endpoints.
2278The
2279.Ar synproxy state
2280option can be used to cause
2281.Xr pf 4
2282itself to complete the handshake with the active endpoint, perform a handshake
2283with the passive endpoint, and then forward packets between the endpoints.
2284.Pp
2285No packets are sent to the passive endpoint before the active endpoint has
2286completed the handshake, hence so-called SYN floods with spoofed source
2287addresses will not reach the passive endpoint, as the sender can't complete the
2288handshake.
2289.Pp
2290The proxy is transparent to both endpoints, they each see a single
2291connection from/to the other endpoint.
2292.Xr pf 4
2293chooses random initial sequence numbers for both handshakes.
2294Once the handshakes are completed, the sequence number modulators
2295(see previous section) are used to translate further packets of the
2296connection.
2297.Ar synproxy state
2298includes
2299.Ar modulate state .
2300.Pp
2301Rules with
2302.Ar synproxy
2303will not work if
2304.Xr pf 4
2305operates on a
2306.Xr bridge 4 .
2307.Pp
2308Example:
2309.Bd -literal -offset indent
2310pass in proto tcp from any to any port www synproxy state
2311.Ed
2312.Sh STATEFUL TRACKING OPTIONS
2313A number of options related to stateful tracking can be applied on a
2314per-rule basis.
2315.Ar keep state ,
2316.Ar modulate state
2317and
2318.Ar synproxy state
2319support these options, and
2320.Ar keep state
2321must be specified explicitly to apply options to a rule.
2322.Pp
2323.Bl -tag -width xxxx -compact
2324.It Ar max Aq Ar number
2325Limits the number of concurrent states the rule may create.
2326When this limit is reached, further packets that would create
2327state will not match this rule until existing states time out.
2328.It Ar no-sync
2329Prevent state changes for states created by this rule from appearing on the
2330.Xr pfsync 4
2331interface.
2332.It Xo Aq Ar timeout
2333.Aq Ar seconds
2334.Xc
2335Changes the timeout values used for states created by this rule.
2336For a list of all valid timeout names, see
2337.Sx OPTIONS
2338above.
2339.It Ar sloppy
2340Uses a sloppy TCP connection tracker that does not check sequence
2341numbers at all, which makes insertion and ICMP teardown attacks way
2342easier.
2343This is intended to be used in situations where one does not see all
2344packets of a connection, e.g. in asymmetric routing situations.
2345Cannot be used with modulate or synproxy state.
2346.El
2347.Pp
2348Multiple options can be specified, separated by commas:
2349.Bd -literal -offset indent
2350pass in proto tcp from any to any \e
2351      port www keep state \e
2352      (max 100, source-track rule, max-src-nodes 75, \e
2353      max-src-states 3, tcp.established 60, tcp.closing 5)
2354.Ed
2355.Pp
2356When the
2357.Ar source-track
2358keyword is specified, the number of states per source IP is tracked.
2359.Pp
2360.Bl -tag -width xxxx -compact
2361.It Ar source-track rule
2362The maximum number of states created by this rule is limited by the rule's
2363.Ar max-src-nodes
2364and
2365.Ar max-src-states
2366options.
2367Only state entries created by this particular rule count toward the rule's
2368limits.
2369.It Ar source-track global
2370The number of states created by all rules that use this option is limited.
2371Each rule can specify different
2372.Ar max-src-nodes
2373and
2374.Ar max-src-states
2375options, however state entries created by any participating rule count towards
2376each individual rule's limits.
2377.El
2378.Pp
2379The following limits can be set:
2380.Pp
2381.Bl -tag -width xxxx -compact
2382.It Ar max-src-nodes Aq Ar number
2383Limits the maximum number of source addresses which can simultaneously
2384have state table entries.
2385.It Ar max-src-states Aq Ar number
2386Limits the maximum number of simultaneous state entries that a single
2387source address can create with this rule.
2388.El
2389.Pp
2390For stateful TCP connections, limits on established connections (connections
2391which have completed the TCP 3-way handshake) can also be enforced
2392per source IP.
2393.Pp
2394.Bl -tag -width xxxx -compact
2395.It Ar max-src-conn Aq Ar number
2396Limits the maximum number of simultaneous TCP connections which have
2397completed the 3-way handshake that a single host can make.
2398.It Xo Ar max-src-conn-rate Aq Ar number
2399.No / Aq Ar seconds
2400.Xc
2401Limit the rate of new connections over a time interval.
2402The connection rate is an approximation calculated as a moving average.
2403.El
2404.Pp
2405Because the 3-way handshake ensures that the source address is not being
2406spoofed, more aggressive action can be taken based on these limits.
2407With the
2408.Ar overload Aq Ar table
2409state option, source IP addresses which hit either of the limits on
2410established connections will be added to the named table.
2411This table can be used in the ruleset to block further activity from
2412the offending host, redirect it to a tarpit process, or restrict its
2413bandwidth.
2414.Pp
2415The optional
2416.Ar flush
2417keyword kills all states created by the matching rule which originate
2418from the host which exceeds these limits.
2419The
2420.Ar global
2421modifier to the flush command kills all states originating from the
2422offending host, regardless of which rule created the state.
2423.Pp
2424For example, the following rules will protect the webserver against
2425hosts making more than 100 connections in 10 seconds.
2426Any host which connects faster than this rate will have its address added
2427to the
2428.Aq bad_hosts
2429table and have all states originating from it flushed.
2430Any new packets arriving from this host will be dropped unconditionally
2431by the block rule.
2432.Bd -literal -offset indent
2433block quick from \*(Ltbad_hosts\*(Gt
2434pass in on $ext_if proto tcp to $webserver port www keep state \e
2435	(max-src-conn-rate 100/10, overload \*(Ltbad_hosts\*(Gt flush global)
2436.Ed
2437.Sh OPERATING SYSTEM FINGERPRINTING
2438Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP
2439connection's initial SYN packet and guess at the host's operating system.
2440Unfortunately these nuances are easily spoofed by an attacker so the
2441fingerprint is not useful in making security decisions.
2442But the fingerprint is typically accurate enough to make policy decisions
2443upon.
2444.Pp
2445The fingerprints may be specified by operating system class, by
2446version, or by subtype/patchlevel.
2447The class of an operating system is typically the vendor or genre
2448and would be
2449.Ox
2450for the
2451.Xr pf 4
2452firewall itself.
2453The version of the oldest available
2454.Ox
2455release on the main FTP site
2456would be 2.6 and the fingerprint would be written
2457.Pp
2458.Dl \&"OpenBSD 2.6\&"
2459.Pp
2460The subtype of an operating system is typically used to describe the
2461patchlevel if that patch led to changes in the TCP stack behavior.
2462In the case of
2463.Ox ,
2464the only subtype is for a fingerprint that was
2465normalized by the
2466.Ar no-df
2467scrub option and would be specified as
2468.Pp
2469.Dl \&"OpenBSD 3.3 no-df\&"
2470.Pp
2471Fingerprints for most popular operating systems are provided by
2472.Xr pf.os 5 .
2473Once
2474.Xr pf 4
2475is running, a complete list of known operating system fingerprints may
2476be listed by running:
2477.Pp
2478.Dl # pfctl -so
2479.Pp
2480Filter rules can enforce policy at any level of operating system specification
2481assuming a fingerprint is present.
2482Policy could limit traffic to approved operating systems or even ban traffic
2483from hosts that aren't at the latest service pack.
2484.Pp
2485The
2486.Ar unknown
2487class can also be used as the fingerprint which will match packets for
2488which no operating system fingerprint is known.
2489.Pp
2490Examples:
2491.Bd -literal -offset indent
2492pass  out proto tcp from any os OpenBSD
2493block out proto tcp from any os Doors
2494block out proto tcp from any os "Doors PT"
2495block out proto tcp from any os "Doors PT SP3"
2496block out from any os "unknown"
2497pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0"
2498.Ed
2499.Pp
2500Operating system fingerprinting is limited only to the TCP SYN packet.
2501This means that it will not work on other protocols and will not match
2502a currently established connection.
2503.Pp
2504Caveat: operating system fingerprints are occasionally wrong.
2505There are three problems: an attacker can trivially craft his packets to
2506appear as any operating system he chooses;
2507an operating system patch could change the stack behavior and no fingerprints
2508will match it until the database is updated;
2509and multiple operating systems may have the same fingerprint.
2510.Sh BLOCKING SPOOFED TRAFFIC
2511"Spoofing" is the faking of IP addresses, typically for malicious
2512purposes.
2513The
2514.Ar antispoof
2515directive expands to a set of filter rules which will block all
2516traffic with a source IP from the network(s) directly connected
2517to the specified interface(s) from entering the system through
2518any other interface.
2519.Pp
2520For example, the line
2521.Bd -literal -offset indent
2522antispoof for lo0
2523.Ed
2524.Pp
2525expands to
2526.Bd -literal -offset indent
2527block drop in on ! lo0 inet from 127.0.0.1/8 to any
2528block drop in on ! lo0 inet6 from ::1 to any
2529.Ed
2530.Pp
2531For non-loopback interfaces, there are additional rules to block incoming
2532packets with a source IP address identical to the interface's IP(s).
2533For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a
2534netmask of 255.255.255.0,
2535the line
2536.Bd -literal -offset indent
2537antispoof for wi0 inet
2538.Ed
2539.Pp
2540expands to
2541.Bd -literal -offset indent
2542block drop in on ! wi0 inet from 10.0.0.0/24 to any
2543block drop in inet from 10.0.0.1 to any
2544.Ed
2545.Pp
2546Caveat: Rules created by the
2547.Ar antispoof
2548directive interfere with packets sent over loopback interfaces
2549to local addresses.
2550One should pass these explicitly.
2551.Sh FRAGMENT HANDLING
2552The size of IP datagrams (packets) can be significantly larger than the
2553maximum transmission unit (MTU) of the network.
2554In cases when it is necessary or more efficient to send such large packets,
2555the large packet will be fragmented into many smaller packets that will each
2556fit onto the wire.
2557Unfortunately for a firewalling device, only the first logical fragment will
2558contain the necessary header information for the subprotocol that allows
2559.Xr pf 4
2560to filter on things such as TCP ports or to perform NAT.
2561.Pp
2562Besides the use of
2563.Ar scrub
2564rules as described in
2565.Sx TRAFFIC NORMALIZATION
2566above, there are three options for handling fragments in the packet filter.
2567.Pp
2568One alternative is to filter individual fragments with filter rules.
2569If no
2570.Ar scrub
2571rule applies to a fragment, it is passed to the filter.
2572Filter rules with matching IP header parameters decide whether the
2573fragment is passed or blocked, in the same way as complete packets
2574are filtered.
2575Without reassembly, fragments can only be filtered based on IP header
2576fields (source/destination address, protocol), since subprotocol header
2577fields are not available (TCP/UDP port numbers, ICMP code/type).
2578The
2579.Ar fragment
2580option can be used to restrict filter rules to apply only to
2581fragments, but not complete packets.
2582Filter rules without the
2583.Ar fragment
2584option still apply to fragments, if they only specify IP header fields.
2585For instance, the rule
2586.Bd -literal -offset indent
2587pass in proto tcp from any to any port 80
2588.Ed
2589.Pp
2590never applies to a fragment, even if the fragment is part of a TCP
2591packet with destination port 80, because without reassembly this information
2592is not available for each fragment.
2593This also means that fragments cannot create new or match existing
2594state table entries, which makes stateful filtering and address
2595translation (NAT, redirection) for fragments impossible.
2596.Pp
2597It's also possible to reassemble only certain fragments by specifying
2598source or destination addresses or protocols as parameters in
2599.Ar scrub
2600rules.
2601.Pp
2602In most cases, the benefits of reassembly outweigh the additional
2603memory cost, and it's recommended to use
2604.Ar scrub
2605rules to reassemble
2606all fragments via the
2607.Ar fragment reassemble
2608modifier.
2609.Pp
2610The memory allocated for fragment caching can be limited using
2611.Xr pfctl 8 .
2612Once this limit is reached, fragments that would have to be cached
2613are dropped until other entries time out.
2614The timeout value can also be adjusted.
2615.Pp
2616When forwarding reassembled IPv6 packets, pf refragments them with
2617the original maximum fragment size.
2618This allows the sender to determine the optimal fragment size by
2619path MTU discovery.
2620.Sh ANCHORS
2621Besides the main ruleset,
2622.Xr pfctl 8
2623can load rulesets into
2624.Ar anchor
2625attachment points.
2626An
2627.Ar anchor
2628is a container that can hold rules, address tables, and other anchors.
2629.Pp
2630An
2631.Ar anchor
2632has a name which specifies the path where
2633.Xr pfctl 8
2634can be used to access the anchor to perform operations on it, such as
2635attaching child anchors to it or loading rules into it.
2636Anchors may be nested, with components separated by
2637.Sq /
2638characters, similar to how file system hierarchies are laid out.
2639The main ruleset is actually the default anchor, so filter and
2640translation rules, for example, may also be contained in any anchor.
2641.Pp
2642An anchor can reference another
2643.Ar anchor
2644attachment point
2645using the following kinds
2646of rules:
2647.Bl -tag -width xxxx
2648.It Ar nat-anchor Aq Ar name
2649Evaluates the
2650.Ar nat
2651rules in the specified
2652.Ar anchor .
2653.It Ar rdr-anchor Aq Ar name
2654Evaluates the
2655.Ar rdr
2656rules in the specified
2657.Ar anchor .
2658.It Ar binat-anchor Aq Ar name
2659Evaluates the
2660.Ar binat
2661rules in the specified
2662.Ar anchor .
2663.It Ar anchor Aq Ar name
2664Evaluates the filter rules in the specified
2665.Ar anchor .
2666.It Xo Ar load anchor
2667.Aq Ar name
2668.Ar from Aq Ar file
2669.Xc
2670Loads the rules from the specified file into the
2671anchor
2672.Ar name .
2673.El
2674.Pp
2675When evaluation of the main ruleset reaches an
2676.Ar anchor
2677rule,
2678.Xr pf 4
2679will proceed to evaluate all rules specified in that anchor.
2680.Pp
2681Matching filter and translation rules marked with the
2682.Ar quick
2683option are final and abort the evaluation of the rules in other
2684anchors and the main ruleset.
2685If the
2686.Ar anchor
2687itself is marked with the
2688.Ar quick
2689option,
2690ruleset evaluation will terminate when the anchor is exited if the packet is
2691matched by any rule within the anchor.
2692.Pp
2693.Ar anchor
2694rules are evaluated relative to the anchor in which they are contained.
2695For example, all
2696.Ar anchor
2697rules specified in the main ruleset will reference anchor
2698attachment points underneath the main ruleset, and
2699.Ar anchor
2700rules specified in a file loaded from a
2701.Ar load anchor
2702rule will be attached under that anchor point.
2703.Pp
2704Rules may be contained in
2705.Ar anchor
2706attachment points which do not contain any rules when the main ruleset
2707is loaded, and later such anchors can be manipulated through
2708.Xr pfctl 8
2709without reloading the main ruleset or other anchors.
2710For example,
2711.Bd -literal -offset indent
2712ext_if = \&"kue0\&"
2713block on $ext_if all
2714anchor spam
2715pass out on $ext_if all
2716pass in on $ext_if proto tcp from any \e
2717      to $ext_if port smtp
2718.Ed
2719.Pp
2720blocks all packets on the external interface by default, then evaluates
2721all rules in the
2722.Ar anchor
2723named "spam", and finally passes all outgoing connections and
2724incoming connections to port 25.
2725.Bd -literal -offset indent
2726# echo \&"block in quick from 1.2.3.4 to any\&" \&| \e
2727      pfctl -a spam -f -
2728.Ed
2729.Pp
2730This loads a single rule into the
2731.Ar anchor ,
2732which blocks all packets from a specific address.
2733.Pp
2734The anchor can also be populated by adding a
2735.Ar load anchor
2736rule after the
2737.Ar anchor
2738rule:
2739.Bd -literal -offset indent
2740anchor spam
2741load anchor spam from "/etc/pf-spam.conf"
2742.Ed
2743.Pp
2744When
2745.Xr pfctl 8
2746loads
2747.Nm pf.conf ,
2748it will also load all the rules from the file
2749.Pa /etc/pf-spam.conf
2750into the anchor.
2751.Pp
2752Optionally,
2753.Ar anchor
2754rules can specify packet filtering parameters using the same syntax as
2755filter rules.
2756When parameters are used, the
2757.Ar anchor
2758rule is only evaluated for matching packets.
2759This allows conditional evaluation of anchors, like:
2760.Bd -literal -offset indent
2761block on $ext_if all
2762anchor spam proto tcp from any to any port smtp
2763pass out on $ext_if all
2764pass in on $ext_if proto tcp from any to $ext_if port smtp
2765.Ed
2766.Pp
2767The rules inside
2768.Ar anchor
2769spam are only evaluated for
2770.Ar tcp
2771packets with destination port 25.
2772Hence,
2773.Bd -literal -offset indent
2774# echo \&"block in quick from 1.2.3.4 to any" \&| \e
2775      pfctl -a spam -f -
2776.Ed
2777.Pp
2778will only block connections from 1.2.3.4 to port 25.
2779.Pp
2780Anchors may end with the asterisk
2781.Pq Sq *
2782character, which signifies that all anchors attached at that point
2783should be evaluated in the alphabetical ordering of their anchor name.
2784For example,
2785.Bd -literal -offset indent
2786anchor "spam/*"
2787.Ed
2788.Pp
2789will evaluate each rule in each anchor attached to the
2790.Li spam
2791anchor.
2792Note that it will only evaluate anchors that are directly attached to the
2793.Li spam
2794anchor, and will not descend to evaluate anchors recursively.
2795.Pp
2796Since anchors are evaluated relative to the anchor in which they are
2797contained, there is a mechanism for accessing the parent and ancestor
2798anchors of a given anchor.
2799Similar to file system path name resolution, if the sequence
2800.Dq ..
2801appears as an anchor path component, the parent anchor of the current
2802anchor in the path evaluation at that point will become the new current
2803anchor.
2804As an example, consider the following:
2805.Bd -literal -offset indent
2806# echo ' anchor "spam/allowed" ' | pfctl -f -
2807# echo -e ' anchor "../banned" \en pass' | \e
2808      pfctl -a spam/allowed -f -
2809.Ed
2810.Pp
2811Evaluation of the main ruleset will lead into the
2812.Li spam/allowed
2813anchor, which will evaluate the rules in the
2814.Li spam/banned
2815anchor, if any, before finally evaluating the
2816.Ar pass
2817rule.
2818.Pp
2819Filter rule
2820.Ar anchors
2821can also be loaded inline in the ruleset within a brace ('{' '}') delimited
2822block.
2823Brace delimited blocks may contain rules or other brace-delimited blocks.
2824When anchors are loaded this way the anchor name becomes optional.
2825.Bd -literal -offset indent
2826anchor "external" on $ext_if {
2827	block
2828	anchor out {
2829		pass proto tcp from any to port { 25, 80, 443 }
2830	}
2831	pass in proto tcp to any port 22
2832}
2833.Ed
2834.Pp
2835Since the parser specification for anchor names is a string, any
2836reference to an anchor name containing
2837.Sq /
2838characters will require double quote
2839.Pq Sq \&"
2840characters around the anchor name.
2841.Sh TRANSLATION EXAMPLES
2842This example maps incoming requests on port 80 to port 8080, on
2843which a daemon is running (because, for example, it is not run as root,
2844and therefore lacks permission to bind to port 80).
2845.Bd -literal
2846# use a macro for the interface name, so it can be changed easily
2847ext_if = \&"ne3\&"
2848
2849# map daemon on 8080 to appear to be on 80
2850rdr on $ext_if proto tcp from any to any port 80 -\*(Gt 127.0.0.1 port 8080
2851.Ed
2852.Pp
2853If the
2854.Ar pass
2855modifier is given, packets matching the translation rule are passed without
2856inspecting the filter rules:
2857.Bd -literal
2858rdr pass on $ext_if proto tcp from any to any port 80 -\*(Gt 127.0.0.1 \e
2859      port 8080
2860.Ed
2861.Pp
2862In the example below, vlan12 is configured as 192.168.168.1;
2863the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111
2864when they are going out any interface except vlan12.
2865This has the net effect of making traffic from the 192.168.168.0/24
2866network appear as though it is the Internet routable address
2867204.92.77.111 to nodes behind any interface on the router except
2868for the nodes on vlan12.
2869(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.)
2870.Bd -literal
2871nat on ! vlan12 from 192.168.168.0/24 to any -\*(Gt 204.92.77.111
2872.Ed
2873.Pp
2874In the example below, the machine sits between a fake internal 144.19.74.*
2875network, and a routable external IP of 204.92.77.100.
2876The
2877.Ar no nat
2878rule excludes protocol AH from being translated.
2879.Bd -literal
2880# NO NAT
2881no nat on $ext_if proto ah from 144.19.74.0/24 to any
2882nat on $ext_if from 144.19.74.0/24 to any -\*(Gt 204.92.77.100
2883.Ed
2884.Pp
2885In the example below, packets bound for one specific server, as well as those
2886generated by the sysadmins are not proxied; all other connections are.
2887.Bd -literal
2888# NO RDR
2889no rdr on $int_if proto { tcp, udp } from any to $server port 80
2890no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80
2891rdr on $int_if proto { tcp, udp } from any to any port 80 -\*(Gt 127.0.0.1 \e
2892      port 80
2893.Ed
2894.Pp
2895This longer example uses both a NAT and a redirection.
2896The external interface has the address 157.161.48.183.
2897On localhost, we are running
2898.Xr ftp-proxy 8 ,
2899waiting for FTP sessions to be redirected to it.
2900The three mandatory anchors for
2901.Xr ftp-proxy 8
2902are omitted from this example; see the
2903.Xr ftp-proxy 8
2904manpage.
2905.Bd -literal
2906# NAT
2907# Translate outgoing packets' source addresses (any protocol).
2908# In this case, any address but the gateway's external address is mapped.
2909nat on $ext_if inet from ! ($ext_if) to any -\*(Gt ($ext_if)
2910
2911# NAT PROXYING
2912# Map outgoing packets' source port to an assigned proxy port instead of
2913# an arbitrary port.
2914# In this case, proxy outgoing isakmp with port 500 on the gateway.
2915nat on $ext_if inet proto udp from any port = isakmp to any -\*(Gt ($ext_if) \e
2916      port 500
2917
2918# BINAT
2919# Translate outgoing packets' source address (any protocol).
2920# Translate incoming packets' destination address to an internal machine
2921# (bidirectional).
2922binat on $ext_if from 10.1.2.150 to any -\*(Gt $ext_if
2923
2924# RDR
2925# Translate incoming packets' destination addresses.
2926# As an example, redirect a TCP and UDP port to an internal machine.
2927rdr on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e
2928      -\*(Gt 10.1.2.151 port 22
2929rdr on $ext_if inet proto udp from any to ($ext_if) port 8080 \e
2930      -\*(Gt 10.1.2.151 port 53
2931
2932# RDR
2933# Translate outgoing ftp control connections to send them to localhost
2934# for proxying with ftp-proxy(8) running on port 8021.
2935rdr on $int_if proto tcp from any to any port 21 -\*(Gt 127.0.0.1 port 8021
2936.Ed
2937.Pp
2938In this example, a NAT gateway is set up to translate internal addresses
2939using a pool of public addresses (192.0.2.16/28) and to redirect
2940incoming web server connections to a group of web servers on the internal
2941network.
2942.Bd -literal
2943# NAT LOAD BALANCE
2944# Translate outgoing packets' source addresses using an address pool.
2945# A given source address is always translated to the same pool address by
2946# using the source-hash keyword.
2947nat on $ext_if inet from any to any -\*(Gt 192.0.2.16/28 source-hash
2948
2949# RDR ROUND ROBIN
2950# Translate incoming web server connections to a group of web servers on
2951# the internal network.
2952rdr on $ext_if proto tcp from any to any port 80 \e
2953      -\*(Gt { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin
2954.Ed
2955.Sh FILTER EXAMPLES
2956.Bd -literal
2957# The external interface is kue0
2958# (157.161.48.183, the only routable address)
2959# and the private network is 10.0.0.0/8, for which we are doing NAT.
2960
2961# use a macro for the interface name, so it can be changed easily
2962ext_if = \&"kue0\&"
2963
2964# normalize all incoming traffic
2965scrub in on $ext_if all fragment reassemble
2966
2967# block and log everything by default
2968block return log on $ext_if all
2969
2970# block anything coming from source we have no back routes for
2971block in from no-route to any
2972
2973# block packets whose ingress interface does not match the one in
2974# the route back to their source address
2975block in from urpf-failed to any
2976
2977# block and log outgoing packets that do not have our address as source,
2978# they are either spoofed or something is misconfigured (NAT disabled,
2979# for instance), we want to be nice and do not send out garbage.
2980block out log quick on $ext_if from ! 157.161.48.183 to any
2981
2982# silently drop broadcasts (cable modem noise)
2983block in quick on $ext_if from any to 255.255.255.255
2984
2985# block and log incoming packets from reserved address space and invalid
2986# addresses, they are either spoofed or misconfigured, we cannot reply to
2987# them anyway (hence, no return-rst).
2988block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e
2989      192.168.0.0/16, 255.255.255.255/32 } to any
2990
2991# ICMP
2992
2993# pass out/in certain ICMP queries and keep state (ping)
2994# state matching is done on host addresses and ICMP id (not type/code),
2995# so replies (like 0/0 for 8/0) will match queries
2996# ICMP error messages (which always refer to a TCP/UDP packet) are
2997# handled by the TCP/UDP states
2998pass on $ext_if inet proto icmp all icmp-type 8 code 0
2999
3000# UDP
3001
3002# pass out all UDP connections and keep state
3003pass out on $ext_if proto udp all
3004
3005# pass in certain UDP connections and keep state (DNS)
3006pass in on $ext_if proto udp from any to any port domain
3007
3008# TCP
3009
3010# pass out all TCP connections and modulate state
3011pass out on $ext_if proto tcp all modulate state
3012
3013# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT)
3014pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e
3015      auth }
3016
3017# Do not allow Windows 9x SMTP connections since they are typically
3018# a viral worm. Alternately we could limit these OSes to 1 connection each.
3019block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e
3020      to any port smtp
3021
3022# IPv6
3023# pass in/out all IPv6 traffic: note that we have to enable this in two
3024# different ways, on both our physical interface and our tunnel
3025pass quick on gif0 inet6
3026pass quick on $ext_if proto ipv6
3027
3028# Packet Tagging
3029
3030# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is
3031# being done on $ext_if for all outgoing packets. tag packets in on
3032# $int_if and pass those tagged packets out on $ext_if.  all other
3033# outgoing packets (i.e., packets from the wireless network) are only
3034# permitted to access port 80.
3035
3036pass in on $int_if from any to any tag INTNET
3037pass in on $wifi_if from any to any
3038
3039block out on $ext_if from any to any
3040pass out quick on $ext_if tagged INTNET
3041pass out on $ext_if proto tcp from any to any port 80
3042
3043# tag incoming packets as they are redirected to spamd(8). use the tag
3044# to pass those packets through the packet filter.
3045
3046rdr on $ext_if inet proto tcp from \*(Ltspammers\*(Gt to port smtp \e
3047	tag SPAMD -\*(Gt 127.0.0.1 port spamd
3048
3049block in on $ext_if
3050pass in on $ext_if inet proto tcp tagged SPAMD
3051.Ed
3052.Sh GRAMMAR
3053Syntax for
3054.Nm
3055in BNF:
3056.Bd -literal
3057line           = ( option | ether-rule | pf-rule | nat-rule | binat-rule |
3058                 rdr-rule | antispoof-rule | altq-rule | queue-rule |
3059                 trans-anchors | anchor-rule | anchor-close | load-anchor |
3060                 table-rule | include )
3061
3062option         = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] |
3063                 [ "ruleset-optimization" [ "none" | "basic" | "profile" ]] |
3064                 [ "optimization" [ "default" | "normal" |
3065                 "high-latency" | "satellite" |
3066                 "aggressive" | "conservative" ] ]
3067                 [ "limit" ( limit-item | "{" limit-list "}" ) ] |
3068                 [ "loginterface" ( interface-name | "none" ) ] |
3069                 [ "block-policy" ( "drop" | "return" ) ] |
3070                 [ "state-policy" ( "if-bound" | "floating" ) ]
3071                 [ "state-defaults" state-opts ]
3072                 [ "require-order" ( "yes" | "no" ) ]
3073                 [ "fingerprints" filename ] |
3074                 [ "skip on" ifspec ] |
3075                 [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ]
3076                 [ "keepcounters" ] )
3077
3078ether-rule     = "ether" etheraction [ ( "in" | "out" ) ]
3079                 [ "quick" ] [ "on" ifspec ] [ etherprotospec ]
3080                 etherhosts [ "l3" hosts ] [ etherfilteropt-list ]
3081
3082pf-rule        = action [ ( "in" | "out" ) ]
3083                 [ "log" [ "(" logopts ")"] ] [ "quick" ]
3084                 [ "on" ifspec ] [ route ] [ af ] [ protospec ]
3085                 hosts [ filteropt-list ]
3086
3087logopts        = logopt [ "," logopts ]
3088logopt         = "all" | "user" | "to" interface-name
3089
3090etherfilteropt-list = etherfilteropt-list etherfilteropt | etherfilteropt
3091etherfilteropt = "tag" string | "tagged" string | "queue" ( string )
3092
3093filteropt-list = filteropt-list filteropt | filteropt
3094filteropt      = user | group | flags | icmp-type | icmp6-type | "tos" tos |
3095                 ( "no" | "keep" | "modulate" | "synproxy" ) "state"
3096                 [ "(" state-opts ")" ] |
3097                 "fragment" | "no-df" | "min-ttl" number | "set-tos" tos |
3098                 "max-mss" number | "random-id" | "reassemble tcp" |
3099                 fragmentation | "allow-opts" |
3100                 "label" string | "tag" string | [ ! ] "tagged" string |
3101                 "set prio" ( number | "(" number [ [ "," ] number ] ")" ) |
3102                 "queue" ( string | "(" string [ [ "," ] string ] ")" ) |
3103                 "rtable" number | "probability" number"%" | "prio" number |
3104                 "dnpipe" ( number | "(" number "," number ")" ) |
3105                 "dnqueue" ( number | "(" number "," number ")" ) |
3106                 "ridentifier" number
3107
3108nat-rule       = [ "no" ] "nat" [ "pass" [ "log" [ "(" logopts ")" ] ] ]
3109                 [ "on" ifspec ] [ af ]
3110                 [ protospec ] hosts [ "tag" string ] [ "tagged" string ]
3111                 [ "-\*(Gt" ( redirhost | "{" redirhost-list "}" )
3112                 [ portspec ] [ pooltype ] [ "static-port" ]
3113                 [ "map-e-portset" number "/" number "/" number ] ]
3114
3115binat-rule     = [ "no" ] "binat" [ "pass" [ "log" [ "(" logopts ")" ] ] ]
3116                 [ "on" interface-name ] [ af ]
3117                 [ "proto" ( proto-name | proto-number ) ]
3118                 "from" address [ "/" mask-bits ] "to" ipspec
3119                 [ "tag" string ] [ "tagged" string ]
3120                 [ "-\*(Gt" address [ "/" mask-bits ] ]
3121
3122rdr-rule       = [ "no" ] "rdr" [ "pass" [ "log" [ "(" logopts ")" ] ] ]
3123                 [ "on" ifspec ] [ af ]
3124                 [ protospec ] hosts [ "tag" string ] [ "tagged" string ]
3125                 [ "-\*(Gt" ( redirhost | "{" redirhost-list "}" )
3126                 [ portspec ] [ pooltype ] ]
3127
3128antispoof-rule = "antispoof" [ "log" ] [ "quick" ]
3129                 "for" ifspec [ af ] [ "label" string ]
3130                 [ "ridentifier" number ]
3131
3132table-rule     = "table" "\*(Lt" string "\*(Gt" [ tableopts-list ]
3133tableopts-list = tableopts-list tableopts | tableopts
3134tableopts      = "persist" | "const" | "counters" | "file" string |
3135                 "{" [ tableaddr-list ] "}"
3136tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec
3137tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ]
3138tableaddr      = hostname | ifspec | "self" |
3139                 ipv4-dotted-quad | ipv6-coloned-hex
3140
3141altq-rule      = "altq on" interface-name queueopts-list
3142                 "queue" subqueue
3143queue-rule     = "queue" string [ "on" interface-name ] queueopts-list
3144                 subqueue
3145
3146anchor-rule    = "anchor" [ string ] [ ( "in" | "out" ) ] [ "on" ifspec ]
3147                 [ af ] [ protospec ] [ hosts ] [ filteropt-list ] [ "{" ]
3148
3149anchor-close   = "}"
3150
3151trans-anchors  = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string
3152                 [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ]
3153
3154load-anchor    = "load anchor" string "from" filename
3155
3156queueopts-list = queueopts-list queueopts | queueopts
3157queueopts      = [ "bandwidth" bandwidth-spec ] |
3158                 [ "qlimit" number ] | [ "tbrsize" number ] |
3159                 [ "priority" number ] | [ schedulers ]
3160schedulers     = ( cbq-def | priq-def | hfsc-def )
3161bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" )
3162
3163etheraction    = "pass" | "block"
3164action         = "pass" | "block" [ return ] | [ "no" ] "scrub"
3165return         = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] |
3166                 "return-icmp" [ "(" icmpcode [ [ "," ] icmp6code ] ")" ] |
3167                 "return-icmp6" [ "(" icmp6code ")" ]
3168icmpcode       = ( icmp-code-name | icmp-code-number )
3169icmp6code      = ( icmp6-code-name | icmp6-code-number )
3170
3171ifspec         = ( [ "!" ] ( interface-name | interface-group ) ) |
3172                 "{" interface-list "}"
3173interface-list = [ "!" ] ( interface-name | interface-group )
3174                 [ [ "," ] interface-list ]
3175route          = ( "route-to" | "reply-to" | "dup-to" )
3176                 ( routehost | "{" routehost-list "}" )
3177                 [ pooltype ]
3178af             = "inet" | "inet6"
3179
3180etherprotospec = "proto" ( proto-number | "{" proto-list "}" )
3181protospec      = "proto" ( proto-name | proto-number |
3182                 "{" proto-list "}" )
3183proto-list     = ( proto-name | proto-number ) [ [ "," ] proto-list ]
3184
3185etherhosts     = "from" macaddress "to" macaddress
3186macaddress     = mac | mac "/" masklen | mac "&" mask
3187
3188hosts          = "all" |
3189                 "from" ( "any" | "no-route" | "urpf-failed" | "self" | host |
3190                 "{" host-list "}" ) [ port ] [ os ]
3191                 "to"   ( "any" | "no-route" | "self" | host |
3192                 "{" host-list "}" ) [ port ]
3193
3194ipspec         = "any" | host | "{" host-list "}"
3195host           = [ "!" ] ( address [ "/" mask-bits ] | "\*(Lt" string "\*(Gt" )
3196redirhost      = address [ "/" mask-bits ]
3197routehost      = "(" interface-name [ address [ "/" mask-bits ] ] ")"
3198address        = ( interface-name | interface-group |
3199                 "(" ( interface-name | interface-group ) ")" |
3200                 hostname | ipv4-dotted-quad | ipv6-coloned-hex )
3201host-list      = host [ [ "," ] host-list ]
3202redirhost-list = redirhost [ [ "," ] redirhost-list ]
3203routehost-list = routehost [ [ "," ] routehost-list ]
3204
3205port           = "port" ( unary-op | binary-op | "{" op-list "}" )
3206portspec       = "port" ( number | name ) [ ":" ( "*" | number | name ) ]
3207os             = "os"  ( os-name | "{" os-list "}" )
3208user           = "user" ( unary-op | binary-op | "{" op-list "}" )
3209group          = "group" ( unary-op | binary-op | "{" op-list "}" )
3210
3211unary-op       = [ "=" | "!=" | "\*(Lt" | "\*(Le" | "\*(Gt" | "\*(Ge" ]
3212                 ( name | number )
3213binary-op      = number ( "\*(Lt\*(Gt" | "\*(Gt\*(Lt" | ":" ) number
3214op-list        = ( unary-op | binary-op ) [ [ "," ] op-list ]
3215
3216os-name        = operating-system-name
3217os-list        = os-name [ [ "," ] os-list ]
3218
3219flags          = "flags" ( [ flag-set ] "/"  flag-set | "any" )
3220flag-set       = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ]
3221                 [ "W" ]
3222
3223icmp-type      = "icmp-type" ( icmp-type-code | "{" icmp-list "}" )
3224icmp6-type     = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" )
3225icmp-type-code = ( icmp-type-name | icmp-type-number )
3226                 [ "code" ( icmp-code-name | icmp-code-number ) ]
3227icmp-list      = icmp-type-code [ [ "," ] icmp-list ]
3228
3229tos            = ( "lowdelay" | "throughput" | "reliability" |
3230                 [ "0x" ] number )
3231
3232state-opts     = state-opt [ [ "," ] state-opts ]
3233state-opt      = ( "max" number | "no-sync" | timeout | "sloppy" |
3234                 "source-track" [ ( "rule" | "global" ) ] |
3235                 "max-src-nodes" number | "max-src-states" number |
3236                 "max-src-conn" number |
3237                 "max-src-conn-rate" number "/" number |
3238                 "overload" "\*(Lt" string "\*(Gt" [ "flush" ] |
3239                 "if-bound" | "floating" )
3240
3241fragmentation  = [ "fragment reassemble" ]
3242
3243timeout-list   = timeout [ [ "," ] timeout-list ]
3244timeout        = ( "tcp.first" | "tcp.opening" | "tcp.established" |
3245                 "tcp.closing" | "tcp.finwait" | "tcp.closed" |
3246                 "udp.first" | "udp.single" | "udp.multiple" |
3247                 "icmp.first" | "icmp.error" |
3248                 "other.first" | "other.single" | "other.multiple" |
3249                 "frag" | "interval" | "src.track" |
3250                 "adaptive.start" | "adaptive.end" ) number
3251
3252limit-list     = limit-item [ [ "," ] limit-list ]
3253limit-item     = ( "states" | "frags" | "src-nodes" ) number
3254
3255pooltype       = ( "bitmask" | "random" |
3256                 "source-hash" [ ( hex-key | string-key ) ] |
3257                 "round-robin" ) [ sticky-address ]
3258
3259subqueue       = string | "{" queue-list "}"
3260queue-list     = string [ [ "," ] string ]
3261cbq-def        = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ]
3262priq-def       = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ]
3263hfsc-def       = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ]
3264cbq-opt        = ( "default" | "borrow" | "red" | "ecn" | "rio" )
3265priq-opt       = ( "default" | "red" | "ecn" | "rio" )
3266hfsc-opt       = ( "default" | "red" | "ecn" | "rio" |
3267                 linkshare-sc | realtime-sc | upperlimit-sc )
3268linkshare-sc   = "linkshare" sc-spec
3269realtime-sc    = "realtime" sc-spec
3270upperlimit-sc  = "upperlimit" sc-spec
3271sc-spec        = ( bandwidth-spec |
3272                 "(" bandwidth-spec number bandwidth-spec ")" )
3273include        = "include" filename
3274.Ed
3275.Sh FILES
3276.Bl -tag -width "/etc/protocols" -compact
3277.It Pa /etc/hosts
3278Host name database.
3279.It Pa /etc/pf.conf
3280Default location of the ruleset file.
3281The file has to be created manually as it is not installed with a
3282standard installation.
3283.It Pa /etc/pf.os
3284Default location of OS fingerprints.
3285.It Pa /etc/protocols
3286Protocol name database.
3287.It Pa /etc/services
3288Service name database.
3289.El
3290.Sh SEE ALSO
3291.Xr altq 4 ,
3292.Xr carp 4 ,
3293.Xr icmp 4 ,
3294.Xr icmp6 4 ,
3295.Xr ip 4 ,
3296.Xr ip6 4 ,
3297.Xr pf 4 ,
3298.Xr pfsync 4 ,
3299.Xr tcp 4 ,
3300.Xr udp 4 ,
3301.Xr hosts 5 ,
3302.Xr pf.os 5 ,
3303.Xr protocols 5 ,
3304.Xr services 5 ,
3305.Xr ftp-proxy 8 ,
3306.Xr pfctl 8 ,
3307.Xr pflogd 8
3308.Sh HISTORY
3309The
3310.Nm
3311file format first appeared in
3312.Ox 3.0 .
3313