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