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