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