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