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