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