Bring the 'probability' keyword into PF from NetBSD. This feature allows
[dragonfly.git] / usr.sbin / pfctl / pf.conf.5
CommitLineData
95cc27f0 1.\" $OpenBSD: pf.conf.5,v 1.291 2004/02/04 19:38:30 jmc Exp $
75fda04a 2.\" $DragonFly: src/usr.sbin/pfctl/pf.conf.5,v 1.12 2008/04/06 21:12:40 dillon Exp $
95cc27f0
JS
3.\"
4.\" Copyright (c) 2002, Daniel Hartmeier
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" - Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" - Redistributions in binary form must reproduce the above
14.\" copyright notice, this list of conditions and the following
15.\" disclaimer in the documentation and/or other materials provided
16.\" with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
24.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
28.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29.\" POSSIBILITY OF SUCH DAMAGE.
30.\"
17312218 31.Dd April 6, 2008
95cc27f0
JS
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
9b5a9965 42.Nm .
95cc27f0
JS
43.Sh STATEMENT ORDER
44There are seven types of statements in
9b5a9965 45.Nm :
95cc27f0
JS
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
9b5a9965 51.Nm .
95cc27f0
JS
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.
17312218 57.It Cm Traffic Normalization Li (e.g.\& Em scrub )
95cc27f0
JS
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
9b5a9965 75.Nm
95cc27f0
JS
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
9b5a9965 149.Nm
95cc27f0
JS
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
9b5a9965 155.Nm
95cc27f0
JS
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
3867d280 179.Xr securelevel 8
95cc27f0
JS
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
17312218 447States are bound to interface group (i.e., ppp)
95cc27f0
JS
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
9b5a9965 635.Nm ,
95cc27f0
JS
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.
5950bf01
MD
701.It Ar fairq
702Fair Queue.
703.Ar Queues
704are flat attached to the interface, thus,
705.Ar queues
706cannot have further child
707.Ar queues .
708Each queue must be given a unique priority and one must be marked
709as the default queue.
710Each queue implements a number of buckets (default 256) which sorts the
711traffic based on a hash key generated by the
712.Ar keep state
17312218
SW
713facility in your pass rules.
714Each bucket contains a list of packets controlled by
5950bf01
MD
715.Ar qlimit .
716In order for
717.Ar fairq
718to function properly,
719.Ar keep state
720must be enabled on most of the rule sets that route packets to the queue.
721.Pp
722Packet selection operates as follows:
17312218
SW
723The queues are scanned from highest priority to lowest priority.
724If a queue has pending packets and has not reached its bandwidth limit the
5950bf01
MD
725scan stops and a packet is selected from that queue.
726If a queue has reached its bandwidth limit the scan continues searching for
17312218
SW
727other, lower priority queues which have not.
728If no queue is found to be
5950bf01
MD
729suitable then the highest priority queue with pending packets is used
730regardless of whether it has reached its bandwidth limit or not.
731.Pp
732A
733.Ar fairq
734round robins between its buckets, extracting one packet from each bucket.
735This essentially prevents large backlogs of packets from high volume
736connections from destroying the interactive response of other connections.
737.Pp
738The
739.Ar bandwidth
740parameter for a
741.Ar fairq
742is guaranteed minimum and more will be used if no higher priority traffic is
17312218
SW
743present.
744Creating a queue with one bucket as a catch-all for pass rules
5950bf01
MD
745not characterized by
746.Ar keep state
17312218
SW
747is supported.
748Such a queue serves as a basic priority queue with a bandwidth
5950bf01 749specification.
95cc27f0
JS
750.El
751.Pp
752The interfaces on which queueing should be activated are declared using
753the
754.Ar altq on
755declaration.
756.Ar altq on
757has the following keywords:
758.Bl -tag -width xxxx
759.It Ar <interface>
760Queueing is enabled on the named interface.
761.It Ar <scheduler>
762Specifies which queueing scheduler to use.
763Currently supported values
764are
765.Ar cbq
766for Class Based Queueing,
767.Ar priq
5950bf01 768for Priority Queueing,
95cc27f0 769.Ar hfsc
5950bf01
MD
770for the Hierarchical Fair Service Curve scheduler, and
771.Ar fairq
772for the Fair Queueing.
95cc27f0
JS
773.It Ar bandwidth <bw>
774The maximum bitrate for all queues on an
775interface may be specified using the
776.Ar bandwidth
777keyword.
778The value can be specified as an absolute value or as a
779percentage of the interface bandwidth.
780When using an absolute value, the suffixes
781.Ar b ,
782.Ar Kb ,
783.Ar Mb ,
784and
785.Ar Gb
786are used to represent bits, kilobits, megabits, and
787gigabits per second, respectively.
788The value must not exceed the interface bandwidth.
789If
790.Ar bandwidth
791is not specified, the interface bandwidth is used.
5950bf01
MD
792.Pp
793When used with
794.Ar fairq ,
795.Ar bandwidth
796specifies a guaranteed minimum but the fairq is allowed to exceed it.
95cc27f0
JS
797.It Ar qlimit <limit>
798The maximum number of packets held in the queue.
799The default is 50.
800.It Ar tbrsize <size>
801Adjusts the size, in bytes, of the token bucket regulator.
802If not specified, heuristics based on the
803interface bandwidth are used to determine the size.
804.It Ar queue <list>
805Defines a list of subqueues to create on an interface.
806.El
807.Pp
808In the following example, the interface dc0
809should queue up to 5 Mbit/s in four second-level queues using
810Class Based Queueing.
811Those four queues will be shown in a later example.
812.Bd -literal -offset indent
813altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh }
814.Ed
815.Pp
816Once interfaces are activated for queueing using the
817.Ar altq
818directive, a sequence of
819.Ar queue
820directives may be defined.
821The name associated with a
822.Ar queue
823must match a queue defined in the
824.Ar altq
17312218 825directive (e.g.\& mail), or, except for the
95cc27f0
JS
826.Ar priq
827.Ar scheduler ,
828in a parent
829.Ar queue
830declaration.
831The following keywords can be used:
832.Bl -tag -width xxxx
833.It Ar on <interface>
834Specifies the interface the queue operates on.
835If not given, it operates on all matching interfaces.
836.It Ar bandwidth <bw>
837Specifies the maximum bitrate to be processed by the queue.
838This value must not exceed the value of the parent
839.Ar queue
840and can be specified as an absolute value or a percentage of the parent
841queue's bandwidth.
842The
843.Ar priq
844scheduler does not support bandwidth specification.
5950bf01
MD
845The
846.Ar fairq
847scheduler uses the bandwidth specification as a guaranteed minimum and
848may exceed it.
95cc27f0
JS
849.It Ar priority <level>
850Between queues a priority level can be set.
851For
5950bf01 852.Ar cbq ,
95cc27f0 853.Ar hfsc ,
5950bf01
MD
854and
855.Ar fairq
95cc27f0
JS
856the range is 0 to 7 and for
857.Ar priq ,
858the range is 0 to 15.
859The default for all is 1.
860.Ar Priq
861queues with a higher priority are always served first.
5950bf01
MD
862.Ar Fairq
863queues with a higher priority are served first unless they exceed their
864bandwidth specification.
95cc27f0
JS
865.Ar Cbq
866and
867.Ar Hfsc
868queues with a higher priority are preferred in the case of overload.
869.It Ar qlimit <limit>
870The maximum number of packets held in the queue.
871The default is 50.
5950bf01
MD
872When used with a
873.Ar fairq
874this specified the maximum number of packets held per bucket.
95cc27f0
JS
875.El
876.Pp
877The
878.Ar scheduler
879can get additional parameters with
880.Ar <scheduler> Ns Li (\& Ar <parameters> No ) .
881Parameters are as follows:
882.Bl -tag -width Fl
883.It Ar default
884Packets not matched by another queue are assigned to this one.
885Exactly one default queue is required.
886.It Ar red
887Enable RED (Random Early Detection) on this queue.
888RED drops packets with a probability proportional to the average
889queue length.
890.It Ar rio
891Enables RIO on this queue.
892RIO is RED with IN/OUT, thus running
893RED two times more than RIO would achieve the same effect.
894RIO is currently not supported in the GENERIC kernel.
895.It Ar ecn
896Enables ECN (Explicit Congestion Notification) on this queue.
897ECN implies RED.
898.El
899.Pp
900The
5950bf01
MD
901.Ar fairq
902.Ar scheduler
903supports the following additional options:
904.Bl -tag -width Fl
905.It Ar buckets <number>
17312218
SW
906Specify the number of buckets, from 1 to 2048 in powers of 2.
907A bucket size of 1 causes a
5950bf01
MD
908.Ar fairq
909to essentially degenerate into a priority queue.
910.It Ar linkshare <sc>
17312218
SW
911The bandwidth share of a backlogged queue.
912This option is parsed but not yet supported.
5950bf01
MD
913.It Ar hogs <bandwidth>
914This option allows low bandwidth connections to burst up to the specified
915bandwidth by not advancing the round robin when taking packets out of
916the related queue.
917When using this option a small value no greater then 1/20 available interface
918bandwidth is recommended.
919.El
920.Pp
921The
95cc27f0
JS
922.Ar cbq
923.Ar scheduler
924supports an additional option:
925.Bl -tag -width Fl
926.It Ar borrow
927The queue can borrow bandwidth from the parent.
928.El
929.Pp
930The
931.Ar hfsc
932.Ar scheduler
933supports some additional options:
934.Bl -tag -width Fl
935.It Ar realtime <sc>
936The minimum required bandwidth for the queue.
937.It Ar upperlimit <sc>
938The maximum allowed bandwidth for the queue.
939.It Ar linkshare <sc>
940The bandwidth share of a backlogged queue.
941.El
942.Pp
943<sc> is an acronym for
944.Ar service curve .
945.Pp
946The format for service curve specifications is
947.Ar ( m1 , d , m2 ) .
948.Ar m2
949controls the bandwidth assigned to the queue.
950.Ar m1
951and
952.Ar d
953are optional and can be used to control the initial bandwidth assignment.
954For the first
955.Ar d
956milliseconds the queue gets the bandwidth given as
957.Ar m1 ,
958afterwards the value given in
959.Ar m2 .
960.Pp
961Furthermore, with
962.Ar cbq
963and
964.Ar hfsc ,
965child queues can be specified as in an
966.Ar altq
967declaration, thus building a tree of queues using a part of
968their parent's bandwidth.
969.Pp
970Packets can be assigned to queues based on filter rules by using the
971.Ar queue
972keyword.
973Normally only one
974.Ar queue
975is specified; when a second one is specified it will instead be used for
976packets which have a
977.Em TOS
978of
979.Em lowdelay
980and for TCP ACKs with no data payload.
981.Pp
982To continue the previous example, the examples below would specify the
983four referenced
984queues, plus a few child queues.
985Interactive
986.Xr ssh 1
987sessions get priority over bulk transfers like
988.Xr scp 1
989and
990.Xr sftp 1 .
991The queues may then be referenced by filtering rules (see
992.Sx PACKET FILTERING
993below).
994.Bd -literal
995queue std bandwidth 10% cbq(default)
996queue http bandwidth 60% priority 2 cbq(borrow red) \e
997 { employees, developers }
998queue developers bandwidth 75% cbq(borrow)
999queue employees bandwidth 15%
1000queue mail bandwidth 10% priority 0 cbq(borrow ecn)
1001queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk }
1002queue ssh_interactive priority 7
1003queue ssh_bulk priority 0
1004
1005block return out on dc0 inet all queue std
1006pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e
1007 keep state queue developers
1008pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e
1009 keep state queue employees
1010pass out on dc0 inet proto tcp from any to any port 22 \e
1011 keep state queue(ssh_bulk, ssh_interactive)
1012pass out on dc0 inet proto tcp from any to any port 25 \e
1013 keep state queue mail
1014.Ed
1015.Sh TRANSLATION
1016Translation rules modify either the source or destination address of the
1017packets associated with a stateful connection.
1018A stateful connection is automatically created to track packets matching
1019such a rule as long as they are not blocked by the filtering section of
9b5a9965 1020.Nm .
95cc27f0
JS
1021The translation engine modifies the specified address and/or port in the
1022packet, recalculates IP, TCP and UDP checksums as necessary, and passes it to
1023the packet filter for evaluation.
1024.Pp
1025Since translation occurs before filtering the filter
1026engine will see packets as they look after any
17312218
SW
1027addresses and ports have been translated.
1028Filter rules will therefore have to filter based on the translated
95cc27f0
JS
1029address and port number.
1030Packets that match a translation rule are only automatically passed if
1031the
1032.Ar pass
1033modifier is given, otherwise they are
1034still subject to
1035.Ar block
1036and
1037.Ar pass
1038rules.
1039.Pp
1040The state entry created permits
1041.Xr pf 4
1042to keep track of the original address for traffic associated with that state
1043and correctly direct return traffic for that connection.
1044.Pp
1045Various types of translation are possible with pf:
1046.Bl -tag -width xxxx
1047.It Ar binat
1048A
1049.Ar binat
1050rule specifies a bidirectional mapping between an external IP netblock
1051and an internal IP netblock.
1052.It Ar nat
1053A
1054.Ar nat
1055rule specifies that IP addresses are to be changed as the packet
1056traverses the given interface.
1057This technique allows one or more IP addresses
1058on the translating host to support network traffic for a larger range of
1059machines on an "inside" network.
1060Although in theory any IP address can be used on the inside, it is strongly
1061recommended that one of the address ranges defined by RFC 1918 be used.
1062These netblocks are:
1063.Bd -literal
106410.0.0.0 - 10.255.255.255 (all of net 10, i.e., 10/8)
1065172.16.0.0 - 172.31.255.255 (i.e., 172.16/12)
1066192.168.0.0 - 192.168.255.255 (i.e., 192.168/16)
1067.Ed
1068.It Pa rdr
1069The packet is redirected to another destination and possibly a
1070different port.
1071.Ar rdr
1072rules can optionally specify port ranges instead of single ports.
1073rdr ... port 2000:2999 -> ... port 4000
1074redirects ports 2000 to 2999 (inclusive) to port 4000.
1075rdr ... port 2000:2999 -> ... port 4000:*
1076redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999.
1077.El
1078.Pp
1079In addition to modifying the address, some translation rules may modify
1080source or destination ports for
1081.Xr tcp 4
1082or
1083.Xr udp 4
1084connections; implicitly in the case of
1085.Ar nat
1086rules and explicitly in the case of
1087.Ar rdr
1088rules.
1089Port numbers are never translated with a
1090.Ar binat
1091rule.
1092.Pp
1093For each packet processed by the translator, the translation rules are
1094evaluated in sequential order, from first to last.
1095The first matching rule decides what action is taken.
1096.Pp
1097The
1098.Ar no
1099option prefixed to a translation rule causes packets to remain untranslated,
1100much in the same way as
1101.Ar drop quick
1102works in the packet filter (see below).
1103If no rule matches the packet it is passed to the filter engine unmodified.
1104.Pp
1105Translation rules apply only to packets that pass through
1106the specified interface, and if no interface is specified,
1107translation is applied to packets on all interfaces.
1108For instance, redirecting port 80 on an external interface to an internal
1109web server will only work for connections originating from the outside.
1110Connections to the address of the external interface from local hosts will
1111not be redirected, since such packets do not actually pass through the
1112external interface.
1113Redirections cannot reflect packets back through the interface they arrive
1114on, they can only be redirected to hosts connected to different interfaces
1115or to the firewall itself.
1116.Pp
1117Note that redirecting external incoming connections to the loopback
1118address, as in
1119.Bd -literal -offset indent
1120rdr on ne3 inet proto tcp to port 8025 -> 127.0.0.1 port 25
1121.Ed
1122.Pp
1123will effectively allow an external host to connect to daemons
1124bound solely to the loopback address, circumventing the traditional
1125blocking of such connections on a real interface.
1126Unless this effect is desired, any of the local non-loopback addresses
1127should be used as redirection target instead, which allows external
1128connections only to daemons bound to this address or not bound to
1129any address.
1130.Pp
1131See
1132.Sx TRANSLATION EXAMPLES
1133below.
1134.Sh PACKET FILTERING
1135.Xr pf 4
1136has the ability to
1137.Ar block
1138and
1139.Ar pass
1140packets based on attributes of their layer 3 (see
1141.Xr ip 4
1142and
1143.Xr ip6 4 )
1144and layer 4 (see
1145.Xr icmp 4 ,
1146.Xr icmp6 4 ,
1147.Xr tcp 4 ,
1148.Xr udp 4 )
1149headers.
1150In addition, packets may also be
1151assigned to queues for the purpose of bandwidth control.
1152.Pp
1153For each packet processed by the packet filter, the filter rules are
1154evaluated in sequential order, from first to last.
1155The last matching rule decides what action is taken.
1156.Pp
1157The following actions can be used in the filter:
1158.Bl -tag -width xxxx
1159.It Ar block
1160The packet is blocked.
1161There are a number of ways in which a
1162.Ar block
1163rule can behave when blocking a packet.
1164The default behaviour is to
1165.Ar drop
1166packets silently, however this can be overridden or made
1167explicit either globally, by setting the
1168.Ar block-policy
1169option, or on a per-rule basis with one of the following options:
1170.Pp
1171.Bl -tag -width xxxx -compact
1172.It Ar drop
1173The packet is silently dropped.
1174.It Ar return-rst
1175This applies only to
1176.Xr tcp 4
1177packets, and issues a TCP RST which closes the
1178connection.
1179.It Ar return-icmp
1180.It Ar return-icmp6
1181This causes ICMP messages to be returned for packets which match the rule.
1182By default this is an ICMP UNREACHABLE message, however this
1183can be overridden by specifying a message as a code or number.
1184.It Ar return
1185This causes a TCP RST to be returned for
1186.Xr tcp 4
1187packets and an ICMP UNREACHABLE for UDP and other packets.
1188.El
1189.Pp
1190Options returning packets have no effect if
1191.Xr pf 4
1192operates on a
1193.Xr bridge 4 .
1194.It Ar pass
1195The packet is passed.
1196.El
1197.Pp
1198If no rule matches the packet, the default action is
1199.Ar pass .
1200.Pp
1201To block everything by default and only pass packets
1202that match explicit rules, one uses
1203.Bd -literal -offset indent
1204block all
1205.Ed
1206.Pp
1207as the first filter rule.
1208.Pp
1209See
1210.Sx FILTER EXAMPLES
1211below.
1212.Sh PARAMETERS
1213The rule parameters specify the packets to which a rule applies.
1214A packet always comes in on, or goes out through, one interface.
1215Most parameters are optional.
1216If a parameter is specified, the rule only applies to packets with
1217matching attributes.
1218Certain parameters can be expressed as lists, in which case
1219.Xr pfctl 8
1220generates all needed rule combinations.
1221.Bl -tag -width xxxx
1222.It Ar in No or Ar out
1223This rule applies to incoming or outgoing packets.
1224If neither
1225.Ar in
1226nor
1227.Ar out
1228are specified, the rule will match packets in both directions.
1229.It Ar log
1230In addition to the action specified, a log message is generated.
1231All packets for that connection are logged, unless the
1232.Ar keep state ,
1233.Ar modulate state
1234or
1235.Ar synproxy state
1236options are specified, in which case only the
1237packet that establishes the state is logged.
1238(See
1239.Ar keep state ,
1240.Ar modulate state
1241and
1242.Ar synproxy state
1243below).
1244The logged packets are sent to the
1245.Xr pflog 4
1246interface.
1247This interface is monitored by the
1248.Xr pflogd 8
1249logging daemon, which dumps the logged packets to the file
1250.Pa /var/log/pflog
1251in
1252.Xr pcap 3
1253binary format.
1254.It Ar log-all
1255Used with
1256.Ar keep state ,
1257.Ar modulate state
1258or
1259.Ar synproxy state
1260rules to force logging of all packets for a connection.
1261As with
1262.Ar log ,
1263packets are logged to
1264.Xr pflog 4 .
1265.It Ar quick
1266If a packet matches a rule which has the
1267.Ar quick
1268option set, this rule
1269is considered the last matching rule, and evaluation of subsequent rules
1270is skipped.
1271.It Ar on <interface>
1272This rule applies only to packets coming in on, or going out through, this
1273particular interface.
1274It is also possible to simply give the interface driver name, like ppp or fxp,
1275to make the rule match packets flowing through a group of interfaces.
1276.It Ar <af>
1277This rule applies only to packets of this address family.
1278Supported values are
1279.Ar inet
1280and
1281.Ar inet6 .
1282.It Ar proto <protocol>
1283This rule applies only to packets of this protocol.
1284Common protocols are
1285.Xr icmp 4 ,
1286.Xr icmp6 4 ,
1287.Xr tcp 4 ,
1288and
1289.Xr udp 4 .
1290For a list of all the protocol name to number mappings used by
1291.Xr pfctl 8 ,
1292see the file
f1481abe 1293.Pa /etc/protocols .
95cc27f0
JS
1294.It Xo
1295.Ar from <source> port <source> os <source>
1296.Ar to <dest> port <dest>
1297.Xc
1298This rule applies only to packets with the specified source and destination
1299addresses and ports.
1300.Pp
1301Addresses can be specified in CIDR notation (matching netblocks), as
1302symbolic host names or interface names, or as any of the following keywords:
1303.Pp
1304.Bl -tag -width xxxxxxxxxxxx -compact
1305.It Ar any
1306Any address.
1307.It Ar no-route
1308Any address which is not currently routable.
1309.It Ar <table>
1310Any address that matches the given table.
1311.El
1312.Pp
1313Interface names can have modifiers appended:
1314.Pp
1315.Bl -tag -width xxxxxxxxxxxx -compact
1316.It Ar :network
1317Translates to the network(s) attached to the interface.
1318.It Ar :broadcast
1319Translates to the interface's broadcast address(es).
1320.It Ar :peer
1321Translates to the point to point interface's peer address(es).
1322.It Ar :0
1323Do not include interface aliases.
1324.El
1325.Pp
1326Host names may also have the
1327.Ar :0
1328option appended to restrict the name resolution to the first of each
1329v4 and v6 address found.
1330.Pp
1331Host name resolution and interface to address translation are done at
1332ruleset load-time.
1333When the address of an interface (or host name) changes (under DHCP or PPP,
1334for instance), the ruleset must be reloaded for the change to be reflected
1335in the kernel.
1336Surrounding the interface name (and optional modifiers) in parentheses
1337changes this behaviour.
1338When the interface name is surrounded by parentheses, the rule is
1339automatically updated whenever the interface changes its address.
1340The ruleset does not need to be reloaded.
1341This is especially useful with
1342.Ar nat .
1343.Pp
1344Ports can be specified either by number or by name.
1345For example, port 80 can be specified as
1346.Em www .
1347For a list of all port name to number mappings used by
1348.Xr pfctl 8 ,
1349see the file
1350.Pa /etc/services .
1351.Pp
1352Ports and ranges of ports are specified by using these operators:
1353.Bd -literal -offset indent
1354= (equal)
1355!= (unequal)
1356< (less than)
1357<= (less than or equal)
1358> (greater than)
1359>= (greater than or equal)
1360: (range including boundaries)
1361>< (range excluding boundaries)
1362<> (except range)
1363.Ed
1364.Pp
1365><, <> and :
1366are binary operators (they take two arguments).
1367For instance:
1368.Bl -tag -width Fl
1369.It Ar port 2000:2004
1370means
aa0d550a 1371.Sq all ports \(>= 2000 and \(<= 2004 ,
95cc27f0
JS
1372hence ports 2000, 2001, 2002, 2003 and 2004.
1373.It Ar port 2000 >< 2004
1374means
1375.Sq all ports > 2000 and < 2004 ,
1376hence ports 2001, 2002 and 2003.
1377.It Ar port 2000 <> 2004
1378means
1379.Sq all ports < 2000 or > 2004 ,
1380hence ports 1-1999 and 2005-65535.
1381.El
1382.Pp
1383The operating system of the source host can be specified in the case of TCP
1384rules with the
1385.Ar OS
1386modifier.
1387See the
1388.Sx OPERATING SYSTEM FINGERPRINTING
1389section for more information.
1390.Pp
1391The host, port and OS specifications are optional, as in the following examples:
1392.Bd -literal -offset indent
1393pass in all
1394pass in from any to any
1395pass in proto tcp from any port <= 1024 to any
1396pass in proto tcp from any to any port 25
1397pass in proto tcp from 10.0.0.0/8 port > 1024 \e
1398 to ! 10.1.2.3 port != ssh
1399pass in proto tcp from any os "OpenBSD" flags S/SA
1400.Ed
1401.It Ar all
1402This is equivalent to "from any to any".
1403.It Ar group <group>
1404Similar to
1405.Ar user ,
1406this rule only applies to packets of sockets owned by the specified group.
1407.It Ar user <user>
1408This rule only applies to packets of sockets owned by the specified user.
1409For outgoing connections initiated from the firewall, this is the user
1410that opened the connection.
1411For incoming connections to the firewall itself, this is the user that
1412listens on the destination port.
1413For forwarded connections, where the firewall is not a connection endpoint,
1414the user and group are
1415.Em unknown .
1416.Pp
1417All packets, both outgoing and incoming, of one connection are associated
1418with the same user and group.
1419Only TCP and UDP packets can be associated with users; for other protocols
1420these parameters are ignored.
1421.Pp
1422User and group refer to the effective (as opposed to the real) IDs, in
1423case the socket is created by a setuid/setgid process.
1424User and group IDs are stored when a socket is created;
1425when a process creates a listening socket as root (for instance, by
1426binding to a privileged port) and subsequently changes to another
1427user ID (to drop privileges), the credentials will remain root.
1428.Pp
1429User and group IDs can be specified as either numbers or names.
1430The syntax is similar to the one for ports.
1431The value
1432.Em unknown
1433matches packets of forwarded connections.
1434.Em unknown
1435can only be used with the operators
1436.Cm =
1437and
1438.Cm != .
1439Other constructs like
1440.Cm user >= unknown
1441are invalid.
1442Forwarded packets with unknown user and group ID match only rules
1443that explicitly compare against
1444.Em unknown
1445with the operators
1446.Cm =
1447or
1448.Cm != .
1449For instance
1450.Cm user >= 0
1451does not match forwarded packets.
1452The following example allows only selected users to open outgoing
1453connections:
1454.Bd -literal -offset indent
1455block out proto { tcp, udp } all
1456pass out proto { tcp, udp } all \e
1457 user { < 1000, dhartmei } keep state
1458.Ed
1459.It Ar flags <a>/<b> | /<b>
1460This rule only applies to TCP packets that have the flags
1461.Ar <a>
1462set out of set
1463.Ar <b> .
1464Flags not specified in
1465.Ar <b>
1466are ignored.
1467The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R.
1468.Bl -tag -width Fl
1469.It Ar flags S/S
1470Flag SYN is set.
1471The other flags are ignored.
1472.It Ar flags S/SA
1473Out of SYN and ACK, exactly SYN may be set.
1474SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not.
1475This is more restrictive than the previous example.
1476.It Ar flags /SFRA
1477If the first set is not specified, it defaults to none.
1478All of SYN, FIN, RST and ACK must be unset.
1479.El
1480.It Ar icmp-type <type> code <code>
1481.It Ar icmp6-type <type> code <code>
1482This rule only applies to ICMP or ICMPv6 packets with the specified type
1483and code.
1484This parameter is only valid for rules that cover protocols ICMP or
1485ICMP6.
1486The protocol and the ICMP type indicator (icmp-type or icmp6-type)
1487must match.
1488.It Ar allow-opts
1489By default, packets which contain IP options are blocked.
1490When
1491.Ar allow-opts
1492is specified for a
1493.Ar pass
1494rule, packets that pass the filter based on that rule (last matching)
1495do so even if they contain IP options.
1496For packets that match state, the rule that initially created the
1497state is used.
1498The implicit
1499.Ar pass
1500rule that is used when a packet does not match any rules does not
1501allow IP options.
1502.It Ar label <string>
1503Adds a label (name) to the rule, which can be used to identify the rule.
1504For instance,
1505pfctl -s labels
1506shows per-rule statistics for rules that have labels.
1507.Pp
1508The following macros can be used in labels:
1509.Pp
1510.Bl -tag -width $srcaddr -compact -offset indent
1511.It Ar $if
1512The interface.
1513.It Ar $srcaddr
1514The source IP address.
1515.It Ar $dstaddr
1516The destination IP address.
1517.It Ar $srcport
1518The source port specification.
1519.It Ar $dstport
1520The destination port specification.
1521.It Ar $proto
1522The protocol name.
1523.It Ar $nr
1524The rule number.
1525.El
1526.Pp
1527For example:
1528.Bd -literal -offset indent
1529ips = \&"{ 1.2.3.4, 1.2.3.5 }\&"
1530pass in proto tcp from any to $ips \e
1531 port > 1023 label \&"$dstaddr:$dstport\&"
1532.Ed
1533.Pp
1534expands to
1535.Bd -literal -offset indent
1536pass in inet proto tcp from any to 1.2.3.4 \e
1537 port > 1023 label \&"1.2.3.4:>1023\&"
1538pass in inet proto tcp from any to 1.2.3.5 \e
1539 port > 1023 label \&"1.2.3.5:>1023\&"
1540.Ed
1541.Pp
1542The macro expansion for the
1543.Ar label
1544directive occurs only at configuration file parse time, not during runtime.
1545.It Ar queue <queue> | ( <queue> , <queue> )
1546Packets matching this rule will be assigned to the specified queue.
1547If two queues are given, packets which have a
1548.Em tos
1549of
1550.Em lowdelay
1551and TCP ACKs with no data payload will be assigned to the second one.
1552See
1553.Sx QUEUEING
1554for setup details.
1555.Pp
1556For example:
1557.Bd -literal -offset indent
1558pass in proto tcp to port 25 queue mail
1559pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio)
1560.Ed
1561.It Ar tag <string>
1562Packets matching this rule will be tagged with the
1563specified string.
1564The tag acts as an internal marker that can be used to
1565identify these packets later on.
1566This can be used, for example, to provide trust between
1567interfaces and to determine if packets have been
1568processed by translation rules.
1569Tags are
1570.Qq sticky ,
1571meaning that the packet will be tagged even if the rule
1572is not the last matching rule.
1573Further matching rules can replace the tag with a
1574new one but will not remove a previously applied tag.
1575A packet is only ever assigned one tag at a time.
1576.Ar pass
1577rules that use the
1578.Ar tag
1579keyword must also use
1580.Ar keep state ,
1581.Ar modulate state
1582or
1583.Ar synproxy state .
1584Packet tagging can be done during
1585.Ar nat ,
1586.Ar rdr ,
1587or
1588.Ar binat
1589rules in addition to filter rules.
1590Tags take the same macros as labels (see above).
1591.It Ar tagged <string>
1592Used with filter rules to specify that packets must already
1593be tagged with the given tag in order to match the rule.
1594Inverse tag matching can also be done
1595by specifying the
1596.Cm !\&
1597operator before the
1598.Ar tagged
1599keyword.
75fda04a
MD
1600.It Ar probability <number>
1601A probability attribute can be attached to a rule, with a value set between
16020 and 1, bounds not included.
1603In that case, the rule will be honoured using the given probability value
1604only.
1605For example, the following rule will drop 20% of incoming ICMP packets:
1606.Bd -literal -offset indent
1607block in proto icmp probability 20%
1608.Ed
95cc27f0
JS
1609.El
1610.Sh ROUTING
1611If a packet matches a rule with a route option set, the packet filter will
1612route the packet according to the type of route option.
1613When such a rule creates state, the route option is also applied to all
1614packets matching the same connection.
1615.Bl -tag -width xxxx
1616.It Ar fastroute
1617The
1618.Ar fastroute
1619option does a normal route lookup to find the next hop for the packet.
1620.It Ar route-to
1621The
1622.Ar route-to
1623option routes the packet to the specified interface with an optional address
1624for the next hop.
1625When a
1626.Ar route-to
1627rule creates state, only packets that pass in the same direction as the
1628filter rule specifies will be routed in this way.
1629Packets passing in the opposite direction (replies) are not affected
1630and are routed normally.
1631.It Ar reply-to
1632The
1633.Ar reply-to
1634option is similar to
1635.Ar route-to ,
1636but routes packets that pass in the opposite direction (replies) to the
1637specified interface.
1638Opposite direction is only defined in the context of a state entry, and
1639.Ar route-to
1640is useful only in rules that create state.
1641It can be used on systems with multiple external connections to
1642route all outgoing packets of a connection through the interface
1643the incoming connection arrived through (symmetric routing enforcement).
1644.It Ar dup-to
1645The
1646.Ar dup-to
1647option creates a duplicate of the packet and routes it like
1648.Ar route-to .
1649The original packet gets routed as it normally would.
1650.El
1651.Sh POOL OPTIONS
1652For
1653.Ar nat
1654and
1655.Ar rdr
1656rules, (as well as for the
1657.Ar route-to ,
1658.Ar reply-to
1659and
1660.Ar dup-to
1661rule options) for which there is a single redirection address which has a
1662subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP
1663address), a variety of different methods for assigning this address can be
1664used:
1665.Bl -tag -width xxxx
1666.It Ar bitmask
1667The
1668.Ar bitmask
1669option applies the network portion of the redirection address to the address
1670to be modified (source with
1671.Ar nat ,
1672destination with
1673.Ar rdr ) .
1674.It Ar random
1675The
1676.Ar random
1677option selects an address at random within the defined block of addresses.
1678.It Ar source-hash
1679The
1680.Ar source-hash
1681option uses a hash of the source address to determine the redirection address,
1682ensuring that the redirection address is always the same for a given source.
1683An optional key can be specified after this keyword either in hex or as a
1684string; by default
1685.Xr pfctl 8
1686randomly generates a key for source-hash every time the
1687ruleset is reloaded.
1688.It Ar round-robin
1689The
1690.Ar round-robin
1691option loops through the redirection address(es).
1692.Pp
1693When more than one redirection address is specified,
1694.Ar round-robin
1695is the only permitted pool type.
1696.It Ar static-port
1697With
1698.Ar nat
1699rules, the
1700.Ar static-port
1701option prevents
1702.Xr pf 4
1703from modifying the source port on TCP and UDP packets.
1704.El
1705.Pp
1706Additionally, the
1707.Ar sticky-address
1708option can be specified to help ensure that multiple connections from the
1709same source are mapped to the same redirection address.
1710This option can be used with the
1711.Ar random
1712and
1713.Ar round-robin
1714pool options.
1715Note that by default these associations are destroyed as soon as there are
1716no longer states which refer to them; in order to make the mappings last
1717beyond the lifetime of the states, increase the global options with
1718.Ar set timeout source-track
1719See
1720.Sx STATEFUL TRACKING OPTIONS
1721for more ways to control the source tracking.
1722.Sh STATEFUL INSPECTION
1723.Xr pf 4
1724is a stateful packet filter, which means it can track the state of
1725a connection.
1726Instead of passing all traffic to port 25, for instance, it is possible
1727to pass only the initial packet, and then begin to keep state.
1728Subsequent traffic will flow because the filter is aware of the connection.
1729.Pp
1730If a packet matches a
1731.Ar pass ... keep state
1732rule, the filter creates a state for this connection and automatically
1733lets pass all subsequent packets of that connection.
1734.Pp
1735Before any rules are evaluated, the filter checks whether the packet
1736matches any state.
1737If it does, the packet is passed without evaluation of any rules.
1738.Pp
1739States are removed after the connection is closed or has timed out.
1740.Pp
1741This has several advantages.
1742Comparing a packet to a state involves checking its sequence numbers.
1743If the sequence numbers are outside the narrow windows of expected
1744values, the packet is dropped.
1745This prevents spoofing attacks, such as when an attacker sends packets with
1746a fake source address/port but does not know the connection's sequence
1747numbers.
1748.Pp
1749Also, looking up states is usually faster than evaluating rules.
1750If there are 50 rules, all of them are evaluated sequentially in O(n).
1751Even with 50000 states, only 16 comparisons are needed to match a
1752state, since states are stored in a binary search tree that allows
1753searches in O(log2 n).
1754.Pp
1755For instance:
1756.Bd -literal -offset indent
1757block all
1758pass out proto tcp from any to any flags S/SA keep state
1759pass in proto tcp from any to any port 25 flags S/SA keep state
1760.Ed
1761.Pp
1762This ruleset blocks everything by default.
1763Only outgoing connections and incoming connections to port 25 are allowed.
1764The initial packet of each connection has the SYN
1765flag set, will be passed and creates state.
1766All further packets of these connections are passed if they match a state.
1767.Pp
1768By default, packets coming in and out of any interface can match a state,
1769but it is also possible to change that behaviour by assigning states to a
1770single interface or a group of interfaces.
1771.Pp
1772The default policy is specified by the
1773.Ar state-policy
1774global option, but this can be adjusted on a per-rule basis by adding one
1775of the
1776.Ar if-bound ,
1777.Ar group-bound
1778or
1779.Ar floating
1780keywords to the
1781.Ar keep state
1782option.
1783For example, if a rule is defined as:
1784.Bd -literal -offset indent
1785pass out on ppp from any to 10.12/16 keep state (group-bound)
1786.Ed
1787.Pp
1788A state created on ppp0 would match packets an all PPP interfaces,
1789but not packets flowing through fxp0 or any other interface.
1790.Pp
1791Keeping rules
1792.Ar floating
1793is the more flexible option when the firewall is in a dynamic routing
1794environment.
1795However, this has some security implications since a state created by one
1796trusted network could allow potentially hostile packets coming in from other
1797interfaces.
1798.Pp
1799Specifying
1800.Ar flags S/SA
1801restricts state creation to the initial SYN
1802packet of the TCP handshake.
1803One can also be less restrictive, and allow state creation from
1804intermediate
1805.Pq non-SYN
1806packets.
1807This will cause
1808.Xr pf 4
1809to synchronize to existing connections, for instance
1810if one flushes the state table.
1811.Pp
1812For UDP, which is stateless by nature,
1813.Ar keep state
1814will create state as well.
1815UDP packets are matched to states using only host addresses and ports.
1816.Pp
1817ICMP messages fall into two categories: ICMP error messages, which always
1818refer to a TCP or UDP packet, are matched against the referred to connection.
1819If one keeps state on a TCP connection, and an ICMP source quench message
1820referring to this TCP connection arrives, it will be matched to the right
1821state and get passed.
1822.Pp
1823For ICMP queries,
1824.Ar keep state
1825creates an ICMP state, and
1826.Xr pf 4
1827knows how to match ICMP replies to states.
1828For example,
1829.Bd -literal -offset indent
1830pass out inet proto icmp all icmp-type echoreq keep state
1831.Ed
1832.Pp
1833allows echo requests (such as those created by
1834.Xr ping 8 )
1835out, creates state, and matches incoming echo replies correctly to states.
1836.Pp
1837Note:
1838.Ar nat , binat No and Ar rdr
1839rules implicitly create state for connections.
1840.Sh STATE MODULATION
1841Much of the security derived from TCP is attributable to how well the
1842initial sequence numbers (ISNs) are chosen.
1843Some popular stack implementations choose
1844.Em very
1845poor ISNs and thus are normally susceptible to ISN prediction exploits.
1846By applying a
1847.Ar modulate state
1848rule to a TCP connection,
1849.Xr pf 4
1850will create a high quality random sequence number for each connection
1851endpoint.
1852.Pp
1853The
1854.Ar modulate state
1855directive implicitly keeps state on the rule and is
1856only applicable to TCP connections.
1857.Pp
1858For instance:
1859.Bd -literal -offset indent
1860block all
1861pass out proto tcp from any to any modulate state
1862pass in proto tcp from any to any port 25 flags S/SA modulate state
1863.Ed
1864.Pp
1865There are two caveats associated with state modulation:
1866A
1867.Ar modulate state
1868rule can not be applied to a pre-existing but unmodulated connection.
1869Such an application would desynchronize TCP's strict
1870sequencing between the two endpoints.
1871Instead,
1872.Xr pf 4
1873will treat the
1874.Ar modulate state
1875modifier as a
1876.Ar keep state
1877modifier and the pre-existing connection will be inferred without
1878the protection conferred by modulation.
1879.Pp
1880The other caveat affects currently modulated states when the state table
1881is lost (firewall reboot, flushing the state table, etc...).
1882.Xr pf 4
1883will not be able to infer a connection again after the state table flushes
1884the connection's modulator.
1885When the state is lost, the connection may be left dangling until the
1886respective endpoints time out the connection.
1887It is possible on a fast local network for the endpoints to start an ACK
1888storm while trying to resynchronize after the loss of the modulator.
1889Using a
1890.Ar flags S/SA
1891modifier on
1892.Ar modulate state
1893rules between fast networks is suggested to prevent ACK storms.
1894.Sh SYN PROXY
1895By default,
1896.Xr pf 4
1897passes packets that are part of a
1898.Xr tcp 4
1899handshake between the endpoints.
1900The
1901.Ar synproxy state
1902option can be used to cause
1903.Xr pf 4
1904itself to complete the handshake with the active endpoint, perform a handshake
1905with the passive endpoint, and then forward packets between the endpoints.
1906.Pp
1907No packets are sent to the passive endpoint before the active endpoint has
1908completed the handshake, hence so-called SYN floods with spoofed source
1909addresses will not reach the passive endpoint, as the sender can't complete the
1910handshake.
1911.Pp
1912The proxy is transparent to both endpoints, they each see a single
1913connection from/to the other endpoint.
1914.Xr pf 4
1915chooses random initial sequence numbers for both handshakes.
1916Once the handshakes are completed, the sequence number modulators
1917(see previous section) are used to translate further packets of the
1918connection.
1919Hence,
1920.Ar synproxy state
1921includes
1922.Ar modulate state
1923and
1924.Ar keep state .
1925.Pp
1926Rules with
1927.Ar synproxy
1928will not work if
1929.Xr pf 4
1930operates on a
1931.Xr bridge 4 .
1932.Pp
1933Example:
1934.Bd -literal -offset indent
1935pass in proto tcp from any to any port www flags S/SA synproxy state
1936.Ed
1937.Sh STATEFUL TRACKING OPTIONS
1938All three of
1939.Ar keep state ,
1940.Ar modulate state
1941and
1942.Ar synproxy state
1943support the following options:
1944.Pp
1945.Bl -tag -width xxxx -compact
1946.It Ar max <number>
1947Limits the number of concurrent states the rule may create.
1948When this limit is reached, further packets matching the rule that would
1949create state are dropped, until existing states time out.
1950.It Ar no-sync
1951Prevent state changes for states created by this rule from appearing on the
1952.Xr pfsync 4
1953interface.
1954.It Ar <timeout> <seconds>
1955Changes the timeout values used for states created by this rule.
1956.Pp
1957When the
1958.Ar source-track
1959keyword is specified, the number of states per source IP is tracked.
1960The following limits can be set:
1961.Pp
1962.Bl -tag -width xxxx -compact
1963.It Ar max-src-nodes
1964Limits the maximum number of source addresses which can simultaneously
1965have state table entries.
1966.It Ar max-src-states
1967Limits the maximum number of simultaneous state entries that a single
1968source address can create with this rule.
1969.El
1970For a list of all valid timeout names, see
1971.Sx OPTIONS
1972above.
1973.Pp
1974Multiple options can be specified, separated by commas:
1975.Bd -literal
1976pass in proto tcp from any to any \e
1977 port www flags S/SA keep state \e
1978 (max 100, source-track rule, max-src-nodes 75, \e
1979 max-src-states 3, tcp.established 60, tcp.closing 5)
1980.Ed
1981.El
1982.Sh OPERATING SYSTEM FINGERPRINTING
1983Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP
1984connection's initial SYN packet and guess at the host's operating system.
1985Unfortunately these nuances are easily spoofed by an attacker so the
1986fingerprint is not useful in making security decisions.
1987But the fingerprint is typically accurate enough to make policy decisions
1988upon.
1989.Pp
1990The fingerprints may be specified by operating system class, by
1991version, or by subtype/patchlevel.
2e46b2a9 1992The class of an operating system is typically the vendor or genre
b5ac91c1
SW
1993and would be
1994.Ox
1995for the
95cc27f0
JS
1996.Xr pf 4
1997firewall itself.
b5ac91c1
SW
1998The version of the oldest available
1999.Ox
2000release on the main ftp site
95cc27f0
JS
2001would be 2.6 and the fingerprint would be written
2002.Pp
2003.Dl \&"OpenBSD 2.6\&"
2004.Pp
2005The subtype of an operating system is typically used to describe the
2006patchlevel if that patch led to changes in the TCP stack behavior.
b5ac91c1
SW
2007In the case of
2008.Ox ,
2009the only subtype is for a fingerprint that was
95cc27f0
JS
2010normalized by the
2011.Ar no-df
2012scrub option and would be specified as
2013.Pp
2014.Dl \&"OpenBSD 3.3 no-df\&"
2015.Pp
2016Fingerprints for most popular operating systems are provided by
2017.Xr pf.os 5 .
2018Once
2019.Xr pf 4
2020is running, a complete list of known operating system fingerprints may
2021be listed by running:
2022.Pp
2023.Dl # pfctl -so
2024.Pp
2025Filter rules can enforce policy at any level of operating system specification
2026assuming a fingerprint is present.
2027Policy could limit traffic to approved operating systems or even ban traffic
2028from hosts that aren't at the latest service pack.
2029.Pp
2030The
2031.Ar unknown
2032class can also be used as the fingerprint which will match packets for
2033which no operating system fingerprint is known.
2034.Pp
2035Examples:
2036.Bd -literal -offset indent
2037pass out proto tcp from any os OpenBSD keep state
2038block out proto tcp from any os Doors
2039block out proto tcp from any os "Doors PT"
2040block out proto tcp from any os "Doors PT SP3"
2041block out from any os "unknown"
2042pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" keep state
2043.Ed
2044.Pp
2045Operating system fingerprinting is limited only to the TCP SYN packet.
2046This means that it will not work on other protocols and will not match
2047a currently established connection.
2048.Pp
2049Caveat: operating system fingerprints are occasionally wrong.
2050There are three problems: an attacker can trivially craft his packets to
2051appear as any operating system he chooses;
2052an operating system patch could change the stack behavior and no fingerprints
2053will match it until the database is updated;
2054and multiple operating systems may have the same fingerprint.
2055.Sh BLOCKING SPOOFED TRAFFIC
2056"Spoofing" is the faking of IP addresses, typically for malicious
2057purposes.
2058The
2059.Ar antispoof
2060directive expands to a set of filter rules which will block all
2061traffic with a source IP from the network(s) directly connected
2062to the specified interface(s) from entering the system through
2063any other interface.
2064.Pp
2065For example, the line
2066.Bd -literal -offset indent
2067antispoof for lo0
2068.Ed
2069.Pp
2070expands to
2071.Bd -literal -offset indent
2072block drop in on ! lo0 inet from 127.0.0.1/8 to any
2073block drop in on ! lo0 inet6 from ::1 to any
2074.Ed
2075.Pp
2076For non-loopback interfaces, there are additional rules to block incoming
2077packets with a source IP address identical to the interface's IP(s).
2078For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a
2079netmask of 255.255.255.0,
2080the line
2081.Bd -literal -offset indent
2082antispoof for wi0 inet
2083.Ed
2084.Pp
2085expands to
2086.Bd -literal -offset indent
2087block drop in on ! wi0 inet from 10.0.0.0/24 to any
2088block drop in inet from 10.0.0.1 to any
2089.Ed
2090.Pp
2091Caveat: Rules created by the
2092.Ar antispoof
2093directive interfere with packets sent over loopback interfaces
2094to local addresses.
2095One should pass these explicitly.
2096.Sh FRAGMENT HANDLING
2097The size of IP datagrams (packets) can be significantly larger than the
2098maximum transmission unit (MTU) of the network.
2099In cases when it is necessary or more efficient to send such large packets,
2100the large packet will be fragmented into many smaller packets that will each
2101fit onto the wire.
2102Unfortunately for a firewalling device, only the first logical fragment will
2103contain the necessary header information for the subprotocol that allows
2104.Xr pf 4
2105to filter on things such as TCP ports or to perform NAT.
2106.Pp
2107Besides the use of
2108.Ar scrub
2109rules as described in
2110.Sx TRAFFIC NORMALIZATION
2111above, there are three options for handling fragments in the packet filter.
2112.Pp
2113One alternative is to filter individual fragments with filter rules.
2114If no
2115.Ar scrub
2116rule applies to a fragment, it is passed to the filter.
2117Filter rules with matching IP header parameters decide whether the
2118fragment is passed or blocked, in the same way as complete packets
2119are filtered.
2120Without reassembly, fragments can only be filtered based on IP header
2121fields (source/destination address, protocol), since subprotocol header
2122fields are not available (TCP/UDP port numbers, ICMP code/type).
2123The
2124.Ar fragment
2125option can be used to restrict filter rules to apply only to
2126fragments, but not complete packets.
2127Filter rules without the
2128.Ar fragment
2129option still apply to fragments, if they only specify IP header fields.
2130For instance, the rule
2131.Bd -literal -offset indent
2132pass in proto tcp from any to any port 80
2133.Ed
2134.Pp
2135never applies to a fragment, even if the fragment is part of a TCP
2136packet with destination port 80, because without reassembly this information
2137is not available for each fragment.
2138This also means that fragments cannot create new or match existing
2139state table entries, which makes stateful filtering and address
2140translation (NAT, redirection) for fragments impossible.
2141.Pp
2142It's also possible to reassemble only certain fragments by specifying
2143source or destination addresses or protocols as parameters in
2144.Ar scrub
2145rules.
2146.Pp
2147In most cases, the benefits of reassembly outweigh the additional
2148memory cost, and it's recommended to use
2149.Ar scrub
2150rules to reassemble
2151all fragments via the
2152.Ar fragment reassemble
2153modifier.
2154.Pp
2155The memory allocated for fragment caching can be limited using
2156.Xr pfctl 8 .
2157Once this limit is reached, fragments that would have to be cached
2158are dropped until other entries time out.
2159The timeout value can also be adjusted.
2160.Pp
2161Currently, only IPv4 fragments are supported and IPv6 fragments
2162are blocked unconditionally.
2163.Sh ANCHORS AND NAMED RULESETS
2164Besides the main ruleset,
2165.Xr pfctl 8
2166can load named rulesets into
2167.Ar anchor
2168attachment points.
2169An
2170.Ar anchor
2171contains a list of named rulesets.
2172An
2173.Ar anchor
2174has a name which specifies where
2175.Xr pfctl 8
2176can be used to attach sub-rulesets.
2177A named ruleset contains filter and translation rules, like the
2178main ruleset.
2179The main ruleset can reference
2180.Ar anchor
2181attachment points
2182using the following kinds
2183of rules:
2184.Bl -tag -width xxxx
2185.It Ar nat-anchor <name>
2186Evaluates the
2187.Ar nat
2188rules of all named rulesets in the specified
2189.Ar anchor .
2190.It Ar rdr-anchor <name>
2191Evaluates the
2192.Ar rdr
2193rules of all named rulesets in the specified
2194.Ar anchor .
2195.It Ar binat-anchor <name>
2196Evaluates the
2197.Ar binat
2198rules of all named rulesets in the specified
2199.Ar anchor .
2200.It Ar anchor <name>
2201Evaluates the filter rules of all named rulesets in the specified
2202.Ar anchor .
2203.It Ar load anchor <name>:<ruleset> from <file>
2204Loads the rules from the specified file into the named
2205ruleset
2206.Ar <ruleset>
2207attached to the anchor
2208.Ar <name> .
2209.El
2210.Pp
2211When evaluation of the main ruleset reaches an
2212.Ar anchor
2213rule,
2214.Xr pf 4
2215will proceed to evaluate all rules specified in the
2216named rulesets attached to that
2217.Ar anchor .
2218.Pp
2219Matching filter rules in named rulesets with the
2220.Ar quick
2221option and matching translation rules are final and abort the
2222evaluation of both the rules in the
2223.Ar anchor
2224and the main ruleset.
2225.Pp
2226Only the main ruleset can contain
2227.Ar anchor
2228rules.
2229.Pp
2230When an
2231.Ar anchor
2232contains more than one named ruleset, they are evaluated
2233in the alphabetical order of their names.
2234.Pp
2235Rules may contain
2236.Ar anchor
2237attachment points which do not contain any rules when the main ruleset
2238is loaded, and later such named rulesets can be manipulated through
2239.Xr pfctl 8
2240without reloading the main ruleset.
2241For example,
2242.Bd -literal -offset indent
2243ext_if = \&"kue0\&"
2244block on $ext_if all
2245anchor spam
2246pass out on $ext_if all keep state
2247pass in on $ext_if proto tcp from any \e
2248 to $ext_if port smtp keep state
2249.Ed
2250.Pp
2251blocks all packets on the external interface by default, then evaluates
2252all rulesets in the
2253.Ar anchor
2254named "spam", and finally passes all outgoing connections and
2255incoming connections to port 25.
2256.Bd -literal -offset indent
2257# echo \&"block in quick from 1.2.3.4 to any\&" \&| \e
2258 pfctl -a spam:manual -f -
2259.Ed
2260.Pp
2261loads a single ruleset containing a single rule into the
2262.Ar anchor ,
2263which blocks all packets from a specific address.
2264.Pp
2265The named ruleset can also be populated by adding a
2266.Ar load anchor
2267rule after the
2268.Ar anchor
2269rule:
2270.Bd -literal -offset indent
2271anchor spam
2272load anchor spam:manual from "/etc/pf-spam.conf"
2273.Ed
2274.Pp
2275When
2276.Xr pfctl 8
2277loads
9b5a9965 2278.Nm ,
95cc27f0
JS
2279it will also load all the rules from the file
2280.Pa /etc/pf-spam.conf
2281into the named ruleset.
2282.Pp
2283Optionally,
2284.Ar anchor
2285rules can specify the parameter's
2286direction, interface, address family, protocol and source/destination
2287address/port
2288using the same syntax as filter rules.
2289When parameters are used, the
2290.Ar anchor
2291rule is only evaluated for matching packets.
2292This allows conditional evaluation of named rulesets, like:
2293.Bd -literal -offset indent
2294block on $ext_if all
2295anchor spam proto tcp from any to any port smtp
2296pass out on $ext_if all keep state
2297pass in on $ext_if proto tcp from any to $ext_if port smtp keep state
2298.Ed
2299.Pp
2300The rules inside
2301.Ar anchor
2302spam are only evaluated for
2303.Ar tcp
2304packets with destination port 25.
2305Hence,
2306.Bd -literal -offset indent
2307# echo \&"block in quick from 1.2.3.4 to any" \&| \e
2308 pfctl -a spam:manual -f -
2309.Ed
2310.Pp
2311will only block connections from 1.2.3.4 to port 25.
de023c90
SW
2312.Sh FILES
2313.Bl -tag -width "/etc/protocols" -compact
2314.It Pa /etc/hosts
2315Host name database.
2316.It Pa /etc/pf.conf
2317Default location of the ruleset file.
2318.It Pa /etc/pf.os
2319Default location of OS fingerprints.
2320.It Pa /etc/protocols
2321Protocol name database.
2322.It Pa /etc/services
2323Service name database.
2324.It Pa /usr/share/examples/pf
2325Example rulesets.
2326.El
95cc27f0
JS
2327.Sh TRANSLATION EXAMPLES
2328This example maps incoming requests on port 80 to port 8080, on
2329which a daemon is running (because, for example, it is not run as root,
2330and therefore lacks permission to bind to port 80).
2331.Bd -literal
2332# use a macro for the interface name, so it can be changed easily
2333ext_if = \&"ne3\&"
2334
2335# map daemon on 8080 to appear to be on 80
2336rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
2337.Ed
2338.Pp
2339If the
2340.Ar pass
2341modifier is given, packets matching the translation rule are passed without
2342inspecting the filter rules:
2343.Bd -literal
2344rdr pass on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 \e
2345 port 8080
2346.Ed
2347.Pp
2348In the example below, vlan12 is configured as 192.168.168.1;
2349the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111
2350when they are going out any interface except vlan12.
2351This has the net effect of making traffic from the 192.168.168.0/24
2352network appear as though it is the Internet routable address
2353204.92.77.111 to nodes behind any interface on the router except
2354for the nodes on vlan12.
2355(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.)
2356.Bd -literal
2357nat on ! vlan12 from 192.168.168.0/24 to any -> 204.92.77.111
2358.Ed
2359.Pp
2360In the example below, the machine sits between a fake internal 144.19.74.*
2361network, and a routable external IP of 204.92.77.100.
2362The
2363.Ar no nat
2364rule excludes protocol AH from being translated.
2365.Bd -literal
2366# NO NAT
2367no nat on $ext_if proto ah from 144.19.74.0/24 to any
2368nat on $ext_if from 144.19.74.0/24 to any -> 204.92.77.100
2369.Ed
2370.Pp
2371In the example below, packets bound for one specific server, as well as those
2372generated by the sysadmins are not proxied; all other connections are.
2373.Bd -literal
2374# NO RDR
2375no rdr on $int_if proto { tcp, udp } from any to $server port 80
2376no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80
2377rdr on $int_if proto { tcp, udp } from any to any port 80 -> 127.0.0.1 \e
2378 port 80
2379.Ed
2380.Pp
2381This longer example uses both a NAT and a redirection.
2382The external interface has the address 157.161.48.183.
2383On the internal interface, we are running
2384.Xr ftp-proxy 8 ,
2385listening for outbound ftp sessions captured to port 8021.
2386.Bd -literal
2387# NAT
2388# Translate outgoing packets' source addresses (any protocol).
2389# In this case, any address but the gateway's external address is mapped.
2390nat on $ext_if inet from ! ($ext_if) to any -> ($ext_if)
2391
2392# NAT PROXYING
2393# Map outgoing packets' source port to an assigned proxy port instead of
2394# an arbitrary port.
2395# In this case, proxy outgoing isakmp with port 500 on the gateway.
2396nat on $ext_if inet proto udp from any port = isakmp to any -> ($ext_if) \e
2397 port 500
2398
2399# BINAT
2400# Translate outgoing packets' source address (any protocol).
2401# Translate incoming packets' destination address to an internal machine
2402# (bidirectional).
2403binat on $ext_if from 10.1.2.150 to any -> ($ext_if)
2404
2405# RDR
2406# Translate incoming packets' destination addresses.
2407# As an example, redirect a TCP and UDP port to an internal machine.
2408rdr on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e
2409 -> 10.1.2.151 port 22
2410rdr on $ext_if inet proto udp from any to ($ext_if) port 8080 \e
2411 -> 10.1.2.151 port 53
2412
2413# RDR
2414# Translate outgoing ftp control connections to send them to localhost
2415# for proxying with ftp-proxy(8) running on port 8021.
2416rdr on $int_if proto tcp from any to any port 21 -> 127.0.0.1 port 8021
2417.Ed
2418.Pp
2419In this example, a NAT gateway is set up to translate internal addresses
2420using a pool of public addresses (192.0.2.16/28) and to redirect
2421incoming web server connections to a group of web servers on the internal
2422network.
2423.Bd -literal
2424# NAT LOAD BALANCE
2425# Translate outgoing packets' source addresses using an address pool.
2426# A given source address is always translated to the same pool address by
2427# using the source-hash keyword.
2428nat on $ext_if inet from any to any -> 192.0.2.16/28 source-hash
2429
2430# RDR ROUND ROBIN
2431# Translate incoming web server connections to a group of web servers on
2432# the internal network.
2433rdr on $ext_if proto tcp from any to any port 80 \e
2434 -> { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin
2435.Ed
2436.Sh FILTER EXAMPLES
2437.Bd -literal
2438# The external interface is kue0
2439# (157.161.48.183, the only routable address)
2440# and the private network is 10.0.0.0/8, for which we are doing NAT.
2441
2442# use a macro for the interface name, so it can be changed easily
2443ext_if = \&"kue0\&"
2444
2445# normalize all incoming traffic
2446scrub in on $ext_if all fragment reassemble
2447
2448# block and log everything by default
2449block return log on $ext_if all
2450
2451# block anything coming from source we have no back routes for
2452block in from no-route to any
2453
2454# block and log outgoing packets that do not have our address as source,
2455# they are either spoofed or something is misconfigured (NAT disabled,
2456# for instance), we want to be nice and do not send out garbage.
2457block out log quick on $ext_if from ! 157.161.48.183 to any
2458
2459# silently drop broadcasts (cable modem noise)
2460block in quick on $ext_if from any to 255.255.255.255
2461
2462# block and log incoming packets from reserved address space and invalid
2463# addresses, they are either spoofed or misconfigured, we cannot reply to
2464# them anyway (hence, no return-rst).
2465block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e
2466 192.168.0.0/16, 255.255.255.255/32 } to any
2467
2468# ICMP
2469
2470# pass out/in certain ICMP queries and keep state (ping)
2471# state matching is done on host addresses and ICMP id (not type/code),
2472# so replies (like 0/0 for 8/0) will match queries
2473# ICMP error messages (which always refer to a TCP/UDP packet) are
2474# handled by the TCP/UDP states
2475pass on $ext_if inet proto icmp all icmp-type 8 code 0 keep state
2476
2477# UDP
2478
2479# pass out all UDP connections and keep state
2480pass out on $ext_if proto udp all keep state
2481
2482# pass in certain UDP connections and keep state (DNS)
2483pass in on $ext_if proto udp from any to any port domain keep state
2484
2485# TCP
2486
2487# pass out all TCP connections and modulate state
2488pass out on $ext_if proto tcp all modulate state
2489
2490# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT)
2491pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e
2492 auth } flags S/SA keep state
2493
2494# pass in data mode connections for ftp-proxy running on this host.
2495# (see ftp-proxy(8) for details)
2496pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 49152 \e
2497 flags S/SA keep state
2498
2499# Do not allow Windows 9x SMTP connections since they are typically
2500# a viral worm. Alternately we could limit these OSes to 1 connection each.
2501block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e
2502 to any port smtp
2503
2504# Packet Tagging
2505
2506# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is
2507# being done on $ext_if for all outgoing packets. tag packets in on
2508# $int_if and pass those tagged packets out on $ext_if. all other
2509# outgoing packets (i.e., packets from the wireless network) are only
2510# permitted to access port 80.
2511
2512pass in on $int_if from any to any tag INTNET keep state
2513pass in on $wifi_if from any to any keep state
2514
2515block out on $ext_if from any to any
2516pass out quick on $ext_if tagged INTNET keep state
2517pass out on $ext_if from any to any port 80 keep state
2518
2519# tag incoming packets as they are redirected to spamd(8). use the tag
2520# to pass those packets through the packet filter.
2521
2522rdr on $ext_if inet proto tcp from <spammers> to port smtp \e
2523 tag SPAMD -> 127.0.0.1 port spamd
2524
2525block in on $ext_if
2526pass in on $ext_if inet proto tcp tagged SPAMD keep state
2527.Ed
2528.Sh GRAMMAR
2529Syntax for
2530.Nm
2531in BNF:
2532.Bd -literal
2533line = ( option | pf-rule | nat-rule | binat-rule | rdr-rule |
2534 antispoof-rule | altq-rule | queue-rule | anchor-rule |
2535 trans-anchors | load-anchors | table-rule )
2536
2537option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] |
2538 [ "optimization" [ "default" | "normal" |
2539 "high-latency" | "satellite" |
2540 "aggressive" | "conservative" ] ]
2541 [ "limit" ( limit-item | "{" limit-list "}" ) ] |
2542 [ "loginterface" ( interface-name | "none" ) ] |
2543 [ "block-policy" ( "drop" | "return" ) ] |
2544 [ "state-policy" ( "if-bound" | "group-bound" |
2545 "floating" ) ]
2546 [ "require-order" ( "yes" | "no" ) ]
2547 [ "fingerprints" filename ] |
2548 [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] )
2549
2550pf-rule = action [ ( "in" | "out" ) ]
2551 [ "log" | "log-all" ] [ "quick" ]
2552 [ "on" ifspec ] [ route ] [ af ] [ protospec ]
2553 hosts [ filteropt-list ]
2554
2555filteropt-list = filteropt-list filteropt | filteropt
2556filteropt = user | group | flags | icmp-type | icmp6-type | tos |
2557 ( "keep" | "modulate" | "synproxy" ) "state"
2558 [ "(" state-opts ")" ] |
2559 "fragment" | "no-df" | "min-ttl" number |
2560 "max-mss" number | "random-id" | "reassemble tcp" |
2561 fragmentation | "allow-opts" |
2562 "label" string | "tag" string | [ ! ] "tagged" string
75fda04a
MD
2563 "queue" ( string | "(" string [ [ "," ] string ] ")" ) |
2564 "probability" number"%"
95cc27f0
JS
2565
2566nat-rule = [ "no" ] "nat" [ "pass" ] [ "on" ifspec ] [ af ]
2567 [ protospec ] hosts [ "tag" string ]
2568 [ "->" ( redirhost | "{" redirhost-list "}" )
2569 [ portspec ] [ pooltype ] [ "static-port" ] ]
2570
2571binat-rule = [ "no" ] "binat" [ "pass" ] [ "on" interface-name ]
2572 [ af ] [ "proto" ( proto-name | proto-number ) ]
2573 "from" address [ "/" mask-bits ] "to" ipspec
2574 [ "tag" string ]
2575 [ "->" address [ "/" mask-bits ] ]
2576
2577rdr-rule = [ "no" ] "rdr" [ "pass" ] [ "on" ifspec ] [ af ]
2578 [ protospec ] hosts [ "tag" string ]
2579 [ "->" ( redirhost | "{" redirhost-list "}" )
2580 [ portspec ] [ pooltype ] ]
2581
2582antispoof-rule = "antispoof" [ "log" ] [ "quick" ]
2583 "for" ( interface-name | "{" interface-list "}" )
2584 [ af ] [ "label" string ]
2585
2586table-rule = "table" "<" string ">" [ tableopts-list ]
2587tableopts-list = tableopts-list tableopts | tableopts
2588tableopts = "persist" | "const" | "file" string |
2589 "{" [ tableaddr-list ] "}"
2590tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec
2591tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ]
2592tableaddr = hostname | ipv4-dotted-quad | ipv6-coloned-hex |
2593 interface-name | "self"
2594
2595altq-rule = "altq on" interface-name queueopts-list
2596 "queue" subqueue
2597queue-rule = "queue" string [ "on" interface-name ] queueopts-list
2598 subqueue
2599
2600anchor-rule = "anchor" string [ ( "in" | "out" ) ] [ "on" ifspec ]
2601 [ af ] [ "proto" ] [ protospec ] [ hosts ]
2602
2603trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string
2604 [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ]
2605
2606load-anchor = "load anchor" anchorname:rulesetname "from" filename
2607
2608queueopts-list = queueopts-list queueopts | queueopts
2609queueopts = [ "bandwidth" bandwidth-spec ] |
2610 [ "qlimit" number ] | [ "tbrsize" number ] |
2611 [ "priority" number ] | [ schedulers ]
2612schedulers = ( cbq-def | priq-def | hfsc-def )
2613bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" )
2614
2615action = "pass" | "block" [ return ] | "scrub"
2616return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] |
2617 "return-icmp" [ "(" icmpcode ["," icmp6code ] ")" ] |
2618 "return-icmp6" [ "(" icmp6code ")" ]
2619icmpcode = ( icmp-code-name | icmp-code-number )
2620icmp6code = ( icmp6-code-name | icmp6-code-number )
2621
2622ifspec = ( [ "!" ] interface-name ) | "{" interface-list "}"
2623interface-list = [ "!" ] interface-name [ [ "," ] interface-list ]
2624route = "fastroute" |
2625 ( "route-to" | "reply-to" | "dup-to" )
2626 ( routehost | "{" routehost-list "}" )
2627 [ pooltype ]
2628af = "inet" | "inet6"
2629
2630protospec = "proto" ( proto-name | proto-number |
2631 "{" proto-list "}" )
2632proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ]
2633
2634hosts = "all" |
2635 "from" ( "any" | "no-route" | "self" | host |
2636 "{" host-list "}" ) [ port ] [ os ]
2637 "to" ( "any" | "no-route" | "self" | host |
2638 "{" host-list "}" ) [ port ]
2639
2640ipspec = "any" | host | "{" host-list "}"
2641host = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" )
2642redirhost = address [ "/" mask-bits ]
2643routehost = ( interface-name [ address [ "/" mask-bits ] ] )
2644address = ( interface-name | "(" interface-name ")" | hostname |
2645 ipv4-dotted-quad | ipv6-coloned-hex )
2646host-list = host [ [ "," ] host-list ]
2647redirhost-list = redirhost [ [ "," ] redirhost-list ]
2648routehost-list = routehost [ [ "," ] routehost-list ]
2649
2650port = "port" ( unary-op | binary-op | "{" op-list "}" )
2651portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ]
2652os = "os" ( os-name | "{" os-list "}" )
2653user = "user" ( unary-op | binary-op | "{" op-list "}" )
2654group = "group" ( unary-op | binary-op | "{" op-list "}" )
2655
2656unary-op = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ]
2657 ( name | number )
2658binary-op = number ( "<>" | "><" | ":" ) number
2659op-list = ( unary-op | binary-op ) [ [ "," ] op-list ]
2660
2661os-name = operating-system-name
2662os-list = os-name [ [ "," ] os-list ]
2663
2664flags = "flags" [ flag-set ] "/" flag-set
2665flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ]
2666 [ "W" ]
2667
2668icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" )
2669icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" )
2670icmp-type-code = ( icmp-type-name | icmp-type-number )
2671 [ "code" ( icmp-code-name | icmp-code-number ) ]
2672icmp-list = icmp-type-code [ [ "," ] icmp-list ]
2673
2674tos = "tos" ( "lowdelay" | "throughput" | "reliability" |
2675 [ "0x" ] number )
2676
2677state-opts = state-opt [ [ "," ] state-opts ]
2678state-opt = ( "max" number | "no-sync" | timeout |
2679 "source-track" [ ( "rule" | "global" ) ] |
2680 "max-src-nodes" number | "max-src-states" number |
2681 "if-bound" | "group-bound" | "floating" )
2682
2683fragmentation = [ "fragment reassemble" | "fragment crop" |
2684 "fragment drop-ovl" ]
2685
2686timeout-list = timeout [ [ "," ] timeout-list ]
2687timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" |
2688 "tcp.closing" | "tcp.finwait" | "tcp.closed" |
2689 "udp.first" | "udp.single" | "udp.multiple" |
2690 "icmp.first" | "icmp.error" |
2691 "other.first" | "other.single" | "other.multiple" |
2692 "frag" | "interval" | "src.track" |
2693 "adaptive.start" | "adaptive.end" ) number
2694
2695limit-list = limit-item [ [ "," ] limit-list ]
2696limit-item = ( "states" | "frags" | "src-nodes" ) number
2697
2698pooltype = ( "bitmask" | "random" |
2699 "source-hash" [ ( hex-key | string-key ) ] |
2700 "round-robin" ) [ sticky-address ]
2701
2702subqueue = string | "{" queue-list "}"
2703queue-list = string [ [ "," ] string ]
2704cbq-def = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ]
2705priq-def = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ]
2706hfsc-def = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ]
2707cbq-opt = ( "default" | "borrow" | "red" | "ecn" | "rio" )
2708priq-opt = ( "default" | "red" | "ecn" | "rio" )
2709hfsc-opt = ( "default" | "red" | "ecn" | "rio" |
2710 linkshare-sc | realtime-sc | upperlimit-sc )
2711linkshare-sc = "linkshare" sc-spec
2712realtime-sc = "realtime" sc-spec
2713upperlimit-sc = "upperlimit" sc-spec
2714sc-spec = ( bandwidth-spec |
2715 "(" bandwidth-spec number bandwidth-spec ")" )
2716.Ed
95cc27f0
JS
2717.Sh SEE ALSO
2718.Xr icmp 4 ,
2719.Xr icmp6 4 ,
2720.Xr ip 4 ,
2721.Xr ip6 4 ,
2722.Xr pf 4 ,
2723.Xr pfsync 4 ,
2724.Xr tcp 4 ,
2725.Xr udp 4 ,
2726.Xr hosts 5 ,
2727.Xr pf.os 5 ,
2728.Xr protocols 5 ,
2729.Xr services 5 ,
2730.Xr ftp-proxy 8 ,
2731.Xr pfctl 8 ,
2732.Xr pflogd 8
2733.Sh HISTORY
2734The
2735.Nm
2736file format first appeared in
2737.Ox 3.0 .