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