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