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