1.\" $OpenBSD: pf.conf.5,v 1.406 2009/01/31 19:37:12 sobrado Exp $ 2.\" 3.\" Copyright (c) 2002, Daniel Hartmeier 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" - Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" - Redistributions in binary form must reproduce the above 13.\" copyright notice, this list of conditions and the following 14.\" disclaimer in the documentation and/or other materials provided 15.\" with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 20.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 21.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 25.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 27.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd July 30, 2025 31.Dt PF.CONF 5 32.Os 33.Sh NAME 34.Nm pf.conf 35.Nd packet filter configuration file 36.Sh DESCRIPTION 37The 38.Xr pf 4 39packet filter modifies, drops or passes packets according to rules or 40definitions specified in 41.Nm pf.conf . 42.Sh STATEMENT ORDER 43There are eight types of statements in 44.Nm pf.conf : 45.Bl -tag -width xxxx 46.It Cm Macros 47User-defined variables may be defined and used later, simplifying 48the configuration file. 49Macros must be defined before they are referenced in 50.Nm pf.conf . 51.It Cm Tables 52Tables provide a mechanism for increasing the performance and flexibility of 53rules with large numbers of source or destination addresses. 54.It Cm Options 55Options tune the behaviour of the packet filtering engine. 56.It Cm Ethernet Filtering 57Ethernet filtering provides rule-based blocking or passing of Ethernet packets. 58.It Cm Traffic Normalization Li (e.g. Em scrub ) 59Traffic normalization protects internal machines against inconsistencies 60in Internet protocols and implementations. 61.It Cm Queueing 62Queueing provides rule-based bandwidth control. 63.It Cm Translation Li (Various forms of NAT) 64Translation rules specify how addresses are to be mapped or redirected to 65other addresses. 66.It Cm Packet Filtering 67Packet filtering provides rule-based blocking or passing of packets. 68.El 69.Pp 70With the exception of 71.Cm macros 72and 73.Cm tables , 74the types of statements should be grouped and appear in 75.Nm pf.conf 76in the order shown above, as this matches the operation of the underlying 77packet filtering engine. 78By default 79.Xr pfctl 8 80enforces this order (see 81.Ar set require-order 82below). 83.Pp 84Comments can be put anywhere in the file using a hash mark 85.Pq Sq # , 86and extend to the end of the current line. 87.Pp 88Additional configuration files can be included with the 89.Ic include 90keyword, for example: 91.Bd -literal -offset indent 92include "/etc/pf/sub.filter.conf" 93.Ed 94.Sh MACROS 95Macros can be defined that will later be expanded in context. 96Macro names must start with a letter, and may contain letters, digits 97and underscores. 98Macro names may not be reserved words (for example 99.Ar pass , 100.Ar in , 101.Ar out ) . 102Macros are not expanded inside quotes. 103Ranges of network addresses used in macros that will be expanded in lists 104later on must be quoted with additional simple quotes. 105.Pp 106For example, 107.Bd -literal -offset indent 108ext_if = \&"kue0\&" 109all_ifs = \&"{\&" $ext_if lo0 \&"}\&" 110pass out on $ext_if from any to any 111pass in on $ext_if proto tcp from any to any port 25 112 113usr_lan_range = "'192.0.2.0/24'" 114srv_lan_range = "'198.51.100.0 - 198.51.100.255'" 115nat_ranges = \&"{\&" $usr_lan_range $srv_lan_range \&"}\&" 116nat on $ext_if from $nat_ranges to any -> ($ext_if) 117.Ed 118.Sh TABLES 119Tables are named structures which can hold a collection of addresses and 120networks. 121Lookups against tables in 122.Xr pf 4 123are relatively fast, making a single rule with tables much more efficient, 124in terms of 125processor usage and memory consumption, than a large number of rules which 126differ only in IP address (either created explicitly or automatically by rule 127expansion). 128.Pp 129Tables can be used as the source or destination of filter rules, 130.Ar scrub 131rules 132or 133translation rules such as 134.Ar nat 135or 136.Ar rdr 137(see below for details on the various rule types). 138Tables can also be used for the redirect address of 139.Ar nat 140and 141.Ar rdr 142and in the routing options of filter rules, but not for 143.Ar bitmask 144pools. 145.Pp 146Tables can be defined with any of the following 147.Xr pfctl 8 148mechanisms. 149As with macros, reserved words may not be used as table names. 150.Bl -tag -width "manually" 151.It Ar manually 152Persistent tables can be manually created with the 153.Ar add 154or 155.Ar replace 156option of 157.Xr pfctl 8 , 158before or after the ruleset has been loaded. 159.It Pa pf.conf 160Table definitions can be placed directly in this file, and loaded at the 161same time as other rules are loaded, atomically. 162Table definitions inside 163.Nm pf.conf 164use the 165.Ar table 166statement, and are especially useful to define non-persistent tables. 167The contents of a pre-existing table defined without a list of addresses 168to initialize it is not altered when 169.Nm pf.conf 170is loaded. 171A table initialized with the empty list, 172.Li { } , 173will be cleared on load. 174.El 175.Pp 176Tables may be defined with the following attributes: 177.Bl -tag -width counters 178.It Ar persist 179The 180.Ar persist 181flag forces the kernel to keep the table even when no rules refer to it. 182If the flag is not set, the kernel will automatically remove the table 183when the last rule referring to it is flushed. 184.It Ar const 185The 186.Ar const 187flag prevents the user from altering the contents of the table once it 188has been created. 189Without that flag, 190.Xr pfctl 8 191can be used to add or remove addresses from the table at any time, even 192when running with 193.Xr securelevel 7 194= 2. 195.It Ar counters 196The 197.Ar counters 198flag enables per-address packet and byte counters which can be displayed with 199.Xr pfctl 8 . 200Note that this feature carries significant memory overhead for large tables. 201.El 202.Pp 203For example, 204.Bd -literal -offset indent 205table <private> const { 10/8, 172.16/12, 192.168/16 } 206table <badhosts> persist 207block on fxp0 from { <private>, <badhosts> } to any 208.Ed 209.Pp 210creates a table called private, to hold RFC 1918 private network 211blocks, and a table called badhosts, which is initially empty. 212A filter rule is set up to block all traffic coming from addresses listed in 213either table. 214The private table cannot have its contents changed and the badhosts table 215will exist even when no active filter rules reference it. 216Addresses may later be added to the badhosts table, so that traffic from 217these hosts can be blocked by using 218.Bd -literal -offset indent 219# pfctl -t badhosts -Tadd 204.92.77.111 220.Ed 221.Pp 222A table can also be initialized with an address list specified in one or more 223external files, using the following syntax: 224.Bd -literal -offset indent 225table <spam> persist file \&"/etc/spammers\&" file \&"/etc/openrelays\&" 226block on fxp0 from <spam> to any 227.Ed 228.Pp 229The files 230.Pa /etc/spammers 231and 232.Pa /etc/openrelays 233list IP addresses, one per line. 234Any lines beginning with a # are treated as comments and ignored. 235In addition to being specified by IP address, hosts may also be 236specified by their hostname. 237When the resolver is called to add a hostname to a table, 238.Em all 239resulting IPv4 and IPv6 addresses are placed into the table. 240IP addresses can also be entered in a table by specifying a valid interface 241name, a valid interface group or the 242.Em self 243keyword, in which case all addresses assigned to the interface(s) will be 244added to the table. 245.Sh OPTIONS 246.Xr pf 4 247may be tuned for various situations using the 248.Ar set 249command. 250.Bl -tag -width xxxx 251.It Ar set timeout 252.Pp 253.Bl -tag -width "src.track" -compact 254.It Ar interval 255Interval between purging expired states and fragments. 256.It Ar frag 257Seconds before an unassembled fragment is expired. 258.It Ar src.track 259Length of time to retain a source tracking entry after the last state 260expires. 261.El 262.Pp 263When a packet matches a stateful connection, the seconds to live for the 264connection will be updated to that of the 265.Ar proto.modifier 266which corresponds to the connection state. 267Each packet which matches this state will reset the TTL. 268Tuning these values may improve the performance of the 269firewall at the risk of dropping valid idle connections. 270.Pp 271.Bl -tag -width xxxx -compact 272.It Ar tcp.first 273The state after the first packet. 274.It Ar tcp.opening 275The state after the second packet but before both endpoints have 276acknowledged the connection. 277.It Ar tcp.established 278The fully established state. 279.It Ar tcp.closing 280The state after the first FIN has been sent. 281.It Ar tcp.finwait 282The state after both FINs have been exchanged and the connection is closed. 283Some hosts (notably web servers on Solaris) send TCP packets even after closing 284the connection. 285Increasing 286.Ar tcp.finwait 287(and possibly 288.Ar tcp.closing ) 289can prevent blocking of such packets. 290.It Ar tcp.closed 291The state after one endpoint sends an RST. 292.El 293.Pp 294SCTP timeout are handled similar to TCP, but with its own set of states: 295.Pp 296.Bl -tag -width xxxx -compact 297.It Ar sctp.first 298The state after the first packet. 299.It Ar sctp.opening 300The state before the destination host ever sends a packet. 301.It Ar sctp.established 302The fully established state. 303.It Ar sctp.closing 304The state after the first SHUTDOWN chunk has been sent. 305.It Ar sctp.closed 306The state after SHUTDOWN_ACK has been exchanged and the connection is closed. 307.El 308.Pp 309ICMP and UDP are handled in a fashion similar to TCP, but with a much more 310limited set of states: 311.Pp 312.Bl -tag -width xxxx -compact 313.It Ar udp.first 314The state after the first packet. 315.It Ar udp.single 316The state if the source host sends more than one packet but the destination 317host has never sent one back. 318.It Ar udp.multiple 319The state if both hosts have sent packets. 320.It Ar icmp.first 321The state after the first packet. 322.It Ar icmp.error 323The state after an ICMP error came back in response to an ICMP packet. 324.El 325.Pp 326Other protocols are handled similarly to UDP: 327.Pp 328.Bl -tag -width xxxx -compact 329.It Ar other.first 330.It Ar other.single 331.It Ar other.multiple 332.El 333.Pp 334Timeout values can be reduced adaptively as the number of state table 335entries grows. 336.Pp 337.Bl -tag -width xxxx -compact 338.It Ar adaptive.start 339When the number of state entries exceeds this value, adaptive scaling 340begins. 341All timeout values are scaled linearly with factor 342(adaptive.end - number of states) / (adaptive.end - adaptive.start). 343.It Ar adaptive.end 344When reaching this number of state entries, all timeout values become 345zero, effectively purging all state entries immediately. 346This value is used to define the scale factor, it should not actually 347be reached (set a lower state limit, see below). 348.El 349.Pp 350Adaptive timeouts are enabled by default, with an adaptive.start value 351equal to 60% of the state limit, and an adaptive.end value equal to 352120% of the state limit. 353They can be disabled by setting both adaptive.start and adaptive.end to 0. 354.Pp 355The adaptive timeout values can be defined both globally and for each rule. 356When used on a per-rule basis, the values relate to the number of 357states created by the rule, otherwise to the total number of 358states. 359.Pp 360For example: 361.Bd -literal -offset indent 362set timeout tcp.first 120 363set timeout tcp.established 86400 364set timeout { adaptive.start 60000, adaptive.end 120000 } 365set limit states 100000 366.Ed 367.Pp 368With 90000 state table entries, the timeout values are scaled to 50% 369(tcp.first 60, tcp.established 43200). 370.It Ar set loginterface 371Enable collection of packet and byte count statistics for the given 372interface or interface group. 373These statistics can be viewed using 374.Bd -literal -offset indent 375# pfctl -s info 376.Ed 377.Pp 378In this example 379.Xr pf 4 380collects statistics on the interface named dc0: 381.Bd -literal -offset indent 382set loginterface dc0 383.Ed 384.Pp 385One can disable the loginterface using: 386.Bd -literal -offset indent 387set loginterface none 388.Ed 389.It Ar set limit 390Sets hard limits on the memory pools used by the packet filter. 391See 392.Xr zone 9 393for an explanation of memory pools. 394.Pp 395Limits can be set on the following: 396.Bl -tag -width pktdelay_pkts 397.It Cm states 398Set the maximum number of entries in the memory pool used by state table 399entries (those generated by 400.Ar pass 401rules which do not specify 402.Cm no state ) . 403The default is 100000. 404.It Cm src-nodes 405Set the maximum number of entries in the memory pool used for tracking 406source IP addresses (generated by the 407.Ar sticky-address 408and 409.Ar src.track 410options). 411The default is 10000. 412.It Cm table-entries 413Set the number of addresses that can be stored in tables. 414The default is 200000. 415.It Cm anchors 416Set the number of anchors that can exist. 417The default is 512. 418.It Cm eth-anchors 419Set the number of anchors that can exist. 420The default is 512. 421.El 422.Pp 423Multiple limits can be combined on a single line: 424.Bd -literal -offset indent 425set limit { states 20000, frags 2000, src-nodes 2000 } 426.Ed 427.It Ar set ruleset-optimization 428.Bl -tag -width xxxxxxxx -compact 429.It Ar none 430Disable the ruleset optimizer. 431.It Ar basic 432Enable basic ruleset optimization. 433This is the default behaviour. 434Basic ruleset optimization does four things to improve the 435performance of ruleset evaluations: 436.Pp 437.Bl -enum -compact 438.It 439remove duplicate rules 440.It 441remove rules that are a subset of another rule 442.It 443combine multiple rules into a table when advantageous 444.It 445re-order the rules to improve evaluation performance 446.El 447.Pp 448.It Ar profile 449Uses the currently loaded ruleset as a feedback profile to tailor the 450ordering of quick rules to actual network traffic. 451.El 452.Pp 453It is important to note that the ruleset optimizer will modify the ruleset 454to improve performance. 455A side effect of the ruleset modification is that per-rule accounting 456statistics will have different meanings than before. 457If per-rule accounting is important for billing purposes or whatnot, 458either the ruleset optimizer should not be used or a label field should 459be added to all of the accounting rules to act as optimization barriers. 460.Pp 461Optimization can also be set as a command-line argument to 462.Xr pfctl 8 , 463overriding the settings in 464.Nm . 465.It Ar set optimization 466Optimize state timeouts for one of the following network environments: 467.Pp 468.Bl -tag -width xxxx -compact 469.It Ar normal 470A normal network environment. 471Suitable for almost all networks. 472.It Ar high-latency 473A high-latency environment (such as a satellite connection). 474.It Ar satellite 475Alias for 476.Ar high-latency . 477.It Ar aggressive 478Aggressively expire connections. 479This can greatly reduce the memory usage of the firewall at the cost of 480dropping idle connections early. 481.It Ar conservative 482Extremely conservative settings. 483Avoid dropping legitimate connections at the 484expense of greater memory utilization (possibly much greater on a busy 485network) and slightly increased processor utilization. 486.El 487.Pp 488For example: 489.Bd -literal -offset indent 490set optimization aggressive 491.Ed 492.It Ar set reassemble yes | no Op Cm no-df 493The 494.Cm reassemble 495option is used to enable or disable the reassembly of fragmented packets, 496and can be set to 497.Cm yes 498or 499.Cm no . 500If 501.Cm no-df 502is also specified, fragments with the 503.Dq dont-fragment 504bit set are reassembled too, 505instead of being dropped; 506the reassembled packet will have the 507.Dq dont-fragment 508bit cleared. 509The default value is 510.Cm no . 511.Pp 512This option is ignored if there are pre-FreeBSD 14 513.Cm scrub 514rules present. 515.It Ar set block-policy 516The 517.Ar block-policy 518option sets the default behaviour for the packet 519.Ar block 520action: 521.Pp 522.Bl -tag -width xxxxxxxx -compact 523.It Ar drop 524Packet is silently dropped. 525.It Ar return 526A TCP RST is returned for blocked TCP packets, 527an SCTP ABORT chunk is returned for blocked SCTP packets, 528an ICMP UNREACHABLE is returned for blocked UDP packets, 529and all other packets are silently dropped. 530.El 531.Pp 532The default value is 533.Cm drop . 534.Pp 535For example: 536.Bd -literal -offset indent 537set block-policy return 538.Ed 539.It Ar set fail-policy 540The 541.Ar fail-policy 542option sets the behaviour of rules which should pass a packet but were 543unable to do so. 544This might happen when a nat or route-to rule uses an empty table as list 545of targets or if a rule fails to create state or source node. 546The following 547.Ar block 548actions are possible: 549.Pp 550.Bl -tag -width xxxxxxxx -compact 551.It Ar drop 552Incoming packet is silently dropped. 553.It Ar return 554Incoming packet is dropped and TCP RST is returned for TCP packets, 555an SCTP ABORT chunk is returned for blocked SCTP packets, 556an ICMP UNREACHABLE is returned for UDP packets, 557and no response is sent for other packets. 558.El 559.Pp 560For example: 561.Bd -literal -offset indent 562set fail-policy return 563.Ed 564.It Ar set state-policy 565The 566.Ar state-policy 567option sets the default behaviour for states: 568.Pp 569.Bl -tag -width group-bound -compact 570.It Ar if-bound 571States are bound to interface. 572.It Ar floating 573States can match packets on any interfaces (the default). 574.El 575.Pp 576For example: 577.Bd -literal -offset indent 578set state-policy if-bound 579.Ed 580.It Ar set syncookies never | always | adaptive 581When 582.Cm syncookies 583are active, pf will answer each incoming TCP SYN with a syncookie SYNACK, 584without allocating any resources. 585Upon reception of the client's ACK in response to the syncookie 586SYNACK, pf will evaluate the ruleset and create state if the ruleset 587permits it, complete the three way handshake with the target host and 588continue the connection with synproxy in place. 589This allows pf to be resilient against large synflood attacks which would 590run the state table against its limits otherwise. 591Due to the blind answers to every incoming SYN syncookies share the caveats of 592synproxy, namely seemingly accepting connections that will be dropped later on. 593.Pp 594.Bl -tag -width adaptive -compact 595.It Cm never 596pf will never send syncookie SYNACKs (the default). 597.It Cm always 598pf will always send syncookie SYNACKs. 599.It Cm adaptive 600pf will enable syncookie mode when a given percentage of the state table 601is used up by half-open TCP connections, as in, those that saw the initial 602SYN but didn't finish the three way handshake. 603The thresholds for entering and leaving syncookie mode can be specified using 604.Bd -literal -offset indent 605set syncookies adaptive (start 25%, end 12%) 606.Ed 607.El 608.It Ar set state-defaults 609The 610.Ar state-defaults 611option sets the state options for states created from rules 612without an explicit 613.Ar keep state . 614For example: 615.Bd -literal -offset indent 616set state-defaults no-sync 617.Ed 618.It Ar set hostid 619The 32-bit 620.Ar hostid 621identifies this firewall's state table entries to other firewalls 622in a 623.Xr pfsync 4 624failover cluster. 625By default the hostid is set to a pseudo-random value, however it may be 626desirable to manually configure it, for example to more easily identify the 627source of state table entries. 628.Bd -literal -offset indent 629set hostid 1 630.Ed 631.Pp 632The hostid may be specified in either decimal or hexadecimal. 633.It Ar set require-order 634By default 635.Xr pfctl 8 636enforces an ordering of the statement types in the ruleset to: 637.Em options , 638.Em normalization , 639.Em queueing , 640.Em translation , 641.Em filtering . 642Setting this option to 643.Ar no 644disables this enforcement. 645There may be non-trivial and non-obvious implications to an out of 646order ruleset. 647Consider carefully before disabling the order enforcement. 648.It Ar set fingerprints 649Load fingerprints of known operating systems from the given filename. 650By default fingerprints of known operating systems are automatically 651loaded from 652.Xr pf.os 5 653in 654.Pa /etc 655but can be overridden via this option. 656Setting this option may leave a small period of time where the fingerprints 657referenced by the currently active ruleset are inconsistent until the new 658ruleset finishes loading. 659The default location for fingerprints is 660.Pa /etc/pf.os . 661.Pp 662For example: 663.Pp 664.Dl set fingerprints \&"/etc/pf.os.devel\&" 665.It Ar set skip on Aq Ar ifspec 666List interfaces for which packets should not be filtered. 667Packets passing in or out on such interfaces are passed as if pf was 668disabled, i.e. pf does not process them in any way. 669This can be useful on loopback and other virtual interfaces, when 670packet filtering is not desired and can have unexpected effects. 671For example: 672.Pp 673.Dl set skip on lo0 674.It Ar set debug 675Set the debug 676.Ar level 677to one of the following: 678.Pp 679.Bl -tag -width xxxxxxxxxxxx -compact 680.It Ar none 681Don't generate debug messages. 682.It Ar urgent 683Generate debug messages only for serious errors. 684.It Ar misc 685Generate debug messages for various errors. 686.It Ar loud 687Generate debug messages for common conditions. 688.El 689.It Ar set keepcounters 690Preserve rule counters across rule updates. 691Usually rule counters are reset to zero on every update of the ruleset. 692With 693.Ar keepcounters 694set pf will attempt to find matching rules between old and new rulesets 695and preserve the rule counters. 696.El 697.Sh ETHERNET FILTERING 698.Xr pf 4 699has the ability to 700.Ar block 701and 702.Ar pass 703packets based on attributes of their Ethernet (layer 2) header. 704.Pp 705Each time a packet processed by the packet filter comes in on or 706goes out through an interface, the filter rules are evaluated in 707sequential order, from first to last. 708The last matching rule decides what action is taken. 709If no rule matches the packet, the default action is to pass 710the packet without creating a state. 711.Pp 712The following actions can be used in the filter: 713.Bl -tag -width xxxx 714.It Ar block 715The packet is blocked. 716Unlike for layer 3 traffic the packet is always silently dropped. 717.It Ar pass 718The packet is passed; 719no state is created for layer 2 traffic. 720.El 721.Ss Parameters applicable to layer 2 rules 722The rule parameters specify the packets to which a rule applies. 723A packet always comes in on, or goes out through, one interface. 724Most parameters are optional. 725If a parameter is specified, the rule only applies to packets with 726matching attributes. 727The matching for some parameters can be inverted with the 728.Cm !\& 729operator. 730Certain parameters can be expressed as lists, in which case 731.Xr pfctl 8 732generates all needed rule combinations. 733.Bl -tag -width xxxx 734.It Ar in No or Ar out 735This rule applies to incoming or outgoing packets. 736If neither 737.Ar in 738nor 739.Ar out 740are specified, the rule will match packets in both directions. 741.It Ar quick 742If a packet matches a rule which has the 743.Ar quick 744option set, this rule 745is considered the last matching rule, and evaluation of subsequent rules 746is skipped. 747.It Ar on Aq Ar ifspec 748This rule applies only to packets coming in on, or going out through, this 749particular interface or interface group. 750For more information on interface groups, 751see the 752.Ic group 753keyword in 754.Xr ifconfig 8 . 755.Ar any 756will match any existing interface except loopback ones. 757.It Ar bridge-to Aq interface 758Packets matching this rule will be sent out of the specified interface without 759further processing. 760.It Ar proto Aq Ar protocol 761This rule applies only to packets of this protocol. 762Note that Ethernet protocol numbers are different from those used in 763.Xr ip 4 764and 765.Xr ip6 4 . 766.It Xo 767.Ar from Aq Ar source 768.Ar to Aq Ar dest 769.Xc 770This rule applies only to packets with the specified source and destination 771MAC addresses. 772.It Xo Ar queue Aq Ar queue 773.Xc 774Packets matching this rule will be assigned to the specified queue. 775See 776.Sx QUEUEING 777for setup details. 778.Pp 779.It Ar tag Aq Ar string 780Packets matching this rule will be tagged with the 781specified string. 782The tag acts as an internal marker that can be used to 783identify these packets later on. 784This can be used, for example, to provide trust between 785interfaces and to determine if packets have been 786processed by translation rules. 787Tags are 788.Qq sticky , 789meaning that the packet will be tagged even if the rule 790is not the last matching rule. 791Further matching rules can replace the tag with a 792new one but will not remove a previously applied tag. 793A packet is only ever assigned one tag at a time. 794.It Ar tagged Aq Ar string 795Used to specify that packets must already be tagged with the given tag in order 796to match the rule. 797Inverse tag matching can also be done by specifying the ! operator before the 798tagged keyword. 799.El 800.Sh TRAFFIC NORMALIZATION 801Traffic normalization is a broad umbrella term 802for aspects of the packet filter which deal with 803verifying packets, packet fragments, spoofed traffic, 804and other irregularities. 805.Ss Scrub 806Scrub involves sanitising packet content in such a way 807that there are no ambiguities in packet interpretation on the receiving side. 808It is invoked with the 809.Cm scrub 810option, added to filter rules. 811.Pp 812Parameters are specified enclosed in parentheses. 813At least one of the following parameters must be specified: 814.Bl -tag -width xxxx 815.It Ar no-df 816Clears the 817.Ar dont-fragment 818bit from a matching IP packet. 819Some operating systems are known to generate fragmented packets with the 820.Ar dont-fragment 821bit set. 822This is particularly true with NFS. 823.Ar Scrub 824will drop such fragmented 825.Ar dont-fragment 826packets unless 827.Ar no-df 828is specified. 829.Pp 830Unfortunately some operating systems also generate their 831.Ar dont-fragment 832packets with a zero IP identification field. 833Clearing the 834.Ar dont-fragment 835bit on packets with a zero IP ID may cause deleterious results if an 836upstream router later fragments the packet. 837Using the 838.Ar random-id 839modifier (see below) is recommended in combination with the 840.Ar no-df 841modifier to ensure unique IP identifiers. 842.It Ar min-ttl Aq Ar number 843Enforces a minimum TTL for matching IP packets. 844.It Ar max-mss Aq Ar number 845Reduces the maximum segment size (MSS) 846on TCP SYN packets to be no greater than 847.Ar number . 848This is sometimes required in scenarios where the two endpoints 849of a TCP connection are not able to carry similar sized packets 850and the resulting mismatch can lead to packet fragmentation or loss. 851Note that setting the MSS this way can have undesirable effects, 852such as interfering with the OS detection features of 853.Xr pf 4 . 854.It Xo Ar set-tos Aq Ar string 855.No \*(Ba Aq Ar number 856.Xc 857Enforces a 858.Em TOS 859for matching IP packets. 860.Em TOS 861may be 862given as one of 863.Ar critical , 864.Ar inetcontrol , 865.Ar lowdelay , 866.Ar netcontrol , 867.Ar throughput , 868.Ar reliability , 869or one of the DiffServ Code Points: 870.Ar ef , 871.Ar va , 872.Ar af11 No ... Ar af43 , 873.Ar cs0 No ... Ar cs7 ; 874or as either hex or decimal. 875.It Ar random-id 876Replaces the IP identification field with random values to compensate 877for predictable values generated by many hosts. 878This option only applies to packets that are not fragmented 879after the optional fragment reassembly. 880.It Ar reassemble tcp 881Statefully normalizes TCP connections. 882.Ar reassemble tcp 883performs the following normalizations: 884.Pp 885.Bl -tag -width timeout -compact 886.It ttl 887Neither side of the connection is allowed to reduce their IP TTL. 888An attacker may send a packet such that it reaches the firewall, affects 889the firewall state, and expires before reaching the destination host. 890.Ar reassemble tcp 891will raise the TTL of all packets back up to the highest value seen on 892the connection. 893.It timestamp modulation 894Modern TCP stacks will send a timestamp on every TCP packet and echo 895the other endpoint's timestamp back to them. 896Many operating systems will merely start the timestamp at zero when 897first booted, and increment it several times a second. 898The uptime of the host can be deduced by reading the timestamp and multiplying 899by a constant. 900Also observing several different timestamps can be used to count hosts 901behind a NAT device. 902And spoofing TCP packets into a connection requires knowing or guessing 903valid timestamps. 904Timestamps merely need to be monotonically increasing and not derived off a 905guessable base time. 906.Ar reassemble tcp 907will cause 908.Ar scrub 909to modulate the TCP timestamps with a random number. 910.It extended PAWS checks 911There is a problem with TCP on long fat pipes, in that a packet might get 912delayed for longer than it takes the connection to wrap its 32-bit sequence 913space. 914In such an occurrence, the old packet would be indistinguishable from a 915new packet and would be accepted as such. 916The solution to this is called PAWS: Protection Against Wrapped Sequence 917numbers. 918It protects against it by making sure the timestamp on each packet does 919not go backwards. 920.Ar reassemble tcp 921also makes sure the timestamp on the packet does not go forward more 922than the RFC allows. 923By doing this, 924.Xr pf 4 925artificially extends the security of TCP sequence numbers by 10 to 18 926bits when the host uses appropriately randomized timestamps, since a 927blind attacker would have to guess the timestamp as well. 928.El 929.El 930.Pp 931For example, 932.Bd -literal -offset indent 933match in all scrub (no-df random-id max-mss 1440) 934.Ed 935.Ss Scrub ruleset (pre-FreeBSD 14) 936In order to maintain compatibility with older releases of FreeBSD 937.Ar scrub 938rules can also be specified in their own ruleset. 939In such case they are invoked with the 940.Ar scrub 941directive. 942If there are such rules present they determine packet reassembly behaviour. 943When no such rules are present the option 944.Ar set reassembly 945takes precedence. 946The 947.Ar scrub 948rules can take all parameters specified above for a 949.Ar scrub 950option of filter rules and 2 more parameters controlling fragment reassembly: 951.Bl -tag -width xxxx 952.It Ar fragment reassemble 953Using 954.Ar scrub 955rules, fragments can be reassembled by normalization. 956In this case, fragments are buffered until they form a complete 957packet, and only the completed packet is passed on to the filter. 958The advantage is that filter rules have to deal only with complete 959packets, and can ignore fragments. 960The drawback of caching fragments is the additional memory cost. 961This is the default behaviour unless no fragment reassemble is specified. 962.It Ar no fragment reassemble 963Do not reassemble fragments. 964.El 965.Pp 966For example, 967.Bd -literal -offset indent 968scrub in on $ext_if all fragment reassemble 969.Ed 970.Pp 971The 972.Ar no 973option prefixed to a scrub rule causes matching packets to remain unscrubbed, 974much in the same way as 975.Ar drop quick 976works in the packet filter (see below). 977This mechanism should be used when it is necessary to exclude specific packets 978from broader scrub rules. 979.Pp 980.Ar scrub 981rules in the 982.Ar scrub 983ruleset are evaluated for every packet before stateful filtering. 984This means excessive usage of them will cause performance penalty. 985.Ar scrub reassemble tcp 986rules must not have the direction (in/out) specified. 987.Sh QUEUEING with ALTQ 988The ALTQ system is currently not available in the GENERIC kernel nor as 989loadable modules. 990In order to use the herein after called queueing options one has to use a 991custom built kernel. 992Please refer to 993.Xr altq 4 994to learn about the related kernel options. 995.Pp 996Packets can be assigned to queues for the purpose of bandwidth 997control. 998At least two declarations are required to configure queues, and later 999any packet filtering rule can reference the defined queues by name. 1000During the filtering component of 1001.Nm pf.conf , 1002the last referenced 1003.Ar queue 1004name is where any packets from 1005.Ar pass 1006rules will be queued, while for 1007.Ar block 1008rules it specifies where any resulting ICMP or TCP RST 1009packets should be queued. 1010The 1011.Ar scheduler 1012defines the algorithm used to decide which packets get delayed, dropped, or 1013sent out immediately. 1014There are three 1015.Ar schedulers 1016currently supported. 1017.Bl -tag -width xxxx 1018.It Ar cbq 1019Class Based Queueing. 1020.Ar Queues 1021attached to an interface build a tree, thus each 1022.Ar queue 1023can have further child 1024.Ar queues . 1025Each queue can have a 1026.Ar priority 1027and a 1028.Ar bandwidth 1029assigned. 1030.Ar Priority 1031mainly controls the time packets take to get sent out, while 1032.Ar bandwidth 1033has primarily effects on throughput. 1034.Ar cbq 1035achieves both partitioning and sharing of link bandwidth 1036by hierarchically structured classes. 1037Each class has its own 1038.Ar queue 1039and is assigned its share of 1040.Ar bandwidth . 1041A child class can borrow bandwidth from its parent class 1042as long as excess bandwidth is available 1043(see the option 1044.Ar borrow , 1045below). 1046.It Ar priq 1047Priority Queueing. 1048.Ar Queues 1049are flat attached to the interface, thus, 1050.Ar queues 1051cannot have further child 1052.Ar queues . 1053Each 1054.Ar queue 1055has a unique 1056.Ar priority 1057assigned, ranging from 0 to 15. 1058Packets in the 1059.Ar queue 1060with the highest 1061.Ar priority 1062are processed first. 1063.It Ar hfsc 1064Hierarchical Fair Service Curve. 1065.Ar Queues 1066attached to an interface build a tree, thus each 1067.Ar queue 1068can have further child 1069.Ar queues . 1070Each queue can have a 1071.Ar priority 1072and a 1073.Ar bandwidth 1074assigned. 1075.Ar Priority 1076mainly controls the time packets take to get sent out, while 1077.Ar bandwidth 1078primarily affects throughput. 1079.Ar hfsc 1080supports both link-sharing and guaranteed real-time services. 1081It employs a service curve based QoS model, 1082and its unique feature is an ability to decouple 1083.Ar delay 1084and 1085.Ar bandwidth 1086allocation. 1087.El 1088.Pp 1089The interfaces on which queueing should be activated are declared using 1090the 1091.Ar altq on 1092declaration. 1093.Ar altq on 1094has the following keywords: 1095.Bl -tag -width xxxx 1096.It Aq Ar interface 1097Queueing is enabled on the named interface. 1098.It Aq Ar scheduler 1099Specifies which queueing scheduler to use. 1100Currently supported values 1101are 1102.Ar cbq 1103for Class Based Queueing, 1104.Ar priq 1105for Priority Queueing and 1106.Ar hfsc 1107for the Hierarchical Fair Service Curve scheduler. 1108.It Ar bandwidth Aq Ar bw 1109The maximum bitrate for all queues on an 1110interface may be specified using the 1111.Ar bandwidth 1112keyword. 1113The value can be specified as an absolute value or as a 1114percentage of the interface bandwidth. 1115When using an absolute value, the suffixes 1116.Ar b , 1117.Ar Kb , 1118.Ar Mb , 1119and 1120.Ar Gb 1121are used to represent bits, kilobits, megabits, and 1122gigabits per second, respectively. 1123The value must not exceed the interface bandwidth. 1124If 1125.Ar bandwidth 1126is not specified, the interface bandwidth is used 1127(but take note that some interfaces do not know their bandwidth, 1128or can adapt their bandwidth rates). 1129.It Ar qlimit Aq Ar limit 1130The maximum number of packets held in the queue. 1131The default is 50. 1132.It Ar tbrsize Aq Ar size 1133Adjusts the size, in bytes, of the token bucket regulator. 1134If not specified, heuristics based on the 1135interface bandwidth are used to determine the size. 1136.It Ar queue Aq Ar list 1137Defines a list of subqueues to create on an interface. 1138.El 1139.Pp 1140In the following example, the interface dc0 1141should queue up to 5Mbps in four second-level queues using 1142Class Based Queueing. 1143Those four queues will be shown in a later example. 1144.Bd -literal -offset indent 1145altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } 1146.Ed 1147.Pp 1148Once interfaces are activated for queueing using the 1149.Ar altq 1150directive, a sequence of 1151.Ar queue 1152directives may be defined. 1153The name associated with a 1154.Ar queue 1155must match a queue defined in the 1156.Ar altq 1157directive (e.g. mail), or, except for the 1158.Ar priq 1159.Ar scheduler , 1160in a parent 1161.Ar queue 1162declaration. 1163The following keywords can be used: 1164.Bl -tag -width xxxx 1165.It Ar on Aq Ar interface 1166Specifies the interface the queue operates on. 1167If not given, it operates on all matching interfaces. 1168.It Ar bandwidth Aq Ar bw 1169Specifies the maximum bitrate to be processed by the queue. 1170This value must not exceed the value of the parent 1171.Ar queue 1172and can be specified as an absolute value or a percentage of the parent 1173queue's bandwidth. 1174If not specified, defaults to 100% of the parent queue's bandwidth. 1175The 1176.Ar priq 1177scheduler does not support bandwidth specification. 1178.It Ar priority Aq Ar level 1179Between queues a priority level can be set. 1180For 1181.Ar cbq 1182and 1183.Ar hfsc , 1184the range is 0 to 7 and for 1185.Ar priq , 1186the range is 0 to 15. 1187The default for all is 1. 1188.Ar Priq 1189queues with a higher priority are always served first. 1190.Ar Cbq 1191and 1192.Ar Hfsc 1193queues with a higher priority are preferred in the case of overload. 1194.It Ar qlimit Aq Ar limit 1195The maximum number of packets held in the queue. 1196The default is 50. 1197.El 1198.Pp 1199The 1200.Ar scheduler 1201can get additional parameters with 1202.Xo Aq Ar scheduler 1203.Pf ( Aq Ar parameters ) . 1204.Xc 1205Parameters are as follows: 1206.Bl -tag -width Fl 1207.It Ar default 1208Packets not matched by another queue are assigned to this one. 1209Exactly one default queue is required. 1210.It Ar red 1211Enable RED (Random Early Detection) on this queue. 1212RED drops packets with a probability proportional to the average 1213queue length. 1214.It Ar rio 1215Enables RIO on this queue. 1216RIO is RED with IN/OUT, thus running 1217RED two times more than RIO would achieve the same effect. 1218RIO is currently not supported in the GENERIC kernel. 1219.It Ar ecn 1220Enables ECN (Explicit Congestion Notification) on this queue. 1221ECN implies RED. 1222.El 1223.Pp 1224The 1225.Ar cbq 1226.Ar scheduler 1227supports an additional option: 1228.Bl -tag -width Fl 1229.It Ar borrow 1230The queue can borrow bandwidth from the parent. 1231.El 1232.Pp 1233The 1234.Ar hfsc 1235.Ar scheduler 1236supports some additional options: 1237.Bl -tag -width Fl 1238.It Ar realtime Aq Ar sc 1239The minimum required bandwidth for the queue. 1240.It Ar upperlimit Aq Ar sc 1241The maximum allowed bandwidth for the queue. 1242.It Ar linkshare Aq Ar sc 1243The bandwidth share of a backlogged queue. 1244.El 1245.Pp 1246.Aq Ar sc 1247is an acronym for 1248.Ar service curve . 1249.Pp 1250The format for service curve specifications is 1251.Ar ( m1 , d , m2 ) . 1252.Ar m2 1253controls the bandwidth assigned to the queue. 1254.Ar m1 1255and 1256.Ar d 1257are optional and can be used to control the initial bandwidth assignment. 1258For the first 1259.Ar d 1260milliseconds the queue gets the bandwidth given as 1261.Ar m1 , 1262afterwards the value given in 1263.Ar m2 . 1264.Pp 1265Furthermore, with 1266.Ar cbq 1267and 1268.Ar hfsc , 1269child queues can be specified as in an 1270.Ar altq 1271declaration, thus building a tree of queues using a part of 1272their parent's bandwidth. 1273.Pp 1274Packets can be assigned to queues based on filter rules by using the 1275.Ar queue 1276keyword. 1277Normally only one 1278.Ar queue 1279is specified; when a second one is specified it will instead be used for 1280packets which have a 1281.Em TOS 1282of 1283.Em lowdelay 1284and for TCP ACKs with no data payload. 1285.Pp 1286To continue the previous example, the examples below would specify the 1287four referenced 1288queues, plus a few child queues. 1289Interactive 1290.Xr ssh 1 1291sessions get priority over bulk transfers like 1292.Xr scp 1 1293and 1294.Xr sftp 1 . 1295The queues may then be referenced by filtering rules (see 1296.Sx PACKET FILTERING 1297below). 1298.Bd -literal 1299queue std bandwidth 10% cbq(default) 1300queue http bandwidth 60% priority 2 cbq(borrow red) \e 1301 { employees, developers } 1302queue developers bandwidth 75% cbq(borrow) 1303queue employees bandwidth 15% 1304queue mail bandwidth 10% priority 0 cbq(borrow ecn) 1305queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } 1306queue ssh_interactive bandwidth 50% priority 7 cbq(borrow) 1307queue ssh_bulk bandwidth 50% priority 0 cbq(borrow) 1308 1309block return out on dc0 inet all queue std 1310pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e 1311 queue developers 1312pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e 1313 queue employees 1314pass out on dc0 inet proto tcp from any to any port 22 \e 1315 queue(ssh_bulk, ssh_interactive) 1316pass out on dc0 inet proto tcp from any to any port 25 \e 1317 queue mail 1318.Ed 1319.Sh QUEUEING with dummynet 1320Queueing can also be done with 1321.Xr dummynet 4 . 1322Queues and pipes can be created with 1323.Xr dnctl 8 . 1324.Pp 1325Packets can be assigned to queues and pipes using 1326.Ar dnqueue 1327and 1328.Ar dnpipe 1329respectively. 1330.Pp 1331Both 1332.Ar dnqueue 1333and 1334.Ar dnpipe 1335take either a single pipe or queue number or two numbers as arguments. 1336The first pipe or queue number will be used to shape the traffic in the rule 1337direction, the second will be used to shape the traffic in the reverse 1338direction. 1339If the rule does not specify a direction the first packet to create state will 1340be shaped according to the first number, and the response traffic according to 1341the second. 1342.Pp 1343If the 1344.Xr dummynet 4 1345module is not loaded any traffic sent into a queue or pipe will be dropped. 1346.Sh TRANSLATION 1347Translation options modify either the source or destination address and 1348port of the packets associated with a stateful connection. 1349.Xr pf 4 1350modifies the specified address and/or port in the packet and recalculates 1351IP, TCP, and UDP checksums as necessary. 1352.Pp 1353If specified on a 1354.Ic match 1355rule, subsequent rules will see packets as they look 1356after any addresses and ports have been translated. 1357These rules will therefore have to filter based on the translated 1358address and port number. 1359.Pp 1360The state entry created permits 1361.Xr pf 4 1362to keep track of the original address for traffic associated with that state 1363and correctly direct return traffic for that connection. 1364.Pp 1365Various types of translation are possible with pf: 1366.Bl -tag -width xxxx 1367.It Ar af-to 1368Translation between different address families (NAT64) is handled 1369using 1370.Ar af-to 1371rules. 1372Because address family translation overrides the routing table, it's 1373only possible to use 1374.Ar af-to 1375on inbound rules, and a source address of the resulting translation 1376must always be specified. 1377.Pp 1378The optional second argument is the host or subnet the original 1379addresses are translated into for the destination. 1380The lowest bits of the original destination address form the host 1381part of the new destination address according to the specified subnet. 1382It is possible to embed a complete IPv4 address into an IPv6 address 1383using a network prefix of /96 or smaller. 1384.Pp 1385When a destination address is not specified, it is assumed that the host 1386part is 32-bit long. 1387For IPv6 to IPv4 translation this would mean using only the lower 32 1388bits of the original IPv6 destination address. 1389For IPv4 to IPv6 translation the destination subnet defaults to the 1390subnet of the new IPv6 source address with a prefix length of /96. 1391See RFC 6052 Section 2.2 for details on how the prefix determines the 1392destination address encoding. 1393.Pp 1394For example, the following rules are identical: 1395.Bd -literal -offset indent 1396pass in inet af-to inet6 from 2001:db8::1 to 2001:db8::/96 1397pass in inet af-to inet6 from 2001:db8::1 1398.Ed 1399.Pp 1400In the above example the matching IPv4 packets will be modified to 1401have a source address of 2001:db8::1 and a destination address will 1402get prefixed with 2001:db8::/96, e.g. 198.51.100.100 will be 1403translated to 2001:db8::c633:6464. 1404.Pp 1405In the reverse case the following rules are identical: 1406.Bd -literal -offset indent 1407pass in inet6 from any to 64:ff9b::/96 af-to inet \e 1408 from 198.51.100.1 to 0.0.0.0/0 1409pass in inet6 from any to 64:ff9b::/96 af-to inet \e 1410 from 198.51.100.1 1411.Ed 1412.Pp 1413The destination IPv4 address is assumed to be embedded inside the 1414original IPv6 destination address, e.g. 64:ff9b::c633:6464 will be 1415translated to 198.51.100.100. 1416.Pp 1417The current implementation will only extract IPv4 addresses from the 1418IPv6 addresses with a prefix length of /96 and greater. 1419.It Ar binat 1420A 1421.Ar binat-to 1422rule specifies a bidirectional mapping between an external IP netblock 1423and an internal IP netblock. 1424It expands to an outbound 1425.Ar nat-to 1426rule and an inbound 1427.Ar rdr-to 1428rule. 1429.It Ar nat-to 1430A 1431.Ar nat-to 1432option specifies that IP addresses are to be changed as the packet 1433traverses the given interface. 1434This technique allows one or more IP addresses 1435on the translating host to support network traffic for a larger range of 1436machines on an "inside" network. 1437Although in theory any IP address can be used on the inside, it is strongly 1438recommended that one of the address ranges defined by RFC 1918 be used. 1439These netblocks are: 1440.Bd -literal -offset indent 144110.0.0.0 - 10.255.255.255 (all of net 10.0.0.0, i.e., 10.0.0.0/8) 1442172.16.0.0 - 172.31.255.255 (i.e., 172.16.0.0/12) 1443192.168.0.0 - 192.168.255.255 (i.e., 192.168.0.0/16) 1444.Ed 1445.Pp 1446.Ar nat-to 1447is usually applied outbound. 1448If applied inbound, nat-to to a local IP address is not supported. 1449.It Pa rdr-to 1450The packet is redirected to another destination and possibly a 1451different port. 1452.Ar rdr-to 1453can optionally specify port ranges instead of single ports. 1454For instance: 1455.Bd -literal -offset indent 1456match in ... port 2000:2999 rdr-to ... port 4000 1457.Ed 1458redirects ports 2000 to 2999 (inclusive) to port 4000. 1459.Bd -literal -offset indent 1460qmatch in ... port 2000:2999 rdr-to ... port 4000:* 1461.Ed 1462redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999. 1463.El 1464.Pp 1465.Ar rdr-to 1466is usually applied inbound. 1467If applied outbound, rdr-to to a local IP address is not supported. 1468In addition to modifying the address, some translation rules may modify 1469source or destination ports for 1470.Xr tcp 4 1471or 1472.Xr udp 4 1473connections; implicitly in the case of 1474.Ar nat-to 1475options and both implicitly and explicitly in the case of 1476.Ar rdr-to 1477ones. 1478A 1479.Ar rdr-to 1480opion may cause the source port to be modified if doing so avoids a conflict 1481with an existing connection. 1482A random source port in the range 50001-65535 is chosen in this case. 1483Port numbers are never translated with a 1484.Ar binat-to 1485option. 1486.Pp 1487Note that redirecting external incoming connections to the loopback 1488address, as in 1489.Bd -literal -offset indent 1490pass in on egress proto tcp from any to any port smtp \e 1491 rdr-to 127.0.0.1 port spamd 1492.Ed 1493.Pp 1494will effectively allow an external host to connect to daemons 1495bound solely to the loopback address, circumventing the traditional 1496blocking of such connections on a real interface. 1497Unless this effect is desired, any of the local non-loopback addresses 1498should be used as redirection target instead, which allows external 1499connections only to daemons bound to this address or not bound to 1500any address. 1501.Pp 1502See 1503.Sx TRANSLATION EXAMPLES 1504below. 1505.Ss NAT ruleset (pre-FreeBSD 15) 1506In order to maintain compatibility with older releases of FreeBSD 1507.Ar NAT 1508rules can also be specified in their own ruleset. 1509A stateful connection is automatically created to track packets matching 1510such a rule as long as they are not blocked by the filtering section of 1511.Nm pf.conf . 1512Since translation occurs before filtering the filter 1513engine will see packets as they look after any 1514addresses and ports have been translated. 1515Filter rules will therefore have to filter based on the translated 1516address and port number. 1517Packets that match a translation rule are only automatically passed if 1518the 1519.Ar pass 1520modifier is given, otherwise they are 1521still subject to 1522.Ar block 1523and 1524.Ar pass 1525rules. 1526.Pp 1527The following rules can be defined in the NAT ruleset: 1528.Ar binat , 1529.Ar nat , 1530and 1531.Ar rdr . 1532They have the same effect as 1533.Ar binat-to , 1534.Ar nat-to 1535and 1536.Ar rdr-to 1537options for filter rules. 1538.Pp 1539The 1540.Ar no 1541option prefixed to a translation rule causes packets to remain untranslated, 1542much in the same way as 1543.Ar drop quick 1544works in the packet filter. 1545If no rule matches the packet it is passed to the filter engine unmodified. 1546.Pp 1547Evaluation order of the translation rules is dependent on the type 1548of the translation rules and of the direction of a packet. 1549.Ar binat 1550rules are always evaluated first. 1551Then either the 1552.Ar rdr 1553rules are evaluated on an inbound packet or the 1554.Ar nat 1555rules on an outbound packet. 1556Rules of the same type are evaluated in the same order in which they 1557appear in the ruleset. 1558The first matching rule decides what action is taken. 1559.Pp 1560Translation rules apply only to packets that pass through 1561the specified interface, and if no interface is specified, 1562translation is applied to packets on all interfaces. 1563For instance, redirecting port 80 on an external interface to an internal 1564web server will only work for connections originating from the outside. 1565Connections to the address of the external interface from local hosts will 1566not be redirected, since such packets do not actually pass through the 1567external interface. 1568Redirections cannot reflect packets back through the interface they arrive 1569on, they can only be redirected to hosts connected to different interfaces 1570or to the firewall itself. 1571.Pp 1572See 1573.Sx COMPATIBILITY TRANSLATION EXAMPLES 1574below. 1575.Sh PACKET FILTERING 1576.Xr pf 4 1577has the ability to 1578.Ar block 1579, 1580.Ar pass 1581and 1582.Ar match 1583packets based on attributes of their layer 3 (see 1584.Xr ip 4 1585and 1586.Xr ip6 4 ) 1587and layer 4 (see 1588.Xr icmp 4 , 1589.Xr icmp6 4 , 1590.Xr tcp 4 , 1591.Xr sctp 4 , 1592.Xr udp 4 ) 1593headers. 1594In addition, packets may also be 1595assigned to queues for the purpose of bandwidth control. 1596.Pp 1597For each packet processed by the packet filter, the filter rules are 1598evaluated in sequential order, from first to last. 1599For 1600.Ar block 1601and 1602.Ar pass 1603, the last matching rule decides what action is taken. 1604For 1605.Ar match 1606, rules are evaluated every time they match; the pass/block state of a packet 1607remains unchanged. 1608If no rule matches the packet, the default action is to pass 1609the packet. 1610.Pp 1611The following actions can be used in the filter: 1612.Bl -tag -width xxxx 1613.It Ar block 1614The packet is blocked. 1615There are a number of ways in which a 1616.Ar block 1617rule can behave when blocking a packet. 1618The default behaviour is to 1619.Ar drop 1620packets silently, however this can be overridden or made 1621explicit either globally, by setting the 1622.Ar block-policy 1623option, or on a per-rule basis with one of the following options: 1624.Pp 1625.Bl -tag -width xxxx -compact 1626.It Ar drop 1627The packet is silently dropped. 1628.It Ar return-rst 1629This applies only to 1630.Xr tcp 4 1631packets, and issues a TCP RST which closes the 1632connection. 1633.It Ar return-icmp 1634.It Ar return-icmp6 1635This causes ICMP messages to be returned for packets which match the rule. 1636By default this is an ICMP UNREACHABLE message, however this 1637can be overridden by specifying a message as a code or number. 1638.It Ar return 1639This causes a TCP RST to be returned for 1640.Xr tcp 4 1641packets, an SCTP ABORT for SCTP 1642and an ICMP UNREACHABLE for UDP and other packets. 1643.El 1644.Pp 1645Options returning ICMP packets currently have no effect if 1646.Xr pf 4 1647operates on a 1648.Xr if_bridge 4 , 1649as the code to support this feature has not yet been implemented. 1650.Pp 1651The simplest mechanism to block everything by default and only pass 1652packets that match explicit rules is specify a first filter rule of: 1653.Bd -literal -offset indent 1654block all 1655.Ed 1656.It Ar match 1657The packet is matched. 1658This mechanism is used to provide fine grained filtering without altering the 1659block/pass state of a packet. 1660.Ar match 1661rules differ from 1662.Ar block 1663and 1664.Ar pass 1665rules in that parameters are set for every rule a packet matches, not only 1666on the last matching rule. 1667For the following parameters, this means that the parameter effectively becomes 1668"sticky" until explicitly overridden: 1669.Ar nat-to , 1670.Ar binat-to , 1671.Ar rdr-to , 1672.Ar queue , 1673.Ar dnpipe , 1674.Ar dnqueue , 1675.Ar rtable , 1676.Ar scrub 1677. 1678.It Ar pass 1679The packet is passed; 1680state is created unless the 1681.Ar no state 1682option is specified. 1683.El 1684.Pp 1685By default 1686.Xr pf 4 1687filters packets statefully; the first time a packet matches a 1688.Ar pass 1689rule, a state entry is created; for subsequent packets the filter checks 1690whether the packet matches any state. 1691If it does, the packet is passed without evaluation of any rules. 1692After the connection is closed or times out, the state entry is automatically 1693removed. 1694.Pp 1695This has several advantages. 1696For TCP connections, comparing a packet to a state involves checking 1697its sequence numbers, as well as TCP timestamps if a 1698.Ar scrub reassemble tcp 1699rule applies to the connection. 1700If these values are outside the narrow windows of expected 1701values, the packet is dropped. 1702This prevents spoofing attacks, such as when an attacker sends packets with 1703a fake source address/port but does not know the connection's sequence 1704numbers. 1705Similarly, 1706.Xr pf 4 1707knows how to match ICMP replies to states. 1708For example, 1709.Bd -literal -offset indent 1710pass out inet proto icmp all icmp-type echoreq 1711.Ed 1712.Pp 1713allows echo requests (such as those created by 1714.Xr ping 8 ) 1715out statefully, and matches incoming echo replies correctly to states. 1716.Pp 1717Also, looking up states is usually faster than evaluating rules. 1718.Pp 1719Furthermore, correct handling of ICMP error messages is critical to 1720many protocols, particularly TCP. 1721.Xr pf 4 1722matches ICMP error messages to the correct connection, checks them against 1723connection parameters, and passes them if appropriate. 1724For example if an ICMP source quench message referring to a stateful TCP 1725connection arrives, it will be matched to the state and get passed. 1726.Pp 1727Finally, state tracking is required for 1728.Ar nat , binat No and Ar rdr 1729rules, in order to track address and port translations and reverse the 1730translation on returning packets. 1731.Pp 1732.Xr pf 4 1733will also create state for other protocols which are effectively stateless by 1734nature. 1735UDP packets are matched to states using only host addresses and ports, 1736and other protocols are matched to states using only the host addresses. 1737.Pp 1738If stateless filtering of individual packets is desired, 1739the 1740.Ar no state 1741keyword can be used to specify that state will not be created 1742if this is the last matching rule. 1743A number of parameters can also be set to affect how 1744.Xr pf 4 1745handles state tracking. 1746See 1747.Sx STATEFUL TRACKING OPTIONS 1748below for further details. 1749.Ss Parameters 1750The rule parameters specify the packets to which a rule applies. 1751A packet always comes in on, or goes out through, one interface. 1752Most parameters are optional. 1753If a parameter is specified, the rule only applies to packets with 1754matching attributes. 1755Certain parameters can be expressed as lists, in which case 1756.Xr pfctl 8 1757generates all needed rule combinations. 1758.Bl -tag -width xxxx 1759.It Ar in No or Ar out 1760This rule applies to incoming or outgoing packets. 1761If neither 1762.Ar in 1763nor 1764.Ar out 1765are specified, the rule will match packets in both directions. 1766.It Ar log Pq Cm all | matches | to Ao Ar interface Ac | Cm user 1767In addition to any action specified, 1768log the packet. 1769Only the packet that establishes the state is logged, 1770unless the 1771.Ar no state 1772option is specified. 1773The logged packets are sent to a 1774.Xr pflog 4 1775interface, by default pflog0; 1776pflog0 is monitored by the 1777.Xr pflogd 8 1778logging daemon which logs to the file 1779.Pa /var/log/pflog 1780in 1781.Xr pcap 3 1782binary format. 1783.Pp 1784The keywords 1785.Cm all , matches , to , 1786and 1787.Cm user 1788are optional and can be combined using commas, 1789but must be enclosed in parentheses if given. 1790.Pp 1791Use 1792.Cm all 1793to force logging of all packets for a connection. 1794This is not necessary when 1795.Ar no state 1796is explicitly specified. 1797.Pp 1798If 1799.Cm matches 1800is specified, 1801it logs the packet on all subsequent matching rules. 1802It is often combined with 1803.Cm to Aq Ar interface 1804to avoid adding noise to the default log file. 1805.Pp 1806The keyword 1807.Cm user 1808logs the 1809.Ux 1810user ID of the user that owns the socket and the PID of the process that 1811has the socket open where the packet is sourced from or destined to 1812(depending on which socket is local). 1813This is in addition to the normal information logged. 1814.Pp 1815Only the first packet 1816logged via 1817.Ar log (all, user) 1818will have the user credentials logged when using stateful matching. 1819.Pp 1820To specify a logging interface other than pflog0, 1821use the syntax 1822.Cm to Aq Ar interface . 1823.It Ar quick 1824If a packet matches a rule which has the 1825.Ar quick 1826option set, this rule 1827is considered the last matching rule, and evaluation of subsequent rules 1828is skipped. 1829.It Ar on Aq Ar interface 1830This rule applies only to packets coming in on, or going out through, this 1831particular interface or interface group. 1832For more information on interface groups, 1833see the 1834.Ic group 1835keyword in 1836.Xr ifconfig 8 . 1837.Ar any 1838will match any existing interface except loopback ones. 1839.It Aq Ar af 1840This rule applies only to packets of this address family. 1841Supported values are 1842.Ar inet 1843and 1844.Ar inet6 . 1845.It Ar proto Aq Ar protocol 1846This rule applies only to packets of this protocol. 1847Common protocols are 1848.Xr icmp 4 , 1849.Xr icmp6 4 , 1850.Xr tcp 4 , 1851.Xr sctp 4 , 1852and 1853.Xr udp 4 . 1854For a list of all the protocol name to number mappings used by 1855.Xr pfctl 8 , 1856see the file 1857.Pa /etc/protocols . 1858.It Xo 1859.Ar from Aq Ar source 1860.Ar port Aq Ar source 1861.Ar os Aq Ar source 1862.Ar to Aq Ar dest 1863.Ar port Aq Ar dest 1864.Xc 1865This rule applies only to packets with the specified source and destination 1866addresses and ports. 1867.Pp 1868Addresses can be specified in CIDR notation (matching netblocks), as 1869symbolic host names, interface names or interface group names, or as any 1870of the following keywords: 1871.Pp 1872.Bl -tag -width xxxxxxxxxxxxxx -compact 1873.It Ar any 1874Any address. 1875.It Ar no-route 1876Any address which is not currently routable. 1877.It Ar urpf-failed 1878Any source address that fails a unicast reverse path forwarding (URPF) 1879check, i.e. packets coming in on an interface other than that which holds 1880the route back to the packet's source address. 1881.It Ar self 1882Expands to all addresses assigned to all interfaces. 1883.It Aq Ar table 1884Any address that matches the given table. 1885.El 1886.Pp 1887Ranges of addresses are specified by using the 1888.Sq - 1889operator. 1890For instance: 1891.Dq 10.1.1.10 - 10.1.1.12 1892means all addresses from 10.1.1.10 to 10.1.1.12, 1893hence addresses 10.1.1.10, 10.1.1.11, and 10.1.1.12. 1894.Pp 1895Interface names and interface group names, and 1896.Ar self 1897can have modifiers appended: 1898.Pp 1899.Bl -tag -width xxxxxxxxxxxx -compact 1900.It Ar :network 1901Translates to the network(s) attached to the interface. 1902.It Ar :broadcast 1903Translates to the interface's broadcast address(es). 1904.It Ar :peer 1905Translates to the point-to-point interface's peer address(es). 1906.It Ar :0 1907Do not include interface aliases. 1908.El 1909.Pp 1910Host names may also have the 1911.Ar :0 1912option appended to restrict the name resolution to the first of each 1913v4 and non-link-local v6 address found. 1914.Pp 1915Host name resolution and interface to address translation are done at 1916ruleset load-time. 1917When the address of an interface (or host name) changes (under DHCP or PPP, 1918for instance), the ruleset must be reloaded for the change to be reflected 1919in the kernel. 1920Surrounding the interface name (and optional modifiers) in parentheses 1921changes this behaviour. 1922When the interface name is surrounded by parentheses, the rule is 1923automatically updated whenever the interface changes its address. 1924The ruleset does not need to be reloaded. 1925This is especially useful with 1926.Ar nat . 1927.Pp 1928Ports can be specified either by number or by name. 1929For example, port 80 can be specified as 1930.Em www . 1931For a list of all port name to number mappings used by 1932.Xr pfctl 8 , 1933see the file 1934.Pa /etc/services . 1935.Pp 1936Ports and ranges of ports are specified by using these operators: 1937.Bd -literal -offset indent 1938= (equal) 1939!= (unequal) 1940< (less than) 1941<= (less than or equal) 1942> (greater than) 1943>= (greater than or equal) 1944: (range including boundaries) 1945>< (range excluding boundaries) 1946<> (except range) 1947.Ed 1948.Pp 1949.Sq >< , 1950.Sq <> 1951and 1952.Sq \&: 1953are binary operators (they take two arguments). 1954For instance: 1955.Bl -tag -width Fl 1956.It Ar port 2000:2004 1957means 1958.Sq all ports >= 2000 and <= 2004 , 1959hence ports 2000, 2001, 2002, 2003 and 2004. 1960.It Ar port 2000 >< 2004 1961means 1962.Sq all ports > 2000 and < 2004 , 1963hence ports 2001, 2002 and 2003. 1964.It Ar port 2000 <> 2004 1965means 1966.Sq all ports < 2000 or > 2004 , 1967hence ports 1-1999 and 2005-65535. 1968.El 1969.Pp 1970The operating system of the source host can be specified in the case of TCP 1971rules with the 1972.Ar OS 1973modifier. 1974See the 1975.Sx OPERATING SYSTEM FINGERPRINTING 1976section for more information. 1977.Pp 1978The host, port and OS specifications are optional, as in the following examples: 1979.Bd -literal -offset indent 1980pass in all 1981pass in from any to any 1982pass in proto tcp from any port < 1024 to any 1983pass in proto tcp from any to any port 25 1984pass in proto tcp from 10.0.0.0/8 port >= 1024 \e 1985 to ! 10.1.2.3 port != ssh 1986pass in proto tcp from any os "OpenBSD" 1987.Ed 1988.It Ar all 1989This is equivalent to "from any to any". 1990.It Ar group Aq Ar group 1991Similar to 1992.Ar user , 1993this rule only applies to packets of sockets owned by the specified group. 1994.It Ar user Aq Ar user 1995This rule only applies to packets of sockets owned by the specified user. 1996For outgoing connections initiated from the firewall, this is the user 1997that opened the connection. 1998For incoming connections to the firewall itself, this is the user that 1999listens on the destination port. 2000For forwarded connections, where the firewall is not a connection endpoint, 2001the user and group are 2002.Em unknown . 2003.Pp 2004All packets, both outgoing and incoming, of one connection are associated 2005with the same user and group. 2006Only TCP and UDP packets can be associated with users; for other protocols 2007these parameters are ignored. 2008.Pp 2009User and group refer to the effective (as opposed to the real) IDs, in 2010case the socket is created by a setuid/setgid process. 2011User and group IDs are stored when a socket is created; 2012when a process creates a listening socket as root (for instance, by 2013binding to a privileged port) and subsequently changes to another 2014user ID (to drop privileges), the credentials will remain root. 2015.Pp 2016User and group IDs can be specified as either numbers or names. 2017The syntax is similar to the one for ports. 2018The value 2019.Em unknown 2020matches packets of forwarded connections. 2021.Em unknown 2022can only be used with the operators 2023.Cm = 2024and 2025.Cm != . 2026Other constructs like 2027.Cm user \*(Ge unknown 2028are invalid. 2029Forwarded packets with unknown user and group ID match only rules 2030that explicitly compare against 2031.Em unknown 2032with the operators 2033.Cm = 2034or 2035.Cm != . 2036For instance 2037.Cm user \*(Ge 0 2038does not match forwarded packets. 2039The following example allows only selected users to open outgoing 2040connections: 2041.Bd -literal -offset indent 2042block out proto { tcp, udp } all 2043pass out proto { tcp, udp } all user { < 1000, dhartmei } 2044.Ed 2045.Pp 2046The example below permits users with uid between 1000 and 1500 2047to open connections: 2048.Bd -literal -offset indent 2049block out proto tcp all 2050pass out proto tcp from self user { 999 >< 1501 } 2051.Ed 2052.Pp 2053The 2054.Sq \&: 2055operator, which works for port number matching, does not work for 2056.Cm user 2057and 2058.Cm group 2059match. 2060.It Xo Ar flags Aq Ar a 2061.Pf / Ns Aq Ar b 2062.No \*(Ba / Ns Aq Ar b 2063.No \*(Ba any 2064.Xc 2065This rule only applies to TCP packets that have the flags 2066.Aq Ar a 2067set out of set 2068.Aq Ar b . 2069Flags not specified in 2070.Aq Ar b 2071are ignored. 2072For stateful connections, the default is 2073.Ar flags S/SA . 2074To indicate that flags should not be checked at all, specify 2075.Ar flags any . 2076The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R. 2077.Bl -tag -width Fl 2078.It Ar flags S/S 2079Flag SYN is set. 2080The other flags are ignored. 2081.It Ar flags S/SA 2082This is the default setting for stateful connections. 2083Out of SYN and ACK, exactly SYN may be set. 2084SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not. 2085This is more restrictive than the previous example. 2086.It Ar flags /SFRA 2087If the first set is not specified, it defaults to none. 2088All of SYN, FIN, RST and ACK must be unset. 2089.El 2090.Pp 2091Because 2092.Ar flags S/SA 2093is applied by default (unless 2094.Ar no state 2095is specified), only the initial SYN packet of a TCP handshake will create 2096a state for a TCP connection. 2097It is possible to be less restrictive, and allow state creation from 2098intermediate 2099.Pq non-SYN 2100packets, by specifying 2101.Ar flags any . 2102This will cause 2103.Xr pf 4 2104to synchronize to existing connections, for instance 2105if one flushes the state table. 2106However, states created from such intermediate packets may be missing 2107connection details such as the TCP window scaling factor. 2108States which modify the packet flow, such as those affected by 2109.Ar af-to , 2110.Ar nat , 2111.Ar binat or 2112.Ar rdr 2113rules, 2114.Ar modulate No or Ar synproxy state 2115options, or scrubbed with 2116.Ar reassemble tcp 2117will also not be recoverable from intermediate packets. 2118Such connections will stall and time out. 2119.It Xo Ar icmp-type Aq Ar type 2120.Ar Op code Aq Ar code 2121.Xc 2122.It Xo Ar icmp6-type Aq Ar type 2123.Ar Op code Aq Ar code 2124.Xc 2125This rule only applies to ICMP or ICMPv6 packets with the specified type 2126and code. 2127Text names for ICMP types and codes are listed in 2128.Xr icmp 4 2129and 2130.Xr icmp6 4 . 2131This parameter is only valid for rules that cover protocols ICMP or 2132ICMP6. 2133The protocol and the ICMP type indicator 2134.Po 2135.Ar icmp-type 2136or 2137.Ar icmp6-type 2138.Pc 2139must match. 2140.It Xo Ar tos Aq Ar string 2141.No \*(Ba Aq Ar number 2142.Xc 2143This rule applies to packets with the specified 2144.Em TOS 2145bits set. 2146.Em TOS 2147may be 2148given as one of 2149.Ar critical , 2150.Ar inetcontrol , 2151.Ar lowdelay , 2152.Ar netcontrol , 2153.Ar throughput , 2154.Ar reliability , 2155or one of the DiffServ Code Points: 2156.Ar ef , 2157.Ar va , 2158.Ar af11 No ... Ar af43 , 2159.Ar cs0 No ... Ar cs7 ; 2160or as either hex or decimal. 2161.Pp 2162For example, the following rules are identical: 2163.Bd -literal -offset indent 2164pass all tos lowdelay 2165pass all tos 0x10 2166pass all tos 16 2167.Ed 2168.It Ar allow-opts 2169By default, packets with IPv4 options or IPv6 hop-by-hop or destination 2170options header are blocked. 2171When 2172.Ar allow-opts 2173is specified for a 2174.Ar pass 2175rule, packets that pass the filter based on that rule (last matching) 2176do so even if they contain options. 2177For packets that match state, the rule that initially created the 2178state is used. 2179The implicit 2180.Ar pass 2181rule, that is used when a packet does not match 2182any rules, does not allow IP options or option headers. 2183Note that IPv6 packets with type 0 routing headers are always dropped. 2184.It Ar label Aq Ar string 2185Adds a label (name) to the rule, which can be used to identify the rule. 2186For instance, 2187pfctl -s labels 2188shows per-rule statistics for rules that have labels. 2189.Pp 2190The following macros can be used in labels: 2191.Pp 2192.Bl -tag -width $srcaddr -compact -offset indent 2193.It Ar $if 2194The interface. 2195.It Ar $srcaddr 2196The source IP address. 2197.It Ar $dstaddr 2198The destination IP address. 2199.It Ar $srcport 2200The source port specification. 2201.It Ar $dstport 2202The destination port specification. 2203.It Ar $proto 2204The protocol name. 2205.It Ar $nr 2206The rule number. 2207.El 2208.Pp 2209For example: 2210.Bd -literal -offset indent 2211ips = \&"{ 1.2.3.4, 1.2.3.5 }\&" 2212pass in proto tcp from any to $ips \e 2213 port > 1023 label \&"$dstaddr:$dstport\&" 2214.Ed 2215.Pp 2216expands to 2217.Bd -literal -offset indent 2218pass in inet proto tcp from any to 1.2.3.4 \e 2219 port > 1023 label \&"1.2.3.4:>1023\&" 2220pass in inet proto tcp from any to 1.2.3.5 \e 2221 port > 1023 label \&"1.2.3.5:>1023\&" 2222.Ed 2223.Pp 2224The macro expansion for the 2225.Ar label 2226directive occurs only at configuration file parse time, not during runtime. 2227.It Ar ridentifier Aq Ar number 2228Add an identifier (number) to the rule, which can be used to correlate the rule 2229to pflog entries, even after ruleset updates. 2230.It Cm max-pkt-rate Ar number Ns / Ns Ar seconds 2231Measure the rate of packets matching the rule and states created by it. 2232When the specified rate is exceeded, the rule stops matching. 2233Only packets in the direction in which the state was created are considered, 2234so that typically requests are counted and replies are not. 2235For example, 2236to pass up to 100 ICMP packets per 10 seconds: 2237.Bd -literal -offset indent 2238block in proto icmp 2239pass in proto icmp max-pkt-rate 100/10 2240.Ed 2241.Pp 2242When the rate is exceeded, all ICMP is blocked until the rate falls below 2243100 per 10 seconds again. 2244.Pp 2245.It Ar max-pkt-size Aq Ar number 2246Limit each packet to be no more than the specified number of bytes. 2247This includes the IP header, but not any layer 2 header. 2248.It Xo Ar queue Aq Ar queue 2249.No \*(Ba ( Aq Ar queue , 2250.Aq Ar queue ) 2251.Xc 2252Packets matching this rule will be assigned to the specified queue. 2253If two queues are given, packets which have a 2254.Em TOS 2255of 2256.Em lowdelay 2257and TCP ACKs with no data payload will be assigned to the second one. 2258See 2259.Sx QUEUEING 2260for setup details. 2261.Pp 2262For example: 2263.Bd -literal -offset indent 2264pass in proto tcp to port 25 queue mail 2265pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio) 2266.Ed 2267.It Cm set prio Ar priority | Pq Ar priority , priority 2268Packets matching this rule will be assigned a specific queueing priority. 2269Priorities are assigned as integers 0 through 7. 2270If the packet is transmitted on a 2271.Xr vlan 4 2272interface, the queueing priority will be written as the priority 2273code point in the 802.1Q VLAN header. 2274If two priorities are given, TCP ACKs with no data payload and packets 2275which have a TOS of 2276.Cm lowdelay 2277will be assigned to the second one. 2278.Pp 2279For example: 2280.Bd -literal -offset indent 2281pass in proto tcp to port 25 set prio 2 2282pass in proto tcp to port 22 set prio (2, 5) 2283.Ed 2284.It Oo Cm \&! Oc Ns Cm received-on Ar interface 2285Only match packets which were received on the specified 2286.Ar interface 2287(or interface group). 2288.Ar any 2289will match any existing interface except loopback ones. 2290.It Ar tag Aq Ar string 2291Packets matching this rule will be tagged with the 2292specified string. 2293The tag acts as an internal marker that can be used to 2294identify these packets later on. 2295This can be used, for example, to provide trust between 2296interfaces and to determine if packets have been 2297processed by translation rules. 2298Tags are 2299.Qq sticky , 2300meaning that the packet will be tagged even if the rule 2301is not the last matching rule. 2302Further matching rules can replace the tag with a 2303new one but will not remove a previously applied tag. 2304A packet is only ever assigned one tag at a time. 2305Packet tagging can be done during 2306.Ar nat , 2307.Ar rdr , 2308.Ar binat 2309or 2310.Ar ether 2311rules in addition to filter rules. 2312Tags take the same macros as labels (see above). 2313.It Ar tagged Aq Ar string 2314Used with filter, translation or scrub rules 2315to specify that packets must already 2316be tagged with the given tag in order to match the rule. 2317.It Ar rtable Aq Ar number 2318Used to select an alternate routing table for the routing lookup. 2319Only effective before the route lookup happened, i.e. when filtering inbound. 2320.It Xo Ar divert-to Aq Ar host 2321.Ar port Aq Ar port 2322.Xc 2323Used to 2324.Xr divert 4 2325packets to the given divert 2326.Ar port . 2327Historically 2328.Ox pf has another meaning for this, and 2329.Fx pf uses 2330this syntax to support 2331.Xr divert 4 instead. Hence, 2332.Ar host 2333has no meaning and can be set to anything like 127.0.0.1. 2334If a packet is re-injected and does not change direction then it will not be 2335re-diverted. 2336.It Ar divert-reply 2337It has no meaning in 2338.Fx pf . 2339.It Ar probability Aq Ar number 2340A probability attribute can be attached to a rule, with a value set between 23410 and 1, bounds not included. 2342In that case, the rule will be honoured using the given probability value 2343only. 2344For example, the following rule will drop 20% of incoming ICMP packets: 2345.Bd -literal -offset indent 2346block in proto icmp probability 20% 2347.Ed 2348.It Ar prio Aq Ar number 2349Only match packets which have the given queueing priority assigned. 2350.El 2351.Sh ROUTING 2352If a packet matches a rule with a route option set, the packet filter will 2353route the packet according to the type of route option. 2354When such a rule creates state, the route option is also applied to all 2355packets matching the same connection. 2356.Bl -tag -width xxxx 2357.It Ar route-to 2358The 2359.Ar route-to 2360option routes the packet to the specified interface with an optional address 2361for the next hop. 2362When a 2363.Ar route-to 2364rule creates state, only packets that pass in the same direction as the 2365filter rule specifies will be routed in this way. 2366Packets passing in the opposite direction (replies) are not affected 2367and are routed normally. 2368.It Ar reply-to 2369The 2370.Ar reply-to 2371option is similar to 2372.Ar route-to , 2373but routes packets that pass in the opposite direction (replies) to the 2374specified interface. 2375Opposite direction is only defined in the context of a state entry, and 2376.Ar reply-to 2377is useful only in rules that create state. 2378It can be used on systems with multiple external connections to 2379route all outgoing packets of a connection through the interface 2380the incoming connection arrived through (symmetric routing enforcement). 2381.It Ar dup-to 2382The 2383.Ar dup-to 2384option creates a duplicate of the packet and routes it like 2385.Ar route-to . 2386The original packet gets routed as it normally would. 2387.El 2388.Sh POOL OPTIONS 2389For 2390.Ar nat 2391and 2392.Ar rdr 2393rules, (as well as for the 2394.Ar route-to , 2395.Ar reply-to 2396and 2397.Ar dup-to 2398rule options) for which there is a single redirection address which has a 2399subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP 2400address), a variety of different methods for assigning this address can be 2401used: 2402.Bl -tag -width xxxx 2403.It Ar bitmask 2404The 2405.Ar bitmask 2406option applies the network portion of the redirection address to the address 2407to be modified (source with 2408.Ar nat , 2409destination with 2410.Ar rdr ) . 2411.It Ar random 2412The 2413.Ar random 2414option selects an address at random within the defined block of addresses. 2415.It Ar source-hash 2416The 2417.Ar source-hash 2418option uses a hash of the source address to determine the redirection address, 2419ensuring that the redirection address is always the same for a given source. 2420An optional key can be specified after this keyword either in hex or as a 2421string; by default 2422.Xr pfctl 8 2423randomly generates a key for source-hash every time the 2424ruleset is reloaded. 2425.It Ar round-robin 2426The 2427.Ar round-robin 2428option loops through the redirection address(es). 2429.Pp 2430When more than one redirection address is specified, 2431.Ar bitmask 2432is not permitted as a pool type. 2433.It Ar static-port 2434With 2435.Ar nat 2436rules, the 2437.Ar static-port 2438option prevents 2439.Xr pf 4 2440from modifying the source port on TCP and UDP packets. 2441.It Xo Ar map-e-portset Aq Ar psid-offset 2442.No / Aq Ar psid-len 2443.No / Aq Ar psid 2444.Xc 2445With 2446.Ar nat 2447rules, the 2448.Ar map-e-portset 2449option enables the source port translation of MAP-E (RFC 7597) Customer Edge. 2450In order to make the host act as a MAP-E Customer Edge, setting up a tunneling 2451interface and pass rules for encapsulated packets are required in addition 2452to the map-e-portset nat rule. 2453.Pp 2454For example: 2455.Bd -literal -offset indent 2456nat on $gif_mape_if from $int_if:network to any \e 2457 -> $ipv4_mape_src map-e-portset 6/8/0x34 2458.Ed 2459.Pp 2460sets PSID offset 6, PSID length 8, PSID 0x34. 2461.It Ar endpoint-independent 2462With 2463.Ar nat 2464rules, the 2465.Ar endpoint-independent 2466option caues 2467.Xr pf 4 2468to always map connections from a UDP source address and port to the same 2469NAT address and port. 2470This feature implements "full-cone" NAT behavior. 2471.El 2472.Pp 2473Additionally, the 2474.Ar sticky-address 2475option can be specified to help ensure that multiple connections from the 2476same source are mapped to the same redirection address. 2477This option can be used with the 2478.Ar random 2479and 2480.Ar round-robin 2481pool options. 2482Note that by default these associations are destroyed as soon as there are 2483no longer states which refer to them; in order to make the mappings last 2484beyond the lifetime of the states, increase the global options with 2485.Ar set timeout src.track . 2486See 2487.Sx STATEFUL TRACKING OPTIONS 2488for more ways to control the source tracking. 2489.Sh STATE MODULATION 2490Much of the security derived from TCP is attributable to how well the 2491initial sequence numbers (ISNs) are chosen. 2492Some popular stack implementations choose 2493.Em very 2494poor ISNs and thus are normally susceptible to ISN prediction exploits. 2495By applying a 2496.Ar modulate state 2497rule to a TCP connection, 2498.Xr pf 4 2499will create a high quality random sequence number for each connection 2500endpoint. 2501.Pp 2502The 2503.Ar modulate state 2504directive implicitly keeps state on the rule and is 2505only applicable to TCP connections. 2506.Pp 2507For instance: 2508.Bd -literal -offset indent 2509block all 2510pass out proto tcp from any to any modulate state 2511pass in proto tcp from any to any port 25 flags S/SFRA modulate state 2512.Ed 2513.Pp 2514Note that modulated connections will not recover when the state table 2515is lost (firewall reboot, flushing the state table, etc...). 2516.Xr pf 4 2517will not be able to infer a connection again after the state table flushes 2518the connection's modulator. 2519When the state is lost, the connection may be left dangling until the 2520respective endpoints time out the connection. 2521It is possible on a fast local network for the endpoints to start an ACK 2522storm while trying to resynchronize after the loss of the modulator. 2523The default 2524.Ar flags 2525settings (or a more strict equivalent) should be used on 2526.Ar modulate state 2527rules to prevent ACK storms. 2528.Pp 2529Note that alternative methods are available 2530to prevent loss of the state table 2531and allow for firewall failover. 2532See 2533.Xr carp 4 2534and 2535.Xr pfsync 4 2536for further information. 2537.Sh SYN PROXY 2538By default, 2539.Xr pf 4 2540passes packets that are part of a 2541.Xr tcp 4 2542handshake between the endpoints. 2543The 2544.Ar synproxy state 2545option can be used to cause 2546.Xr pf 4 2547itself to complete the handshake with the active endpoint, perform a handshake 2548with the passive endpoint, and then forward packets between the endpoints. 2549.Pp 2550No packets are sent to the passive endpoint before the active endpoint has 2551completed the handshake, hence so-called SYN floods with spoofed source 2552addresses will not reach the passive endpoint, as the sender can't complete the 2553handshake. 2554.Pp 2555The proxy is transparent to both endpoints, they each see a single 2556connection from/to the other endpoint. 2557.Xr pf 4 2558chooses random initial sequence numbers for both handshakes. 2559Once the handshakes are completed, the sequence number modulators 2560(see previous section) are used to translate further packets of the 2561connection. 2562.Ar synproxy state 2563includes 2564.Ar modulate state . 2565.Pp 2566Rules with 2567.Ar synproxy 2568will not work if 2569.Xr pf 4 2570operates on a 2571.Xr bridge 4 . 2572Also they act on incoming SYN packets only. 2573.Pp 2574Example: 2575.Bd -literal -offset indent 2576pass in proto tcp from any to any port www synproxy state 2577.Ed 2578.Sh STATEFUL TRACKING OPTIONS 2579A number of options related to stateful tracking can be applied on a 2580per-rule basis. 2581.Ar keep state , 2582.Ar modulate state 2583and 2584.Ar synproxy state 2585support these options, and 2586.Ar keep state 2587must be specified explicitly to apply options to a rule. 2588.Pp 2589.Bl -tag -width xxxx -compact 2590.It Ar max Aq Ar number 2591Limits the number of concurrent states the rule may create. 2592When this limit is reached, further packets that would create 2593state are dropped until existing states time out. 2594.It Ar no-sync 2595Prevent state changes for states created by this rule from appearing on the 2596.Xr pfsync 4 2597interface. 2598.It Xo Aq Ar timeout 2599.Aq Ar seconds 2600.Xc 2601Changes the timeout values used for states created by this rule. 2602For a list of all valid timeout names, see 2603.Sx OPTIONS 2604above. 2605.It Ar sloppy 2606Uses a sloppy TCP connection tracker that does not check sequence 2607numbers at all, which makes insertion and ICMP teardown attacks way 2608easier. 2609This is intended to be used in situations where one does not see all 2610packets of a connection, e.g. in asymmetric routing situations. 2611Cannot be used with modulate or synproxy state. 2612.It Ar pflow 2613States created by this rule are exported on the 2614.Xr pflow 4 2615interface. 2616.It Ar allow-related 2617Automatically allow connections related to this one, regardless of rules that 2618might otherwise affect them. 2619This currently only applies to SCTP multihomed connection. 2620.El 2621.Pp 2622Multiple options can be specified, separated by commas: 2623.Bd -literal -offset indent 2624pass in proto tcp from any to any \e 2625 port www keep state \e 2626 (max 100, source-track rule, max-src-nodes 75, \e 2627 max-src-states 3, tcp.established 60, tcp.closing 5) 2628.Ed 2629.Pp 2630When the 2631.Ar source-track 2632keyword is specified, the number of states per source IP is tracked. 2633.Pp 2634.Bl -tag -width xxxx -compact 2635.It Ar source-track rule 2636The maximum number of states created by this rule is limited by the rule's 2637.Ar max-src-nodes 2638and 2639.Ar max-src-states 2640options. 2641Only state entries created by this particular rule count toward the rule's 2642limits. 2643.It Ar source-track global 2644The number of states created by all rules that use this option is limited. 2645Each rule can specify different 2646.Ar max-src-nodes 2647and 2648.Ar max-src-states 2649options, however state entries created by any participating rule count towards 2650each individual rule's limits. 2651.El 2652.Pp 2653The following limits can be set: 2654.Pp 2655.Bl -tag -width xxxx -compact 2656.It Ar max-src-nodes Aq Ar number 2657Limits the maximum number of source addresses which can simultaneously 2658have state table entries. 2659.It Ar max-src-states Aq Ar number 2660Limits the maximum number of simultaneous state entries that a single 2661source address can create with this rule. 2662.El 2663.Pp 2664For stateful TCP connections, limits on established connections (connections 2665which have completed the TCP 3-way handshake) can also be enforced 2666per source IP. 2667.Pp 2668.Bl -tag -width xxxx -compact 2669.It Ar max-src-conn Aq Ar number 2670Limits the maximum number of simultaneous TCP connections which have 2671completed the 3-way handshake that a single host can make. 2672.It Xo Ar max-src-conn-rate Aq Ar number 2673.No / Aq Ar seconds 2674.Xc 2675Limit the rate of new connections over a time interval. 2676The connection rate is an approximation calculated as a moving average. 2677.El 2678.Pp 2679When one of these limits is reached, further packets that would create 2680state are dropped until existing states time out. 2681.Pp 2682Because the 3-way handshake ensures that the source address is not being 2683spoofed, more aggressive action can be taken based on these limits. 2684With the 2685.Ar overload Aq Ar table 2686state option, source IP addresses which hit either of the limits on 2687established connections will be added to the named table. 2688This table can be used in the ruleset to block further activity from 2689the offending host, redirect it to a tarpit process, or restrict its 2690bandwidth. 2691.Pp 2692The optional 2693.Ar flush 2694keyword kills all states created by the matching rule which originate 2695from the host which exceeds these limits. 2696The 2697.Ar global 2698modifier to the flush command kills all states originating from the 2699offending host, regardless of which rule created the state. 2700.Pp 2701For example, the following rules will protect the webserver against 2702hosts making more than 100 connections in 10 seconds. 2703Any host which connects faster than this rate will have its address added 2704to the 2705.Aq bad_hosts 2706table and have all states originating from it flushed. 2707Any new packets arriving from this host will be dropped unconditionally 2708by the block rule. 2709.Bd -literal -offset indent 2710block quick from <bad_hosts> 2711pass in on $ext_if proto tcp to $webserver port www keep state \e 2712 (max-src-conn-rate 100/10, overload <bad_hosts> flush global) 2713.Ed 2714.Sh OPERATING SYSTEM FINGERPRINTING 2715Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP 2716connection's initial SYN packet and guess at the host's operating system. 2717Unfortunately these nuances are easily spoofed by an attacker so the 2718fingerprint is not useful in making security decisions. 2719But the fingerprint is typically accurate enough to make policy decisions 2720upon. 2721.Pp 2722The fingerprints may be specified by operating system class, by 2723version, or by subtype/patchlevel. 2724The class of an operating system is typically the vendor or genre 2725and would be 2726.Ox 2727for the 2728.Xr pf 4 2729firewall itself. 2730The version of the oldest available 2731.Ox 2732release on the main FTP site 2733would be 2.6 and the fingerprint would be written 2734.Pp 2735.Dl \&"OpenBSD 2.6\&" 2736.Pp 2737The subtype of an operating system is typically used to describe the 2738patchlevel if that patch led to changes in the TCP stack behavior. 2739In the case of 2740.Ox , 2741the only subtype is for a fingerprint that was 2742normalized by the 2743.Ar no-df 2744scrub option and would be specified as 2745.Pp 2746.Dl \&"OpenBSD 3.3 no-df\&" 2747.Pp 2748Fingerprints for most popular operating systems are provided by 2749.Xr pf.os 5 . 2750Once 2751.Xr pf 4 2752is running, a complete list of known operating system fingerprints may 2753be listed by running: 2754.Pp 2755.Dl # pfctl -so 2756.Pp 2757Filter rules can enforce policy at any level of operating system specification 2758assuming a fingerprint is present. 2759Policy could limit traffic to approved operating systems or even ban traffic 2760from hosts that aren't at the latest service pack. 2761.Pp 2762The 2763.Ar unknown 2764class can also be used as the fingerprint which will match packets for 2765which no operating system fingerprint is known. 2766.Pp 2767Examples: 2768.Bd -literal -offset indent 2769pass out proto tcp from any os OpenBSD 2770block out proto tcp from any os Doors 2771block out proto tcp from any os "Doors PT" 2772block out proto tcp from any os "Doors PT SP3" 2773block out from any os "unknown" 2774pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" 2775.Ed 2776.Pp 2777Operating system fingerprinting is limited only to the TCP SYN packet. 2778This means that it will not work on other protocols and will not match 2779a currently established connection. 2780.Pp 2781Caveat: operating system fingerprints are occasionally wrong. 2782There are three problems: an attacker can trivially craft packets to 2783appear as any operating system; 2784an operating system patch could change the stack behavior and no fingerprints 2785will match it until the database is updated; 2786and multiple operating systems may have the same fingerprint. 2787.Sh BLOCKING SPOOFED TRAFFIC 2788"Spoofing" is the faking of IP addresses, typically for malicious 2789purposes. 2790The 2791.Ar antispoof 2792directive expands to a set of filter rules which will block all 2793traffic with a source IP from the network(s) directly connected 2794to the specified interface(s) from entering the system through 2795any other interface. 2796.Pp 2797For example, the line 2798.Bd -literal -offset indent 2799antispoof for lo0 2800.Ed 2801.Pp 2802expands to 2803.Bd -literal -offset indent 2804block drop in on ! lo0 inet from 127.0.0.1/8 to any 2805block drop in on ! lo0 inet6 from ::1 to any 2806.Ed 2807.Pp 2808For non-loopback interfaces, there are additional rules to block incoming 2809packets with a source IP address identical to the interface's IP(s). 2810For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a 2811netmask of 255.255.255.0, 2812the line 2813.Bd -literal -offset indent 2814antispoof for wi0 inet 2815.Ed 2816.Pp 2817expands to 2818.Bd -literal -offset indent 2819block drop in on ! wi0 inet from 10.0.0.0/24 to any 2820block drop in inet from 10.0.0.1 to any 2821.Ed 2822.Pp 2823Caveat: Rules created by the 2824.Ar antispoof 2825directive interfere with packets sent over loopback interfaces 2826to local addresses. 2827One should pass these explicitly. 2828.Sh FRAGMENT HANDLING 2829The size of IP datagrams (packets) can be significantly larger than the 2830maximum transmission unit (MTU) of the network. 2831In cases when it is necessary or more efficient to send such large packets, 2832the large packet will be fragmented into many smaller packets that will each 2833fit onto the wire. 2834Unfortunately for a firewalling device, only the first logical fragment will 2835contain the necessary header information for the subprotocol that allows 2836.Xr pf 4 2837to filter on things such as TCP ports or to perform NAT. 2838.Pp 2839Besides the use of 2840.Ar set reassemble 2841option or 2842.Ar scrub 2843rules as described in 2844.Sx TRAFFIC NORMALIZATION 2845above, there are three options for handling fragments in the packet filter. 2846.Pp 2847One alternative is to filter individual fragments with filter rules. 2848If no 2849.Ar scrub 2850rule applies to a fragment or 2851.Ar set reassemble 2852is set to 2853.Cm no 2854, it is passed to the filter. 2855Filter rules with matching IP header parameters decide whether the 2856fragment is passed or blocked, in the same way as complete packets 2857are filtered. 2858Without reassembly, fragments can only be filtered based on IP header 2859fields (source/destination address, protocol), since subprotocol header 2860fields are not available (TCP/UDP port numbers, ICMP code/type). 2861The 2862.Ar fragment 2863option can be used to restrict filter rules to apply only to 2864fragments, but not complete packets. 2865Filter rules without the 2866.Ar fragment 2867option still apply to fragments, if they only specify IP header fields. 2868For instance, the rule 2869.Bd -literal -offset indent 2870pass in proto tcp from any to any port 80 2871.Ed 2872.Pp 2873never applies to a fragment, even if the fragment is part of a TCP 2874packet with destination port 80, because without reassembly this information 2875is not available for each fragment. 2876This also means that fragments cannot create new or match existing 2877state table entries, which makes stateful filtering and address 2878translation (NAT, redirection) for fragments impossible. 2879.Pp 2880It's also possible to reassemble only certain fragments by specifying 2881source or destination addresses or protocols as parameters in 2882.Ar scrub 2883rules. 2884.Pp 2885In most cases, the benefits of reassembly outweigh the additional 2886memory cost, and it's recommended to use 2887.Ar set reassemble 2888option or 2889.Ar scrub 2890rules with the 2891.Ar fragment reassemble 2892modifier to reassemble 2893all fragments. 2894.Pp 2895The memory allocated for fragment caching can be limited using 2896.Xr pfctl 8 . 2897Once this limit is reached, fragments that would have to be cached 2898are dropped until other entries time out. 2899The timeout value can also be adjusted. 2900.Pp 2901When forwarding reassembled IPv6 packets, pf refragments them with 2902the original maximum fragment size. 2903This allows the sender to determine the optimal fragment size by 2904path MTU discovery. 2905.Sh ANCHORS 2906Besides the main ruleset, 2907.Xr pfctl 8 2908can load rulesets into 2909.Ar anchor 2910attachment points. 2911An 2912.Ar anchor 2913is a container that can hold rules, address tables, and other anchors. 2914.Pp 2915An 2916.Ar anchor 2917has a name which specifies the path where 2918.Xr pfctl 8 2919can be used to access the anchor to perform operations on it, such as 2920attaching child anchors to it or loading rules into it. 2921Anchors may be nested, with components separated by 2922.Sq / 2923characters, similar to how file system hierarchies are laid out. 2924The main ruleset is actually the default anchor, so filter and 2925translation rules, for example, may also be contained in any anchor. 2926.Pp 2927An anchor can reference another 2928.Ar anchor 2929attachment point 2930using the following kinds 2931of rules: 2932.Bl -tag -width xxxx 2933.It Ar nat-anchor Aq Ar name 2934Evaluates the 2935.Ar nat 2936rules in the specified 2937.Ar anchor . 2938.It Ar rdr-anchor Aq Ar name 2939Evaluates the 2940.Ar rdr 2941rules in the specified 2942.Ar anchor . 2943.It Ar binat-anchor Aq Ar name 2944Evaluates the 2945.Ar binat 2946rules in the specified 2947.Ar anchor . 2948.It Ar anchor Aq Ar name 2949Evaluates the filter rules in the specified 2950.Ar anchor . 2951.It Xo Ar load anchor 2952.Aq Ar name 2953.Ar from Aq Ar file 2954.Xc 2955Loads the rules from the specified file into the 2956anchor 2957.Ar name . 2958.El 2959.Pp 2960When evaluation of the main ruleset reaches an 2961.Ar anchor 2962rule, 2963.Xr pf 4 2964will proceed to evaluate all rules specified in that anchor. 2965.Pp 2966Matching filter and translation rules marked with the 2967.Ar quick 2968option are final and abort the evaluation of the rules in other 2969anchors and the main ruleset. 2970If the 2971.Ar anchor 2972itself is marked with the 2973.Ar quick 2974option, 2975ruleset evaluation will terminate when the anchor is exited if the packet is 2976matched by any rule within the anchor. 2977.Pp 2978.Ar anchor 2979rules are evaluated relative to the anchor in which they are contained. 2980For example, all 2981.Ar anchor 2982rules specified in the main ruleset will reference anchor 2983attachment points underneath the main ruleset, and 2984.Ar anchor 2985rules specified in a file loaded from a 2986.Ar load anchor 2987rule will be attached under that anchor point. 2988.Pp 2989Rules may be contained in 2990.Ar anchor 2991attachment points which do not contain any rules when the main ruleset 2992is loaded, and later such anchors can be manipulated through 2993.Xr pfctl 8 2994without reloading the main ruleset or other anchors. 2995For example, 2996.Bd -literal -offset indent 2997ext_if = \&"kue0\&" 2998block on $ext_if all 2999anchor spam 3000pass out on $ext_if all 3001pass in on $ext_if proto tcp from any \e 3002 to $ext_if port smtp 3003.Ed 3004.Pp 3005blocks all packets on the external interface by default, then evaluates 3006all rules in the 3007.Ar anchor 3008named "spam", and finally passes all outgoing connections and 3009incoming connections to port 25. 3010.Bd -literal -offset indent 3011# echo \&"block in quick from 1.2.3.4 to any\&" \&| \e 3012 pfctl -a spam -f - 3013.Ed 3014.Pp 3015This loads a single rule into the 3016.Ar anchor , 3017which blocks all packets from a specific address. 3018.Pp 3019The anchor can also be populated by adding a 3020.Ar load anchor 3021rule after the 3022.Ar anchor 3023rule: 3024.Bd -literal -offset indent 3025anchor spam 3026load anchor spam from "/etc/pf-spam.conf" 3027.Ed 3028.Pp 3029When 3030.Xr pfctl 8 3031loads 3032.Nm pf.conf , 3033it will also load all the rules from the file 3034.Pa /etc/pf-spam.conf 3035into the anchor. 3036.Pp 3037Optionally, 3038.Ar anchor 3039rules can specify packet filtering parameters using the same syntax as 3040filter rules. 3041When parameters are used, the 3042.Ar anchor 3043rule is only evaluated for matching packets. 3044This allows conditional evaluation of anchors, like: 3045.Bd -literal -offset indent 3046block on $ext_if all 3047anchor spam proto tcp from any to any port smtp 3048pass out on $ext_if all 3049pass in on $ext_if proto tcp from any to $ext_if port smtp 3050.Ed 3051.Pp 3052The rules inside 3053.Ar anchor 3054spam are only evaluated for 3055.Ar tcp 3056packets with destination port 25. 3057Hence, 3058.Bd -literal -offset indent 3059# echo \&"block in quick from 1.2.3.4 to any" \&| \e 3060 pfctl -a spam -f - 3061.Ed 3062.Pp 3063will only block connections from 1.2.3.4 to port 25. 3064.Pp 3065Anchors may end with the asterisk 3066.Pq Sq * 3067character, which signifies that all anchors attached at that point 3068should be evaluated in the alphabetical ordering of their anchor name. 3069For example, 3070.Bd -literal -offset indent 3071anchor "spam/*" 3072.Ed 3073.Pp 3074will evaluate each rule in each anchor attached to the 3075.Li spam 3076anchor. 3077Note that it will only evaluate anchors that are directly attached to the 3078.Li spam 3079anchor, and will not descend to evaluate anchors recursively. 3080.Pp 3081Since anchors are evaluated relative to the anchor in which they are 3082contained, there is a mechanism for accessing the parent and ancestor 3083anchors of a given anchor. 3084Similar to file system path name resolution, if the sequence 3085.Dq .. 3086appears as an anchor path component, the parent anchor of the current 3087anchor in the path evaluation at that point will become the new current 3088anchor. 3089As an example, consider the following: 3090.Bd -literal -offset indent 3091# echo ' anchor "spam/allowed" ' | pfctl -f - 3092# echo -e ' anchor "../banned" \en pass' | \e 3093 pfctl -a spam/allowed -f - 3094.Ed 3095.Pp 3096Evaluation of the main ruleset will lead into the 3097.Li spam/allowed 3098anchor, which will evaluate the rules in the 3099.Li spam/banned 3100anchor, if any, before finally evaluating the 3101.Ar pass 3102rule. 3103.Pp 3104An 3105.Ar anchor 3106rule can also contain a filter ruleset in a brace-delimited block. 3107In that case, no separate loading of rules into the anchor 3108is required. 3109Brace delimited blocks may contain rules or other brace-delimited blocks. 3110When an anchor is populated this way, the anchor name becomes optional. 3111.Bd -literal -offset indent 3112anchor "external" on $ext_if { 3113 block 3114 anchor out { 3115 pass proto tcp from any to port { 25, 80, 443 } 3116 } 3117 pass in proto tcp to any port 22 3118} 3119.Ed 3120.Pp 3121Since the parser specification for anchor names is a string, any 3122reference to an anchor name containing 3123.Sq / 3124characters will require double quote 3125.Pq Sq \&" 3126characters around the anchor name. 3127.Sh SCTP CONSIDERATIONS 3128.Xr pf 4 3129supports 3130.Xr sctp 4 3131connections. 3132It can match ports, track state and NAT SCTP traffic. 3133However, it will not alter port numbers during nat or rdr translations. 3134Doing so would break SCTP multihoming. 3135.Sh TRANSLATION EXAMPLES 3136This example maps incoming requests on port 80 to port 8080, on 3137which a daemon is running (because, for example, it is not run as root, 3138and therefore lacks permission to bind to port 80). 3139.Bd -literal -offset indent 3140# use a macro for the interface name, so it can be changed easily 3141ext_if = \&"ne3\&" 3142 3143# map daemon on 8080 to appear to be on 80 3144match in on $ext_if proto tcp from any to any port 80 \e 3145 rdr-to 127.0.0.1 port 8080 3146.Ed 3147.Pp 3148If a 3149.Ar pass 3150rule is used with the 3151.Ar quick 3152modifier, packets matching the translation rule are passed without 3153inspecting subsequent filter rules: 3154.Bd -literal -offset indent 3155pass in quick on $ext_if proto tcp from any to any port 80 \e 3156 rdr-to 127.0.0.1 port 8080 3157.Ed 3158.Pp 3159In the example below, vlan12 is configured as 192.168.168.1; 3160the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 3161when they are going out any interface except vlan12. 3162This has the net effect of making traffic from the 192.168.168.0/24 3163network appear as though it is the Internet routable address 3164204.92.77.111 to nodes behind any interface on the router except 3165for the nodes on vlan12. 3166(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.) 3167.Bd -literal -offset indent 3168match out on ! vlan12 from 192.168.168.0/24 to any nat-to 204.92.77.111 3169.Ed 3170.Pp 3171This longer example uses both a NAT and a redirection. 3172The external interface has the address 157.161.48.183. 3173On localhost, we are running 3174.Xr ftp-proxy 8 , 3175waiting for FTP sessions to be redirected to it. 3176The three mandatory anchors for 3177.Xr ftp-proxy 8 3178are omitted from this example; see the 3179.Xr ftp-proxy 8 3180manpage. 3181.Bd -literal -offset indent 3182# NAT 3183# Translate outgoing packets' source addresses (any protocol). 3184# In this case, any address but the gateway's external address is mapped. 3185pass out on $ext_if inet from ! ($ext_if) to any nat-to ($ext_if) 3186 3187# NAT PROXYING 3188# Map outgoing packets' source port to an assigned proxy port instead of 3189# an arbitrary port. 3190# In this case, proxy outgoing isakmp with port 500 on the gateway. 3191pass out on $ext_if inet proto udp from any port = isakmp to any \e 3192 nat-to ($ext_if) port 500 3193 3194# BINAT 3195# Translate outgoing packets' source address (any protocol). 3196# Translate incoming packets' destination address to an internal machine 3197# (bidirectional). 3198pass on $ext_if from 10.1.2.150 to any binat-to $ext_if 3199 3200# Translate packets arriving on $peer_if addressed to 172.22.16.0/20 3201# to the corresponding address in 172.21.16.0/20 (bidirectional). 3202pass on $peer_if from 172.21.16.0/20 to any binat-to 172.22.16.0/20 3203 3204# RDR 3205# Translate incoming packets' destination addresses. 3206# As an example, redirect a TCP and UDP port to an internal machine. 3207pass in on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e 3208 rdr-to 10.1.2.151 port 22 3209pass in on $ext_if inet proto udp from any to ($ext_if) port 8080 \e 3210 rdr-to 10.1.2.151 port 53 3211 3212# RDR 3213# Translate outgoing ftp control connections to send them to localhost 3214# for proxying with ftp-proxy(8) running on port 8021. 3215pass in on $int_if proto tcp from any to any port 21 \e 3216 rdr-to 127.0.0.1 port 8021 3217.Ed 3218.Pp 3219In this example, a NAT gateway is set up to translate internal addresses 3220using a pool of public addresses (192.0.2.16/28) and to redirect 3221incoming web server connections to a group of web servers on the internal 3222network. 3223.Bd -literal -offset indent 3224# NAT LOAD BALANCE 3225# Translate outgoing packets' source addresses using an address pool. 3226# A given source address is always translated to the same pool address by 3227# using the source-hash keyword. 3228pass out on $ext_if inet from any to any nat-to 192.0.2.16/28 source-hash 3229 3230# RDR ROUND ROBIN 3231# Translate incoming web server connections to a group of web servers on 3232# the internal network. 3233pass in on $ext_if proto tcp from any to any port 80 \e 3234 rdr-to { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin 3235.Ed 3236.Sh COMPATIBILITY TRANSLATION EXAMPLES 3237In the example below, the machine sits between a fake internal 144.19.74.* 3238network, and a routable external IP of 204.92.77.100. 3239The 3240.Ar no nat 3241rule excludes protocol AH from being translated. 3242.Bd -literal -offset indent 3243# NAT 3244no nat on $ext_if proto ah from 144.19.74.0/24 to any 3245nat on $ext_if from 144.19.74.0/24 to any -> 204.92.77.100 3246.Ed 3247.Pp 3248In the example below, packets bound for one specific server, as well as those 3249generated by the sysadmins are not proxied; all other connections are. 3250.Bd -literal -offset indent 3251# RDR 3252no rdr on $int_if proto { tcp, udp } from any to $server port 80 3253no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80 3254rdr on $int_if proto { tcp, udp } from any to any port 80 \e 3255 -> 127.0.0.1 port 80 3256.Ed 3257.Sh FILTER EXAMPLES 3258.Bd -literal -offset indent 3259# The external interface is kue0 3260# (157.161.48.183, the only routable address) 3261# and the private network is 10.0.0.0/8, for which we are doing NAT. 3262 3263# Reassemble incoming traffic 3264set reassemble yes 3265 3266# use a macro for the interface name, so it can be changed easily 3267ext_if = \&"kue0\&" 3268 3269# block and log everything by default 3270block return log on $ext_if all 3271 3272# block anything coming from source we have no back routes for 3273block in from no-route to any 3274 3275# block packets whose ingress interface does not match the one in 3276# the route back to their source address 3277block in from urpf-failed to any 3278 3279# block and log outgoing packets that do not have our address as source, 3280# they are either spoofed or something is misconfigured (NAT disabled, 3281# for instance), we want to be nice and do not send out garbage. 3282block out log quick on $ext_if from ! 157.161.48.183 to any 3283 3284# silently drop broadcasts (cable modem noise) 3285block in quick on $ext_if from any to 255.255.255.255 3286 3287# block and log incoming packets from reserved address space and invalid 3288# addresses, they are either spoofed or misconfigured, we cannot reply to 3289# them anyway (hence, no return-rst). 3290block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e 3291 192.168.0.0/16, 255.255.255.255/32 } to any 3292 3293# ICMP 3294 3295# pass out/in certain ICMP queries and keep state (ping) 3296# state matching is done on host addresses and ICMP id (not type/code), 3297# so replies (like 0/0 for 8/0) will match queries 3298# ICMP error messages (which always refer to a TCP/UDP packet) are 3299# handled by the TCP/UDP states 3300pass on $ext_if inet proto icmp all icmp-type 8 code 0 3301 3302# UDP 3303 3304# pass out all UDP connections and keep state 3305pass out on $ext_if proto udp all 3306 3307# pass in certain UDP connections and keep state (DNS) 3308pass in on $ext_if proto udp from any to any port domain 3309 3310# TCP 3311 3312# pass out all TCP connections and modulate state 3313pass out on $ext_if proto tcp all modulate state 3314 3315# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) 3316pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e 3317 auth } 3318 3319# Do not allow Windows 9x SMTP connections since they are typically 3320# a viral worm. Alternately we could limit these OSes to 1 connection each. 3321block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e 3322 to any port smtp 3323 3324# IPv6 3325# pass in/out all IPv6 traffic: note that we have to enable this in two 3326# different ways, on both our physical interface and our tunnel 3327pass quick on gif0 inet6 3328pass quick on $ext_if proto ipv6 3329 3330# Packet Tagging 3331 3332# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is 3333# being done on $ext_if for all outgoing packets. tag packets in on 3334# $int_if and pass those tagged packets out on $ext_if. all other 3335# outgoing packets (i.e., packets from the wireless network) are only 3336# permitted to access port 80. 3337 3338pass in on $int_if from any to any tag INTNET 3339pass in on $wifi_if from any to any 3340 3341block out on $ext_if from any to any 3342pass out quick on $ext_if tagged INTNET 3343pass out on $ext_if proto tcp from any to any port 80 3344 3345# tag incoming packets as they are redirected to spamd(8). use the tag 3346# to pass those packets through the packet filter. 3347 3348rdr on $ext_if inet proto tcp from <spammers> to port smtp \e 3349 tag SPAMD -> 127.0.0.1 port spamd 3350 3351block in on $ext_if 3352pass in on $ext_if inet proto tcp tagged SPAMD 3353.Ed 3354.Pp 3355In the example below, a router handling both address families 3356translates an internal IPv4 subnet to IPv6 using the well-known 335764:ff9b::/96 prefix: 3358.Bd -literal -offset 4n 3359pass in on $v4_if inet af-to inet6 from ($v6_if) to 64:ff9b::/96 3360.Ed 3361.Pp 3362Paired with the example above, the example below can be used on 3363another router handling both address families to translate back 3364to IPv4: 3365.Bd -literal -offset 4n 3366pass in on $v6_if inet6 to 64:ff9b::/96 af-to inet from ($v4_if) 3367.Ed 3368.Sh GRAMMAR 3369Syntax for 3370.Nm 3371in BNF: 3372.Bd -literal 3373line = ( option | ether-rule | pf-rule | nat-rule | binat-rule | 3374 rdr-rule | antispoof-rule | altq-rule | queue-rule | 3375 trans-anchors | anchor-rule | anchor-close | load-anchor | 3376 table-rule | include ) 3377 3378option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | 3379 [ "ruleset-optimization" [ "none" | "basic" | "profile" ]] | 3380 [ "optimization" [ "default" | "normal" | 3381 "high-latency" | "satellite" | 3382 "aggressive" | "conservative" ] ] 3383 [ "limit" ( limit-item | "{" limit-list "}" ) ] | 3384 [ "loginterface" ( interface-name | "none" ) ] | 3385 [ "block-policy" ( "drop" | "return" ) ] | 3386 [ "state-policy" ( "if-bound" | "floating" ) ] 3387 [ "state-defaults" state-opts ] 3388 [ "require-order" ( "yes" | "no" ) ] 3389 [ "fingerprints" filename ] | 3390 [ "skip on" ifspec ] | 3391 [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] 3392 [ "keepcounters" ] ) 3393 3394ether-rule = "ether" etheraction [ ( "in" | "out" ) ] 3395 [ "quick" ] [ "on" ifspec ] [ "bridge-to" interface-name ] 3396 [ etherprotospec ] [ etherhosts ] [ "l3" hosts ] 3397 [ etherfilteropt-list ] 3398 3399pf-rule = action [ ( "in" | "out" ) ] 3400 [ "log" [ "(" logopts ")"] ] [ "quick" ] 3401 [ "on" ifspec ] [ route ] [ af ] [ protospec ] 3402 [ hosts ] [ filteropt-list ] 3403 3404logopts = logopt [ "," logopts ] 3405logopt = "all" | "matches" | "user" | "to" interface-name 3406 3407etherfilteropt-list = etherfilteropt-list etherfilteropt | etherfilteropt 3408etherfilteropt = "tag" string | "tagged" string | "queue" ( string ) | 3409 "ridentifier" number | "label" string 3410 3411filteropt-list = filteropt-list filteropt | filteropt 3412filteropt = user | group | flags | icmp-type | icmp6-type | "tos" tos | 3413 "af-to" af "from" ( redirhost | "{" redirhost-list "}" ) 3414 [ "to" ( redirhost | "{" redirhost-list "}" ) ] | 3415 ( "no" | "keep" | "modulate" | "synproxy" ) "state" 3416 [ "(" state-opts ")" ] | 3417 "fragment" | "no-df" | "min-ttl" number | "set-tos" tos | 3418 "max-mss" number | "random-id" | "reassemble tcp" | 3419 fragmentation | "allow-opts" | 3420 "label" string | "tag" string | [ "!" ] "tagged" string | 3421 "max-pkt-rate" number "/" seconds | 3422 "set prio" ( number | "(" number [ [ "," ] number ] ")" ) | 3423 "max-pkt-size" number | 3424 "queue" ( string | "(" string [ [ "," ] string ] ")" ) | 3425 "rtable" number | "probability" number"%" | "prio" number | 3426 "dnpipe" ( number | "(" number "," number ")" ) | 3427 "dnqueue" ( number | "(" number "," number ")" ) | 3428 "ridentifier" number | 3429 [ ! ] "received-on" ( interface-name | interface-group ) 3430 3431nat-rule = [ "no" ] "nat" [ "pass" [ "log" [ "(" logopts ")" ] ] ] 3432 [ "on" ifspec ] [ af ] 3433 [ protospec ] hosts [ "tag" string ] [ "tagged" string ] 3434 [ "->" ( redirhost | "{" redirhost-list "}" ) 3435 [ portspec ] [ pooltype ] [ "static-port" ] 3436 [ "map-e-portset" number "/" number "/" number ] ] 3437 3438binat-rule = [ "no" ] "binat" [ "pass" [ "log" [ "(" logopts ")" ] ] ] 3439 [ "on" interface-name ] [ af ] 3440 [ "proto" ( proto-name | proto-number ) ] 3441 "from" address [ "/" mask-bits ] "to" ipspec 3442 [ "tag" string ] [ "tagged" string ] 3443 [ "->" address [ "/" mask-bits ] ] 3444 3445rdr-rule = [ "no" ] "rdr" [ "pass" [ "log" [ "(" logopts ")" ] ] ] 3446 [ "on" ifspec ] [ af ] 3447 [ protospec ] hosts [ "tag" string ] [ "tagged" string ] 3448 [ "->" ( redirhost | "{" redirhost-list "}" ) 3449 [ portspec ] [ pooltype ] ] 3450 3451antispoof-rule = "antispoof" [ "log" ] [ "quick" ] 3452 "for" ifspec [ af ] [ "label" string ] 3453 [ "ridentifier" number ] 3454 3455table-rule = "table" "<" string ">" [ tableopts-list ] 3456tableopts-list = tableopts-list tableopts | tableopts 3457tableopts = "persist" | "const" | "counters" | "file" string | 3458 "{" [ tableaddr-list ] "}" 3459tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec 3460tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ] 3461tableaddr = hostname | ifspec | "self" | 3462 ipv4-dotted-quad | ipv6-coloned-hex 3463 3464altq-rule = "altq on" interface-name queueopts-list 3465 "queue" subqueue 3466queue-rule = "queue" string [ "on" interface-name ] queueopts-list 3467 subqueue 3468 3469anchor-rule = "anchor" [ string ] [ ( "in" | "out" ) ] [ "on" ifspec ] 3470 [ af ] [ protospec ] [ hosts ] [ filteropt-list ] [ "{" ] 3471 3472anchor-close = "}" 3473 3474trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string 3475 [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ] 3476 3477load-anchor = "load anchor" string "from" filename 3478 3479queueopts-list = queueopts-list queueopts | queueopts 3480queueopts = [ "bandwidth" bandwidth-spec ] | 3481 [ "qlimit" number ] | [ "tbrsize" number ] | 3482 [ "priority" number ] | [ schedulers ] 3483schedulers = ( cbq-def | priq-def | hfsc-def ) 3484bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" ) 3485 3486etheraction = "pass" | "block" 3487action = "pass" | "match" | "block" [ return ] | [ "no" ] "scrub" 3488return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] | 3489 "return-icmp" [ "(" icmpcode [ [ "," ] icmp6code ] ")" ] | 3490 "return-icmp6" [ "(" icmp6code ")" ] 3491icmpcode = ( icmp-code-name | icmp-code-number ) 3492icmp6code = ( icmp6-code-name | icmp6-code-number ) 3493 3494ifspec = ( [ "!" ] ( interface-name | interface-group ) ) | 3495 "{" interface-list "}" 3496interface-list = [ "!" ] ( interface-name | interface-group ) 3497 [ [ "," ] interface-list ] 3498route = ( "route-to" | "reply-to" | "dup-to" ) 3499 ( routehost | "{" routehost-list "}" ) 3500 [ pooltype ] 3501af = "inet" | "inet6" 3502 3503etherprotospec = "proto" ( proto-number | "{" etherproto-list "}" ) 3504etherproto-list = proto-number [ [ "," ] etherproto-list ] 3505protospec = "proto" ( proto-name | proto-number | 3506 "{" proto-list "}" ) 3507proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] 3508 3509etherhosts = "from" macaddress "to" macaddress 3510macaddress = mac | mac "/" masklen | mac "&" mask 3511 3512hosts = "all" | 3513 "from" ( "any" | "no-route" | "urpf-failed" | "self" | host | 3514 "{" host-list "}" ) [ port ] [ os ] 3515 "to" ( "any" | "no-route" | "self" | host | 3516 "{" host-list "}" ) [ port ] 3517 3518ipspec = "any" | host | "{" host-list "}" 3519host = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" ) 3520redirhost = address [ "/" mask-bits ] 3521routehost = "(" interface-name [ address [ "/" mask-bits ] ] ")" 3522address = ( interface-name | interface-group | 3523 "(" ( interface-name | interface-group ) ")" | 3524 hostname | ipv4-dotted-quad | ipv6-coloned-hex ) 3525host-list = host [ [ "," ] host-list ] 3526redirhost-list = redirhost [ [ "," ] redirhost-list ] 3527routehost-list = routehost [ [ "," ] routehost-list ] 3528 3529port = "port" ( unary-op | binary-op | "{" op-list "}" ) 3530portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ] 3531os = "os" ( os-name | "{" os-list "}" ) 3532user = "user" ( unary-op | binary-op | "{" op-list "}" ) 3533group = "group" ( unary-op | binary-op | "{" op-list "}" ) 3534 3535unary-op = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ] 3536 ( name | number ) 3537binary-op = number ( "<>" | "><" | ":" ) number 3538op-list = ( unary-op | binary-op ) [ [ "," ] op-list ] 3539 3540os-name = operating-system-name 3541os-list = os-name [ [ "," ] os-list ] 3542 3543flags = "flags" ( [ flag-set ] "/" flag-set | "any" ) 3544flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ] 3545 [ "W" ] 3546 3547icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) 3548icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" ) 3549icmp-type-code = ( icmp-type-name | icmp-type-number ) 3550 [ "code" ( icmp-code-name | icmp-code-number ) ] 3551icmp-list = icmp-type-code [ [ "," ] icmp-list ] 3552 3553tos = ( "lowdelay" | "throughput" | "reliability" | 3554 [ "0x" ] number ) 3555 3556state-opts = state-opt [ [ "," ] state-opts ] 3557state-opt = ( "max" number | "no-sync" | timeout | "sloppy" | 3558 "source-track" [ ( "rule" | "global" ) ] | 3559 "max-src-nodes" number | "max-src-states" number | 3560 "max-src-conn" number | 3561 "max-src-conn-rate" number "/" number | 3562 "overload" "<" string ">" [ "flush" ] | 3563 "if-bound" | "floating" | "pflow" ) 3564 3565fragmentation = [ "fragment reassemble" ] 3566 3567timeout-list = timeout [ [ "," ] timeout-list ] 3568timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | 3569 "tcp.closing" | "tcp.finwait" | "tcp.closed" | 3570 "sctp.first" | "sctp.opening" | "sctp.established" | 3571 "sctp.closing" | "sctp.closed" | 3572 "udp.first" | "udp.single" | "udp.multiple" | 3573 "icmp.first" | "icmp.error" | 3574 "other.first" | "other.single" | "other.multiple" | 3575 "frag" | "interval" | "src.track" | 3576 "adaptive.start" | "adaptive.end" ) number 3577 3578limit-list = limit-item [ [ "," ] limit-list ] 3579limit-item = ( "states" | "frags" | "src-nodes" ) number 3580 3581pooltype = ( "bitmask" | "random" | 3582 "source-hash" [ ( hex-key | string-key ) ] | 3583 "round-robin" ) [ sticky-address ] 3584 3585subqueue = string | "{" queue-list "}" 3586queue-list = string [ [ "," ] string ] 3587cbq-def = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ] 3588priq-def = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ] 3589hfsc-def = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ] 3590cbq-opt = ( "default" | "borrow" | "red" | "ecn" | "rio" ) 3591priq-opt = ( "default" | "red" | "ecn" | "rio" ) 3592hfsc-opt = ( "default" | "red" | "ecn" | "rio" | 3593 linkshare-sc | realtime-sc | upperlimit-sc ) 3594linkshare-sc = "linkshare" sc-spec 3595realtime-sc = "realtime" sc-spec 3596upperlimit-sc = "upperlimit" sc-spec 3597sc-spec = ( bandwidth-spec | 3598 "(" bandwidth-spec number bandwidth-spec ")" ) 3599include = "include" filename 3600.Ed 3601.Sh FILES 3602.Bl -tag -width "/etc/protocols" -compact 3603.It Pa /etc/hosts 3604Host name database. 3605.It Pa /etc/pf.conf 3606Default location of the ruleset file. 3607The file has to be created manually as it is not installed with a 3608standard installation. 3609.It Pa /etc/pf.os 3610Default location of OS fingerprints. 3611.It Pa /etc/protocols 3612Protocol name database. 3613.It Pa /etc/services 3614Service name database. 3615.El 3616.Sh SEE ALSO 3617.Xr altq 4 , 3618.Xr carp 4 , 3619.Xr icmp 4 , 3620.Xr icmp6 4 , 3621.Xr ip 4 , 3622.Xr ip6 4 , 3623.Xr pf 4 , 3624.Xr pflow 4 , 3625.Xr pfsync 4 , 3626.Xr sctp 4 , 3627.Xr tcp 4 , 3628.Xr udp 4 , 3629.Xr hosts 5 , 3630.Xr pf.os 5 , 3631.Xr protocols 5 , 3632.Xr services 5 , 3633.Xr ftp-proxy 8 , 3634.Xr pfctl 8 , 3635.Xr pflogd 8 3636.Sh HISTORY 3637The 3638.Nm 3639file format first appeared in 3640.Ox 3.0 . 3641