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