692df16dfaa892412c49f2ca4f821a286bab270e
[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.11 2008/04/06 19:29:23 swildner 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 .El
1601 .Sh ROUTING
1602 If a packet matches a rule with a route option set, the packet filter will
1603 route the packet according to the type of route option.
1604 When such a rule creates state, the route option is also applied to all
1605 packets matching the same connection.
1606 .Bl -tag -width xxxx
1607 .It Ar fastroute
1608 The
1609 .Ar fastroute
1610 option does a normal route lookup to find the next hop for the packet.
1611 .It Ar route-to
1612 The
1613 .Ar route-to
1614 option routes the packet to the specified interface with an optional address
1615 for the next hop.
1616 When a
1617 .Ar route-to
1618 rule creates state, only packets that pass in the same direction as the
1619 filter rule specifies will be routed in this way.
1620 Packets passing in the opposite direction (replies) are not affected
1621 and are routed normally.
1622 .It Ar reply-to
1623 The
1624 .Ar reply-to
1625 option is similar to
1626 .Ar route-to ,
1627 but routes packets that pass in the opposite direction (replies) to the
1628 specified interface.
1629 Opposite direction is only defined in the context of a state entry, and
1630 .Ar route-to
1631 is useful only in rules that create state.
1632 It can be used on systems with multiple external connections to
1633 route all outgoing packets of a connection through the interface
1634 the incoming connection arrived through (symmetric routing enforcement).
1635 .It Ar dup-to
1636 The
1637 .Ar dup-to
1638 option creates a duplicate of the packet and routes it like
1639 .Ar route-to .
1640 The original packet gets routed as it normally would.
1641 .El
1642 .Sh POOL OPTIONS
1643 For
1644 .Ar nat
1645 and
1646 .Ar rdr
1647 rules, (as well as for the
1648 .Ar route-to ,
1649 .Ar reply-to
1650 and
1651 .Ar dup-to
1652 rule options) for which there is a single redirection address which has a
1653 subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP
1654 address), a variety of different methods for assigning this address can be
1655 used:
1656 .Bl -tag -width xxxx
1657 .It Ar bitmask
1658 The
1659 .Ar bitmask
1660 option applies the network portion of the redirection address to the address
1661 to be modified (source with
1662 .Ar nat ,
1663 destination with
1664 .Ar rdr ) .
1665 .It Ar random
1666 The
1667 .Ar random
1668 option selects an address at random within the defined block of addresses.
1669 .It Ar source-hash
1670 The
1671 .Ar source-hash
1672 option uses a hash of the source address to determine the redirection address,
1673 ensuring that the redirection address is always the same for a given source.
1674 An optional key can be specified after this keyword either in hex or as a
1675 string; by default
1676 .Xr pfctl 8
1677 randomly generates a key for source-hash every time the
1678 ruleset is reloaded.
1679 .It Ar round-robin
1680 The
1681 .Ar round-robin
1682 option loops through the redirection address(es).
1683 .Pp
1684 When more than one redirection address is specified,
1685 .Ar round-robin
1686 is the only permitted pool type.
1687 .It Ar static-port
1688 With
1689 .Ar nat
1690 rules, the
1691 .Ar static-port
1692 option prevents
1693 .Xr pf 4
1694 from modifying the source port on TCP and UDP packets.
1695 .El
1696 .Pp
1697 Additionally, the
1698 .Ar sticky-address
1699 option can be specified to help ensure that multiple connections from the
1700 same source are mapped to the same redirection address.
1701 This option can be used with the
1702 .Ar random
1703 and
1704 .Ar round-robin
1705 pool options.
1706 Note that by default these associations are destroyed as soon as there are
1707 no longer states which refer to them; in order to make the mappings last
1708 beyond the lifetime of the states, increase the global options with
1709 .Ar set timeout source-track
1710 See
1711 .Sx STATEFUL TRACKING OPTIONS
1712 for more ways to control the source tracking.
1713 .Sh STATEFUL INSPECTION
1714 .Xr pf 4
1715 is a stateful packet filter, which means it can track the state of
1716 a connection.
1717 Instead of passing all traffic to port 25, for instance, it is possible
1718 to pass only the initial packet, and then begin to keep state.
1719 Subsequent traffic will flow because the filter is aware of the connection.
1720 .Pp
1721 If a packet matches a
1722 .Ar pass ... keep state
1723 rule, the filter creates a state for this connection and automatically
1724 lets pass all subsequent packets of that connection.
1725 .Pp
1726 Before any rules are evaluated, the filter checks whether the packet
1727 matches any state.
1728 If it does, the packet is passed without evaluation of any rules.
1729 .Pp
1730 States are removed after the connection is closed or has timed out.
1731 .Pp
1732 This has several advantages.
1733 Comparing a packet to a state involves checking its sequence numbers.
1734 If the sequence numbers are outside the narrow windows of expected
1735 values, the packet is dropped.
1736 This prevents spoofing attacks, such as when an attacker sends packets with
1737 a fake source address/port but does not know the connection's sequence
1738 numbers.
1739 .Pp
1740 Also, looking up states is usually faster than evaluating rules.
1741 If there are 50 rules, all of them are evaluated sequentially in O(n).
1742 Even with 50000 states, only 16 comparisons are needed to match a
1743 state, since states are stored in a binary search tree that allows
1744 searches in O(log2 n).
1745 .Pp
1746 For instance:
1747 .Bd -literal -offset indent
1748 block all
1749 pass out proto tcp from any to any flags S/SA keep state
1750 pass in  proto tcp from any to any port 25 flags S/SA keep state
1751 .Ed
1752 .Pp
1753 This ruleset blocks everything by default.
1754 Only outgoing connections and incoming connections to port 25 are allowed.
1755 The initial packet of each connection has the SYN
1756 flag set, will be passed and creates state.
1757 All further packets of these connections are passed if they match a state.
1758 .Pp
1759 By default, packets coming in and out of any interface can match a state,
1760 but it is also possible to change that behaviour by assigning states to a
1761 single interface or a group of interfaces.
1762 .Pp
1763 The default policy is specified by the
1764 .Ar state-policy
1765 global option, but this can be adjusted on a per-rule basis by adding one
1766 of the
1767 .Ar if-bound ,
1768 .Ar group-bound
1769 or
1770 .Ar floating
1771 keywords to the
1772 .Ar keep state
1773 option.
1774 For example, if a rule is defined as:
1775 .Bd -literal -offset indent
1776 pass out on ppp from any to 10.12/16 keep state (group-bound)
1777 .Ed
1778 .Pp
1779 A state created on ppp0 would match packets an all PPP interfaces,
1780 but not packets flowing through fxp0 or any other interface.
1781 .Pp
1782 Keeping rules
1783 .Ar floating
1784 is the more flexible option when the firewall is in a dynamic routing
1785 environment.
1786 However, this has some security implications since a state created by one
1787 trusted network could allow potentially hostile packets coming in from other
1788 interfaces.
1789 .Pp
1790 Specifying
1791 .Ar flags S/SA
1792 restricts state creation to the initial SYN
1793 packet of the TCP handshake.
1794 One can also be less restrictive, and allow state creation from
1795 intermediate
1796 .Pq non-SYN
1797 packets.
1798 This will cause
1799 .Xr pf 4
1800 to synchronize to existing connections, for instance
1801 if one flushes the state table.
1802 .Pp
1803 For UDP, which is stateless by nature,
1804 .Ar keep state
1805 will create state as well.
1806 UDP packets are matched to states using only host addresses and ports.
1807 .Pp
1808 ICMP messages fall into two categories: ICMP error messages, which always
1809 refer to a TCP or UDP packet, are matched against the referred to connection.
1810 If one keeps state on a TCP connection, and an ICMP source quench message
1811 referring to this TCP connection arrives, it will be matched to the right
1812 state and get passed.
1813 .Pp
1814 For ICMP queries,
1815 .Ar keep state
1816 creates an ICMP state, and
1817 .Xr pf 4
1818 knows how to match ICMP replies to states.
1819 For example,
1820 .Bd -literal -offset indent
1821 pass out inet proto icmp all icmp-type echoreq keep state
1822 .Ed
1823 .Pp
1824 allows echo requests (such as those created by
1825 .Xr ping 8 )
1826 out, creates state, and matches incoming echo replies correctly to states.
1827 .Pp
1828 Note:
1829 .Ar nat , binat No and Ar rdr
1830 rules implicitly create state for connections.
1831 .Sh STATE MODULATION
1832 Much of the security derived from TCP is attributable to how well the
1833 initial sequence numbers (ISNs) are chosen.
1834 Some popular stack implementations choose
1835 .Em very
1836 poor ISNs and thus are normally susceptible to ISN prediction exploits.
1837 By applying a
1838 .Ar modulate state
1839 rule to a TCP connection,
1840 .Xr pf 4
1841 will create a high quality random sequence number for each connection
1842 endpoint.
1843 .Pp
1844 The
1845 .Ar modulate state
1846 directive implicitly keeps state on the rule and is
1847 only applicable to TCP connections.
1848 .Pp
1849 For instance:
1850 .Bd -literal -offset indent
1851 block all
1852 pass out proto tcp from any to any modulate state
1853 pass in  proto tcp from any to any port 25 flags S/SA modulate state
1854 .Ed
1855 .Pp
1856 There are two caveats associated with state modulation:
1857 A
1858 .Ar modulate state
1859 rule can not be applied to a pre-existing but unmodulated connection.
1860 Such an application would desynchronize TCP's strict
1861 sequencing between the two endpoints.
1862 Instead,
1863 .Xr pf 4
1864 will treat the
1865 .Ar modulate state
1866 modifier as a
1867 .Ar keep state
1868 modifier and the pre-existing connection will be inferred without
1869 the protection conferred by modulation.
1870 .Pp
1871 The other caveat affects currently modulated states when the state table
1872 is lost (firewall reboot, flushing the state table, etc...).
1873 .Xr pf 4
1874 will not be able to infer a connection again after the state table flushes
1875 the connection's modulator.
1876 When the state is lost, the connection may be left dangling until the
1877 respective endpoints time out the connection.
1878 It is possible on a fast local network for the endpoints to start an ACK
1879 storm while trying to resynchronize after the loss of the modulator.
1880 Using a
1881 .Ar flags S/SA
1882 modifier on
1883 .Ar modulate state
1884 rules between fast networks is suggested to prevent ACK storms.
1885 .Sh SYN PROXY
1886 By default,
1887 .Xr pf 4
1888 passes packets that are part of a
1889 .Xr tcp 4
1890 handshake between the endpoints.
1891 The
1892 .Ar synproxy state
1893 option can be used to cause
1894 .Xr pf 4
1895 itself to complete the handshake with the active endpoint, perform a handshake
1896 with the passive endpoint, and then forward packets between the endpoints.
1897 .Pp
1898 No packets are sent to the passive endpoint before the active endpoint has
1899 completed the handshake, hence so-called SYN floods with spoofed source
1900 addresses will not reach the passive endpoint, as the sender can't complete the
1901 handshake.
1902 .Pp
1903 The proxy is transparent to both endpoints, they each see a single
1904 connection from/to the other endpoint.
1905 .Xr pf 4
1906 chooses random initial sequence numbers for both handshakes.
1907 Once the handshakes are completed, the sequence number modulators
1908 (see previous section) are used to translate further packets of the
1909 connection.
1910 Hence,
1911 .Ar synproxy state
1912 includes
1913 .Ar modulate state
1914 and
1915 .Ar keep state .
1916 .Pp
1917 Rules with
1918 .Ar synproxy
1919 will not work if
1920 .Xr pf 4
1921 operates on a
1922 .Xr bridge 4 .
1923 .Pp
1924 Example:
1925 .Bd -literal -offset indent
1926 pass in proto tcp from any to any port www flags S/SA synproxy state
1927 .Ed
1928 .Sh STATEFUL TRACKING OPTIONS
1929 All three of
1930 .Ar keep state ,
1931 .Ar modulate state
1932 and
1933 .Ar synproxy state
1934 support the following options:
1935 .Pp
1936 .Bl -tag -width xxxx -compact
1937 .It Ar max <number>
1938 Limits the number of concurrent states the rule may create.
1939 When this limit is reached, further packets matching the rule that would
1940 create state are dropped, until existing states time out.
1941 .It Ar no-sync
1942 Prevent state changes for states created by this rule from appearing on the
1943 .Xr pfsync 4
1944 interface.
1945 .It Ar <timeout> <seconds>
1946 Changes the timeout values used for states created by this rule.
1947 .Pp
1948 When the
1949 .Ar source-track
1950 keyword is specified, the number of states per source IP is tracked.
1951 The following limits can be set:
1952 .Pp
1953 .Bl  -tag -width xxxx -compact
1954 .It Ar max-src-nodes
1955 Limits the maximum number of source addresses which can simultaneously
1956 have state table entries.
1957 .It Ar max-src-states
1958 Limits the maximum number of simultaneous state entries that a single
1959 source address can create with this rule.
1960 .El
1961 For a list of all valid timeout names, see
1962 .Sx OPTIONS
1963 above.
1964 .Pp
1965 Multiple options can be specified, separated by commas:
1966 .Bd -literal
1967 pass in proto tcp from any to any \e
1968       port www flags S/SA keep state \e
1969       (max 100, source-track rule, max-src-nodes 75, \e
1970       max-src-states 3, tcp.established 60, tcp.closing 5)
1971 .Ed
1972 .El
1973 .Sh OPERATING SYSTEM FINGERPRINTING
1974 Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP
1975 connection's initial SYN packet and guess at the host's operating system.
1976 Unfortunately these nuances are easily spoofed by an attacker so the
1977 fingerprint is not useful in making security decisions.
1978 But the fingerprint is typically accurate enough to make policy decisions
1979 upon.
1980 .Pp
1981 The fingerprints may be specified by operating system class, by
1982 version, or by subtype/patchlevel.
1983 The class of an operating system is typically the vendor or genre
1984 and would be
1985 .Ox
1986 for the
1987 .Xr pf 4
1988 firewall itself.
1989 The version of the oldest available
1990 .Ox
1991 release on the main ftp site
1992 would be 2.6 and the fingerprint would be written
1993 .Pp
1994 .Dl \&"OpenBSD 2.6\&"
1995 .Pp
1996 The subtype of an operating system is typically used to describe the
1997 patchlevel if that patch led to changes in the TCP stack behavior.
1998 In the case of
1999 .Ox ,
2000 the only subtype is for a fingerprint that was
2001 normalized by the
2002 .Ar no-df
2003 scrub option and would be specified as
2004 .Pp
2005 .Dl \&"OpenBSD 3.3 no-df\&"
2006 .Pp
2007 Fingerprints for most popular operating systems are provided by
2008 .Xr pf.os 5 .
2009 Once
2010 .Xr pf 4
2011 is running, a complete list of known operating system fingerprints may
2012 be listed by running:
2013 .Pp
2014 .Dl # pfctl -so
2015 .Pp
2016 Filter rules can enforce policy at any level of operating system specification
2017 assuming a fingerprint is present.
2018 Policy could limit traffic to approved operating systems or even ban traffic
2019 from hosts that aren't at the latest service pack.
2020 .Pp
2021 The
2022 .Ar unknown
2023 class can also be used as the fingerprint which will match packets for
2024 which no operating system fingerprint is known.
2025 .Pp
2026 Examples:
2027 .Bd -literal -offset indent
2028 pass  out proto tcp from any os OpenBSD keep state
2029 block out proto tcp from any os Doors
2030 block out proto tcp from any os "Doors PT"
2031 block out proto tcp from any os "Doors PT SP3"
2032 block out from any os "unknown"
2033 pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" keep state
2034 .Ed
2035 .Pp
2036 Operating system fingerprinting is limited only to the TCP SYN packet.
2037 This means that it will not work on other protocols and will not match
2038 a currently established connection.
2039 .Pp
2040 Caveat: operating system fingerprints are occasionally wrong.
2041 There are three problems: an attacker can trivially craft his packets to
2042 appear as any operating system he chooses;
2043 an operating system patch could change the stack behavior and no fingerprints
2044 will match it until the database is updated;
2045 and multiple operating systems may have the same fingerprint.
2046 .Sh BLOCKING SPOOFED TRAFFIC
2047 "Spoofing" is the faking of IP addresses, typically for malicious
2048 purposes.
2049 The
2050 .Ar antispoof
2051 directive expands to a set of filter rules which will block all
2052 traffic with a source IP from the network(s) directly connected
2053 to the specified interface(s) from entering the system through
2054 any other interface.
2055 .Pp
2056 For example, the line
2057 .Bd -literal -offset indent
2058 antispoof for lo0
2059 .Ed
2060 .Pp
2061 expands to
2062 .Bd -literal -offset indent
2063 block drop in on ! lo0 inet from 127.0.0.1/8 to any
2064 block drop in on ! lo0 inet6 from ::1 to any
2065 .Ed
2066 .Pp
2067 For non-loopback interfaces, there are additional rules to block incoming
2068 packets with a source IP address identical to the interface's IP(s).
2069 For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a
2070 netmask of 255.255.255.0,
2071 the line
2072 .Bd -literal -offset indent
2073 antispoof for wi0 inet
2074 .Ed
2075 .Pp
2076 expands to
2077 .Bd -literal -offset indent
2078 block drop in on ! wi0 inet from 10.0.0.0/24 to any
2079 block drop in inet from 10.0.0.1 to any
2080 .Ed
2081 .Pp
2082 Caveat: Rules created by the
2083 .Ar antispoof
2084 directive interfere with packets sent over loopback interfaces
2085 to local addresses.
2086 One should pass these explicitly.
2087 .Sh FRAGMENT HANDLING
2088 The size of IP datagrams (packets) can be significantly larger than the
2089 maximum transmission unit (MTU) of the network.
2090 In cases when it is necessary or more efficient to send such large packets,
2091 the large packet will be fragmented into many smaller packets that will each
2092 fit onto the wire.
2093 Unfortunately for a firewalling device, only the first logical fragment will
2094 contain the necessary header information for the subprotocol that allows
2095 .Xr pf 4
2096 to filter on things such as TCP ports or to perform NAT.
2097 .Pp
2098 Besides the use of
2099 .Ar scrub
2100 rules as described in
2101 .Sx TRAFFIC NORMALIZATION
2102 above, there are three options for handling fragments in the packet filter.
2103 .Pp
2104 One alternative is to filter individual fragments with filter rules.
2105 If no
2106 .Ar scrub
2107 rule applies to a fragment, it is passed to the filter.
2108 Filter rules with matching IP header parameters decide whether the
2109 fragment is passed or blocked, in the same way as complete packets
2110 are filtered.
2111 Without reassembly, fragments can only be filtered based on IP header
2112 fields (source/destination address, protocol), since subprotocol header
2113 fields are not available (TCP/UDP port numbers, ICMP code/type).
2114 The
2115 .Ar fragment
2116 option can be used to restrict filter rules to apply only to
2117 fragments, but not complete packets.
2118 Filter rules without the
2119 .Ar fragment
2120 option still apply to fragments, if they only specify IP header fields.
2121 For instance, the rule
2122 .Bd -literal -offset indent
2123 pass in proto tcp from any to any port 80
2124 .Ed
2125 .Pp
2126 never applies to a fragment, even if the fragment is part of a TCP
2127 packet with destination port 80, because without reassembly this information
2128 is not available for each fragment.
2129 This also means that fragments cannot create new or match existing
2130 state table entries, which makes stateful filtering and address
2131 translation (NAT, redirection) for fragments impossible.
2132 .Pp
2133 It's also possible to reassemble only certain fragments by specifying
2134 source or destination addresses or protocols as parameters in
2135 .Ar scrub
2136 rules.
2137 .Pp
2138 In most cases, the benefits of reassembly outweigh the additional
2139 memory cost, and it's recommended to use
2140 .Ar scrub
2141 rules to reassemble
2142 all fragments via the
2143 .Ar fragment reassemble
2144 modifier.
2145 .Pp
2146 The memory allocated for fragment caching can be limited using
2147 .Xr pfctl 8 .
2148 Once this limit is reached, fragments that would have to be cached
2149 are dropped until other entries time out.
2150 The timeout value can also be adjusted.
2151 .Pp
2152 Currently, only IPv4 fragments are supported and IPv6 fragments
2153 are blocked unconditionally.
2154 .Sh ANCHORS AND NAMED RULESETS
2155 Besides the main ruleset,
2156 .Xr pfctl 8
2157 can load named rulesets into
2158 .Ar anchor
2159 attachment points.
2160 An
2161 .Ar anchor
2162 contains a list of named rulesets.
2163 An
2164 .Ar anchor
2165 has a name which specifies where
2166 .Xr pfctl 8
2167 can be used to attach sub-rulesets.
2168 A named ruleset contains filter and translation rules, like the
2169 main ruleset.
2170 The main ruleset can reference
2171 .Ar anchor
2172 attachment points
2173 using the following kinds
2174 of rules:
2175 .Bl -tag -width xxxx
2176 .It Ar nat-anchor <name>
2177 Evaluates the
2178 .Ar nat
2179 rules of all named rulesets in the specified
2180 .Ar anchor .
2181 .It Ar rdr-anchor <name>
2182 Evaluates the
2183 .Ar rdr
2184 rules of all named rulesets in the specified
2185 .Ar anchor .
2186 .It Ar binat-anchor <name>
2187 Evaluates the
2188 .Ar binat
2189 rules of all named rulesets in the specified
2190 .Ar anchor .
2191 .It Ar anchor <name>
2192 Evaluates the filter rules of all named rulesets in the specified
2193 .Ar anchor .
2194 .It Ar load anchor <name>:<ruleset> from <file>
2195 Loads the rules from the specified file into the named
2196 ruleset
2197 .Ar <ruleset>
2198 attached to the anchor
2199 .Ar <name> .
2200 .El
2201 .Pp
2202 When evaluation of the main ruleset reaches an
2203 .Ar anchor
2204 rule,
2205 .Xr pf 4
2206 will proceed to evaluate all rules specified in the
2207 named rulesets attached to that
2208 .Ar anchor .
2209 .Pp
2210 Matching filter rules in named rulesets with the
2211 .Ar quick
2212 option and matching translation rules are final and abort the
2213 evaluation of both the rules in the
2214 .Ar anchor
2215 and the main ruleset.
2216 .Pp
2217 Only the main ruleset can contain
2218 .Ar anchor
2219 rules.
2220 .Pp
2221 When an
2222 .Ar anchor
2223 contains more than one named ruleset, they are evaluated
2224 in the alphabetical order of their names.
2225 .Pp
2226 Rules may contain
2227 .Ar anchor
2228 attachment points which do not contain any rules when the main ruleset
2229 is loaded, and later such named rulesets can be manipulated through
2230 .Xr pfctl 8
2231 without reloading the main ruleset.
2232 For example,
2233 .Bd -literal -offset indent
2234 ext_if = \&"kue0\&"
2235 block on $ext_if all
2236 anchor spam
2237 pass out on $ext_if all keep state
2238 pass in on $ext_if proto tcp from any \e
2239       to $ext_if port smtp keep state
2240 .Ed
2241 .Pp
2242 blocks all packets on the external interface by default, then evaluates
2243 all rulesets in the
2244 .Ar anchor
2245 named "spam", and finally passes all outgoing connections and
2246 incoming connections to port 25.
2247 .Bd -literal -offset indent
2248 # echo \&"block in quick from 1.2.3.4 to any\&" \&| \e
2249       pfctl -a spam:manual -f -
2250 .Ed
2251 .Pp
2252 loads a single ruleset containing a single rule into the
2253 .Ar anchor ,
2254 which blocks all packets from a specific address.
2255 .Pp
2256 The named ruleset can also be populated by adding a
2257 .Ar load anchor
2258 rule after the
2259 .Ar anchor
2260 rule:
2261 .Bd -literal -offset indent
2262 anchor spam
2263 load anchor spam:manual from "/etc/pf-spam.conf"
2264 .Ed
2265 .Pp
2266 When
2267 .Xr pfctl 8
2268 loads
2269 .Nm ,
2270 it will also load all the rules from the file
2271 .Pa /etc/pf-spam.conf
2272 into the named ruleset.
2273 .Pp
2274 Optionally,
2275 .Ar anchor
2276 rules can specify the parameter's
2277 direction, interface, address family, protocol and source/destination
2278 address/port
2279 using the same syntax as filter rules.
2280 When parameters are used, the
2281 .Ar anchor
2282 rule is only evaluated for matching packets.
2283 This allows conditional evaluation of named rulesets, like:
2284 .Bd -literal -offset indent
2285 block on $ext_if all
2286 anchor spam proto tcp from any to any port smtp
2287 pass out on $ext_if all keep state
2288 pass in on $ext_if proto tcp from any to $ext_if port smtp keep state
2289 .Ed
2290 .Pp
2291 The rules inside
2292 .Ar anchor
2293 spam are only evaluated for
2294 .Ar tcp
2295 packets with destination port 25.
2296 Hence,
2297 .Bd -literal -offset indent
2298 # echo \&"block in quick from 1.2.3.4 to any" \&| \e
2299       pfctl -a spam:manual -f -
2300 .Ed
2301 .Pp
2302 will only block connections from 1.2.3.4 to port 25.
2303 .Sh FILES
2304 .Bl -tag -width "/etc/protocols" -compact
2305 .It Pa /etc/hosts
2306 Host name database.
2307 .It Pa /etc/pf.conf
2308 Default location of the ruleset file.
2309 .It Pa /etc/pf.os
2310 Default location of OS fingerprints.
2311 .It Pa /etc/protocols
2312 Protocol name database.
2313 .It Pa /etc/services
2314 Service name database.
2315 .It Pa /usr/share/examples/pf
2316 Example rulesets.
2317 .El
2318 .Sh TRANSLATION EXAMPLES
2319 This example maps incoming requests on port 80 to port 8080, on
2320 which a daemon is running (because, for example, it is not run as root,
2321 and therefore lacks permission to bind to port 80).
2322 .Bd -literal
2323 # use a macro for the interface name, so it can be changed easily
2324 ext_if = \&"ne3\&"
2325
2326 # map daemon on 8080 to appear to be on 80
2327 rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080
2328 .Ed
2329 .Pp
2330 If the
2331 .Ar pass
2332 modifier is given, packets matching the translation rule are passed without
2333 inspecting the filter rules:
2334 .Bd -literal
2335 rdr pass on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 \e
2336       port 8080
2337 .Ed
2338 .Pp
2339 In the example below, vlan12 is configured as 192.168.168.1;
2340 the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111
2341 when they are going out any interface except vlan12.
2342 This has the net effect of making traffic from the 192.168.168.0/24
2343 network appear as though it is the Internet routable address
2344 204.92.77.111 to nodes behind any interface on the router except
2345 for the nodes on vlan12.
2346 (Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.)
2347 .Bd -literal
2348 nat on ! vlan12 from 192.168.168.0/24 to any -> 204.92.77.111
2349 .Ed
2350 .Pp
2351 In the example below, the machine sits between a fake internal 144.19.74.*
2352 network, and a routable external IP of 204.92.77.100.
2353 The
2354 .Ar no nat
2355 rule excludes protocol AH from being translated.
2356 .Bd -literal
2357 # NO NAT
2358 no nat on $ext_if proto ah from 144.19.74.0/24 to any
2359 nat on $ext_if from 144.19.74.0/24 to any -> 204.92.77.100
2360 .Ed
2361 .Pp
2362 In the example below, packets bound for one specific server, as well as those
2363 generated by the sysadmins are not proxied; all other connections are.
2364 .Bd -literal
2365 # NO RDR
2366 no rdr on $int_if proto { tcp, udp } from any to $server port 80
2367 no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80
2368 rdr on $int_if proto { tcp, udp } from any to any port 80 -> 127.0.0.1 \e
2369       port 80
2370 .Ed
2371 .Pp
2372 This longer example uses both a NAT and a redirection.
2373 The external interface has the address 157.161.48.183.
2374 On the internal interface, we are running
2375 .Xr ftp-proxy 8 ,
2376 listening for outbound ftp sessions captured to port 8021.
2377 .Bd -literal
2378 # NAT
2379 # Translate outgoing packets' source addresses (any protocol).
2380 # In this case, any address but the gateway's external address is mapped.
2381 nat on $ext_if inet from ! ($ext_if) to any -> ($ext_if)
2382
2383 # NAT PROXYING
2384 # Map outgoing packets' source port to an assigned proxy port instead of
2385 # an arbitrary port.
2386 # In this case, proxy outgoing isakmp with port 500 on the gateway.
2387 nat on $ext_if inet proto udp from any port = isakmp to any -> ($ext_if) \e
2388       port 500
2389
2390 # BINAT
2391 # Translate outgoing packets' source address (any protocol).
2392 # Translate incoming packets' destination address to an internal machine
2393 # (bidirectional).
2394 binat on $ext_if from 10.1.2.150 to any -> ($ext_if)
2395
2396 # RDR
2397 # Translate incoming packets' destination addresses.
2398 # As an example, redirect a TCP and UDP port to an internal machine.
2399 rdr on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e
2400       -> 10.1.2.151 port 22
2401 rdr on $ext_if inet proto udp from any to ($ext_if) port 8080 \e
2402       -> 10.1.2.151 port 53
2403
2404 # RDR
2405 # Translate outgoing ftp control connections to send them to localhost
2406 # for proxying with ftp-proxy(8) running on port 8021.
2407 rdr on $int_if proto tcp from any to any port 21 -> 127.0.0.1 port 8021
2408 .Ed
2409 .Pp
2410 In this example, a NAT gateway is set up to translate internal addresses
2411 using a pool of public addresses (192.0.2.16/28) and to redirect
2412 incoming web server connections to a group of web servers on the internal
2413 network.
2414 .Bd -literal
2415 # NAT LOAD BALANCE
2416 # Translate outgoing packets' source addresses using an address pool.
2417 # A given source address is always translated to the same pool address by
2418 # using the source-hash keyword.
2419 nat on $ext_if inet from any to any -> 192.0.2.16/28 source-hash
2420
2421 # RDR ROUND ROBIN
2422 # Translate incoming web server connections to a group of web servers on
2423 # the internal network.
2424 rdr on $ext_if proto tcp from any to any port 80 \e
2425       -> { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin
2426 .Ed
2427 .Sh FILTER EXAMPLES
2428 .Bd -literal
2429 # The external interface is kue0
2430 # (157.161.48.183, the only routable address)
2431 # and the private network is 10.0.0.0/8, for which we are doing NAT.
2432
2433 # use a macro for the interface name, so it can be changed easily
2434 ext_if = \&"kue0\&"
2435
2436 # normalize all incoming traffic
2437 scrub in on $ext_if all fragment reassemble
2438
2439 # block and log everything by default
2440 block return log on $ext_if all
2441
2442 # block anything coming from source we have no back routes for
2443 block in from no-route to any
2444
2445 # block and log outgoing packets that do not have our address as source,
2446 # they are either spoofed or something is misconfigured (NAT disabled,
2447 # for instance), we want to be nice and do not send out garbage.
2448 block out log quick on $ext_if from ! 157.161.48.183 to any
2449
2450 # silently drop broadcasts (cable modem noise)
2451 block in quick on $ext_if from any to 255.255.255.255
2452
2453 # block and log incoming packets from reserved address space and invalid
2454 # addresses, they are either spoofed or misconfigured, we cannot reply to
2455 # them anyway (hence, no return-rst).
2456 block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e
2457       192.168.0.0/16, 255.255.255.255/32 } to any
2458
2459 # ICMP
2460
2461 # pass out/in certain ICMP queries and keep state (ping)
2462 # state matching is done on host addresses and ICMP id (not type/code),
2463 # so replies (like 0/0 for 8/0) will match queries
2464 # ICMP error messages (which always refer to a TCP/UDP packet) are
2465 # handled by the TCP/UDP states
2466 pass on $ext_if inet proto icmp all icmp-type 8 code 0 keep state
2467
2468 # UDP
2469
2470 # pass out all UDP connections and keep state
2471 pass out on $ext_if proto udp all keep state
2472
2473 # pass in certain UDP connections and keep state (DNS)
2474 pass in on $ext_if proto udp from any to any port domain keep state
2475
2476 # TCP
2477
2478 # pass out all TCP connections and modulate state
2479 pass out on $ext_if proto tcp all modulate state
2480
2481 # pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT)
2482 pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e
2483       auth } flags S/SA keep state
2484
2485 # pass in data mode connections for ftp-proxy running on this host.
2486 # (see ftp-proxy(8) for details)
2487 pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 49152 \e
2488       flags S/SA keep state
2489
2490 # Do not allow Windows 9x SMTP connections since they are typically
2491 # a viral worm. Alternately we could limit these OSes to 1 connection each.
2492 block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e
2493       to any port smtp
2494
2495 # Packet Tagging
2496
2497 # three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is
2498 # being done on $ext_if for all outgoing packets. tag packets in on
2499 # $int_if and pass those tagged packets out on $ext_if.  all other
2500 # outgoing packets (i.e., packets from the wireless network) are only
2501 # permitted to access port 80.
2502
2503 pass in on $int_if from any to any tag INTNET keep state
2504 pass in on $wifi_if from any to any keep state
2505
2506 block out on $ext_if from any to any
2507 pass out quick on $ext_if tagged INTNET keep state
2508 pass out on $ext_if from any to any port 80 keep state
2509
2510 # tag incoming packets as they are redirected to spamd(8). use the tag
2511 # to pass those packets through the packet filter.
2512
2513 rdr on $ext_if inet proto tcp from <spammers> to port smtp \e
2514         tag SPAMD -> 127.0.0.1 port spamd
2515
2516 block in on $ext_if
2517 pass in on $ext_if inet proto tcp tagged SPAMD keep state
2518 .Ed
2519 .Sh GRAMMAR
2520 Syntax for
2521 .Nm
2522 in BNF:
2523 .Bd -literal
2524 line           = ( option | pf-rule | nat-rule | binat-rule | rdr-rule |
2525                  antispoof-rule | altq-rule | queue-rule | anchor-rule |
2526                  trans-anchors | load-anchors | table-rule )
2527
2528 option         = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] |
2529                  [ "optimization" [ "default" | "normal" |
2530                  "high-latency" | "satellite" |
2531                  "aggressive" | "conservative" ] ]
2532                  [ "limit" ( limit-item | "{" limit-list "}" ) ] |
2533                  [ "loginterface" ( interface-name | "none" ) ] |
2534                  [ "block-policy" ( "drop" | "return" ) ] |
2535                  [ "state-policy" ( "if-bound" | "group-bound" |
2536                  "floating" ) ]
2537                  [ "require-order" ( "yes" | "no" ) ]
2538                  [ "fingerprints" filename ] |
2539                  [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] )
2540
2541 pf-rule        = action [ ( "in" | "out" ) ]
2542                  [ "log" | "log-all" ] [ "quick" ]
2543                  [ "on" ifspec ] [ route ] [ af ] [ protospec ]
2544                  hosts [ filteropt-list ]
2545
2546 filteropt-list = filteropt-list filteropt | filteropt
2547 filteropt      = user | group | flags | icmp-type | icmp6-type | tos |
2548                  ( "keep" | "modulate" | "synproxy" ) "state"
2549                  [ "(" state-opts ")" ] |
2550                  "fragment" | "no-df" | "min-ttl" number |
2551                  "max-mss" number | "random-id" | "reassemble tcp" |
2552                  fragmentation | "allow-opts" |
2553                  "label" string | "tag" string | [ ! ] "tagged" string
2554                  "queue" ( string | "(" string [ [ "," ] string ] ")" )
2555
2556 nat-rule       = [ "no" ] "nat" [ "pass" ] [ "on" ifspec ] [ af ]
2557                  [ protospec ] hosts [ "tag" string ]
2558                  [ "->" ( redirhost | "{" redirhost-list "}" )
2559                  [ portspec ] [ pooltype ] [ "static-port" ] ]
2560
2561 binat-rule     = [ "no" ] "binat" [ "pass" ] [ "on" interface-name ]
2562                  [ af ] [ "proto" ( proto-name | proto-number ) ]
2563                  "from" address [ "/" mask-bits ] "to" ipspec
2564                  [ "tag" string ]
2565                  [ "->" address [ "/" mask-bits ] ]
2566
2567 rdr-rule       = [ "no" ] "rdr" [ "pass" ] [ "on" ifspec ] [ af ]
2568                  [ protospec ] hosts [ "tag" string ]
2569                  [ "->" ( redirhost | "{" redirhost-list "}" )
2570                  [ portspec ] [ pooltype ] ]
2571
2572 antispoof-rule = "antispoof" [ "log" ] [ "quick" ]
2573                  "for" ( interface-name | "{" interface-list "}" )
2574                  [ af ] [ "label" string ]
2575
2576 table-rule     = "table" "<" string ">" [ tableopts-list ]
2577 tableopts-list = tableopts-list tableopts | tableopts
2578 tableopts      = "persist" | "const" | "file" string |
2579                  "{" [ tableaddr-list ] "}"
2580 tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec
2581 tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ]
2582 tableaddr      = hostname | ipv4-dotted-quad | ipv6-coloned-hex |
2583                  interface-name | "self"
2584
2585 altq-rule      = "altq on" interface-name queueopts-list
2586                  "queue" subqueue
2587 queue-rule     = "queue" string [ "on" interface-name ] queueopts-list
2588                  subqueue
2589
2590 anchor-rule    = "anchor" string [ ( "in" | "out" ) ] [ "on" ifspec ]
2591                  [ af ] [ "proto" ] [ protospec ] [ hosts ]
2592
2593 trans-anchors  = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string
2594                  [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ]
2595
2596 load-anchor    = "load anchor" anchorname:rulesetname "from" filename
2597
2598 queueopts-list = queueopts-list queueopts | queueopts
2599 queueopts      = [ "bandwidth" bandwidth-spec ] |
2600                  [ "qlimit" number ] | [ "tbrsize" number ] |
2601                  [ "priority" number ] | [ schedulers ]
2602 schedulers     = ( cbq-def | priq-def | hfsc-def )
2603 bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" )
2604
2605 action         = "pass" | "block" [ return ] | "scrub"
2606 return         = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] |
2607                  "return-icmp" [ "(" icmpcode ["," icmp6code ] ")" ] |
2608                  "return-icmp6" [ "(" icmp6code ")" ]
2609 icmpcode       = ( icmp-code-name | icmp-code-number )
2610 icmp6code      = ( icmp6-code-name | icmp6-code-number )
2611
2612 ifspec         = ( [ "!" ] interface-name ) | "{" interface-list "}"
2613 interface-list = [ "!" ] interface-name [ [ "," ] interface-list ]
2614 route          = "fastroute" |
2615                  ( "route-to" | "reply-to" | "dup-to" )
2616                  ( routehost | "{" routehost-list "}" )
2617                  [ pooltype ]
2618 af             = "inet" | "inet6"
2619
2620 protospec      = "proto" ( proto-name | proto-number |
2621                  "{" proto-list "}" )
2622 proto-list     = ( proto-name | proto-number ) [ [ "," ] proto-list ]
2623
2624 hosts          = "all" |
2625                  "from" ( "any" | "no-route" | "self" | host |
2626                  "{" host-list "}" ) [ port ] [ os ]
2627                  "to"   ( "any" | "no-route" | "self" | host |
2628                  "{" host-list "}" ) [ port ]
2629
2630 ipspec         = "any" | host | "{" host-list "}"
2631 host           = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" )
2632 redirhost      = address [ "/" mask-bits ]
2633 routehost      = ( interface-name [ address [ "/" mask-bits ] ] )
2634 address        = ( interface-name | "(" interface-name ")" | hostname |
2635                  ipv4-dotted-quad | ipv6-coloned-hex )
2636 host-list      = host [ [ "," ] host-list ]
2637 redirhost-list = redirhost [ [ "," ] redirhost-list ]
2638 routehost-list = routehost [ [ "," ] routehost-list ]
2639
2640 port           = "port" ( unary-op | binary-op | "{" op-list "}" )
2641 portspec       = "port" ( number | name ) [ ":" ( "*" | number | name ) ]
2642 os             = "os"  ( os-name | "{" os-list "}" )
2643 user           = "user" ( unary-op | binary-op | "{" op-list "}" )
2644 group          = "group" ( unary-op | binary-op | "{" op-list "}" )
2645
2646 unary-op       = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ]
2647                  ( name | number )
2648 binary-op      = number ( "<>" | "><" | ":" ) number
2649 op-list        = ( unary-op | binary-op ) [ [ "," ] op-list ]
2650
2651 os-name        = operating-system-name
2652 os-list        = os-name [ [ "," ] os-list ]
2653
2654 flags          = "flags" [ flag-set ] "/" flag-set
2655 flag-set       = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ]
2656                  [ "W" ]
2657
2658 icmp-type      = "icmp-type" ( icmp-type-code | "{" icmp-list "}" )
2659 icmp6-type     = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" )
2660 icmp-type-code = ( icmp-type-name | icmp-type-number )
2661                  [ "code" ( icmp-code-name | icmp-code-number ) ]
2662 icmp-list      = icmp-type-code [ [ "," ] icmp-list ]
2663
2664 tos            = "tos" ( "lowdelay" | "throughput" | "reliability" |
2665                  [ "0x" ] number )
2666
2667 state-opts     = state-opt [ [ "," ] state-opts ]
2668 state-opt      = ( "max" number | "no-sync" | timeout |
2669                  "source-track" [ ( "rule" | "global" ) ] |
2670                  "max-src-nodes" number | "max-src-states" number |
2671                  "if-bound" | "group-bound" | "floating" )
2672
2673 fragmentation  = [ "fragment reassemble" | "fragment crop" |
2674                  "fragment drop-ovl" ]
2675
2676 timeout-list   = timeout [ [ "," ] timeout-list ]
2677 timeout        = ( "tcp.first" | "tcp.opening" | "tcp.established" |
2678                  "tcp.closing" | "tcp.finwait" | "tcp.closed" |
2679                  "udp.first" | "udp.single" | "udp.multiple" |
2680                  "icmp.first" | "icmp.error" |
2681                  "other.first" | "other.single" | "other.multiple" |
2682                  "frag" | "interval" | "src.track" |
2683                  "adaptive.start" | "adaptive.end" ) number
2684
2685 limit-list     = limit-item [ [ "," ] limit-list ]
2686 limit-item     = ( "states" | "frags" | "src-nodes" ) number
2687
2688 pooltype       = ( "bitmask" | "random" |
2689                  "source-hash" [ ( hex-key | string-key ) ] |
2690                  "round-robin" ) [ sticky-address ]
2691
2692 subqueue       = string | "{" queue-list "}"
2693 queue-list     = string [ [ "," ] string ]
2694 cbq-def        = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ]
2695 priq-def       = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ]
2696 hfsc-def       = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ]
2697 cbq-opt        = ( "default" | "borrow" | "red" | "ecn" | "rio" )
2698 priq-opt       = ( "default" | "red" | "ecn" | "rio" )
2699 hfsc-opt       = ( "default" | "red" | "ecn" | "rio" |
2700                  linkshare-sc | realtime-sc | upperlimit-sc )
2701 linkshare-sc   = "linkshare" sc-spec
2702 realtime-sc    = "realtime" sc-spec
2703 upperlimit-sc  = "upperlimit" sc-spec
2704 sc-spec        = ( bandwidth-spec |
2705                  "(" bandwidth-spec number bandwidth-spec ")" )
2706 .Ed
2707 .Sh SEE ALSO
2708 .Xr icmp 4 ,
2709 .Xr icmp6 4 ,
2710 .Xr ip 4 ,
2711 .Xr ip6 4 ,
2712 .Xr pf 4 ,
2713 .Xr pfsync 4 ,
2714 .Xr tcp 4 ,
2715 .Xr udp 4 ,
2716 .Xr hosts 5 ,
2717 .Xr pf.os 5 ,
2718 .Xr protocols 5 ,
2719 .Xr services 5 ,
2720 .Xr ftp-proxy 8 ,
2721 .Xr pfctl 8 ,
2722 .Xr pflogd 8
2723 .Sh HISTORY
2724 The
2725 .Nm
2726 file format first appeared in
2727 .Ox 3.0 .