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