1.\" $OpenBSD: pf.conf.5,v 1.602 2024/04/15 14:06:52 jmc 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: April 15 2024 $ 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. 1467Alternatively, these values may be adjusted collectively 1468in a manner suitable for a specific environment using 1469.Cm set optimization 1470(see above). 1471.Pp 1472.Bl -tag -width Ds -compact 1473.It Cm tcp.closed Pq 90 seconds by default 1474The state after one endpoint sends an RST. 1475.It Cm tcp.closing Pq 900 seconds by default 1476The state after the first FIN has been sent. 1477.It Cm tcp.established Pq 24 hours by default 1478The fully established state. 1479.It Cm tcp.finwait Pq 45 seconds by default 1480The state after both FINs have been exchanged and the connection is closed. 1481Some hosts (notably web servers on Solaris) send TCP packets even after closing 1482the connection. 1483Increasing 1484.Cm tcp.finwait 1485(and possibly 1486.Cm tcp.closing ) 1487can prevent blocking of such packets. 1488.It Cm tcp.first Pq 120 seconds by default 1489The state after the first packet. 1490.It Cm tcp.opening Pq 30 seconds by default 1491The state after the second packet but before both endpoints have 1492acknowledged the connection. 1493.It Cm tcp.tsdiff Pq 30 seconds by default 1494Maximum allowed time difference between RFC 1323 compliant packet timestamps. 1495.El 1496.Pp 1497ICMP and UDP are handled in a fashion similar to TCP, but with a much more 1498limited set of states: 1499.Pp 1500.Bl -tag -width Ds -compact 1501.It Cm icmp.error Pq 10 seconds by default 1502The state after an ICMP error came back in response to an ICMP packet. 1503.It Cm icmp.first Pq 20 seconds by default 1504The state after the first packet. 1505.It Cm udp.first Pq 60 seconds by default 1506The state after the first packet. 1507.It Cm udp.multiple Pq 60 seconds by default 1508The state if both hosts have sent packets. 1509.It Cm udp.single Pq 30 seconds by default 1510The state if the source host sends more than one packet but the destination 1511host has never sent one back. 1512.El 1513.Pp 1514Other protocols are handled similarly to UDP: 1515.Pp 1516.Bl -tag -width xxxx -compact 1517.It Cm other.first Pq 60 seconds by default 1518.It Cm other.multiple Pq 60 seconds by default 1519.It Cm other.single Pq 30 seconds by default 1520.El 1521.Pp 1522Timeout values can be reduced adaptively as the number of state table 1523entries grows. 1524.Pp 1525.Bl -tag -width Ds -compact 1526.It Cm adaptive.start Pq 60000 states by default 1527When the number of state entries exceeds this value, adaptive scaling 1528begins. 1529All timeout values are scaled linearly with factor 1530(adaptive.end \- number of states) / (adaptive.end \- adaptive.start). 1531.It Cm adaptive.end Pq 120000 states by default 1532When reaching this number of state entries, all timeout values become 1533zero, effectively purging all state entries immediately. 1534This value is used to define the scale factor; it should not actually 1535be reached (set a lower state limit, see below). 1536.El 1537.Pp 1538Adaptive timeouts are enabled by default, with an adaptive.start value 1539equal to 60% of the state limit, and an adaptive.end value equal to 1540120% of the state limit. 1541They can be disabled by setting both adaptive.start and adaptive.end to 0. 1542.Pp 1543The adaptive timeout values can be defined both globally and for each rule. 1544When used on a per-rule basis, the values relate to the number of 1545states created by the rule, otherwise to the total number of 1546states. 1547.Pp 1548For example: 1549.Bd -literal -offset indent 1550set timeout tcp.first 120 1551set timeout tcp.established 86400 1552set timeout { adaptive.start 60000, adaptive.end 120000 } 1553set limit states 100000 1554.Ed 1555.Pp 1556With 90000 state table entries, the timeout values are scaled to 50% 1557(tcp.first 60, tcp.established 43200). 1558.El 1559.Pp 1560.Dq pfctl -F Reset 1561restores default values for the following options: debug, all limit options, 1562loginterface, reassemble, skip, syncookies, all timeouts. 1563.Sh QUEUEING 1564Packets can be assigned to queues for the purpose of bandwidth 1565control. 1566At least one declaration is required to configure queues, and later 1567any packet filtering rule can reference the defined queues by name. 1568When filtering, the last referenced 1569.Ar queue 1570name is where any passed packets will be queued, while for 1571blocked packets it specifies where any resulting ICMP or TCP RST 1572packets should be queued. 1573If the referenced queue does not exist on the outgoing interface, 1574the default queue for that interface is used. 1575Queues attached to an interface build a tree, 1576thus each queue can have further child queues. 1577Only leaf queues, i.e. queues without children, can be used to assign 1578packets to. 1579The root queue must specifically reference an interface, all other queues 1580pick up the interfaces they should be created on from their parent queues. 1581.Pp 1582In the following example, a queue named std is created on the interface em0, 1583with 3 child queues ssh, mail and http: 1584.Bd -literal -offset indent 1585queue std on em0 bandwidth 100M 1586queue ssh parent std bandwidth 10M 1587queue mail parent std bandwidth 10M 1588queue http parent std bandwidth 80M default 1589.Ed 1590.Pp 1591The specified bandwidth is the target bandwidth, every queue can receive 1592more bandwidth as long as the parent still has some available. 1593The maximum bandwidth that should be assigned to a given queue can be limited 1594using the 1595.Cm max 1596keyword. 1597If a limitation isn't imposed on the root queue, borrowing can result in 1598saturating the bandwidth of the outgoing interface. 1599Similarly, a minimum (reserved) bandwidth can be specified: 1600.Pp 1601.Dl queue ssh parent std bandwidth 10M min 5M max 25M 1602.Pp 1603For each of these 3 bandwidth specifications an additional burst bandwidth and 1604time can be specified: 1605.Pp 1606.Dl queue ssh parent std bandwidth 10M burst 90M for 100ms 1607.Pp 1608All 1609.Cm bandwidth 1610values are specified as bits per second or using the suffixes 1611.Cm K , 1612.Cm M , 1613and 1614.Cm G 1615to represent kilobits, megabits, and gigabits per second, respectively. 1616The value must not exceed the interface bandwidth. 1617.Pp 1618If multiple connections are assigned the same queue, they're not guaranteed 1619to share the queue bandwidth fairly. 1620An alternative flow queue manager can be used to achieve fair sharing by 1621indicating how many simultaneous states are expected with a 1622.Cm flows 1623option, unless a minimum bandwidth has been specified as well. 1624.Pp 1625When packets are classified by the stateful inspection engine, a flow 1626identifier is assigned to all packets belonging to the state, 1627thus limiting the number of individual flows that can be recognized 1628by the resolution of a flow identifier. 1629The current implementation is able to classify traffic into 32767 distinct 1630flows. 1631However, efficient fair sharing is observed even with a much smaller number 1632of flows. 1633For example on a 10Mbit/s DSL or a cable modem uplink, the following simple 1634configuration can be used: 1635.Bd -literal -offset 4n 1636queue outq on em0 bandwidth 9M max 9M flows 1024 qlimit 1024 \e 1637 default 1638.Ed 1639.Pp 1640It's important to specify the upper bound within 90-95% of the expected 1641bandwidth and raise the default queue limit. 1642.Pp 1643If a 1644.Cm flows 1645option appears without a 1646.Cm bandwidth 1647specification, the flow queue manager is selected as the queueing discipline 1648for the corresponding interface acting as a default queue for all outgoing 1649packets. 1650In such a scenario, a queueing hierarchy is not supported. 1651.Pp 1652In addition to the bandwidth and flow specifications, queues support the 1653following options: 1654.Bl -tag -width xxxx 1655.It Cm default 1656Packets not matched by another queue are assigned to this queue. 1657Exactly one default queue per interface is required. 1658.It Cm on Ar interface 1659Specifies the interface the queue operates on. 1660If not given, it operates on all matching interfaces. 1661.It Cm parent Ar name 1662Defines which parent queue the queue should be attached to. 1663Mandatory for all queues except root queues. 1664The parent queue must exist. 1665.It Cm quantum Ar size 1666Specifies the quantum of service for the flow queue manager. 1667The lower the quantum size the more advantage is given to streams of smaller 1668packets at the expense of bulk transfers. 1669The default value is set to the configured Maximum Transmission Unit (MTU) 1670of the specified interface. 1671.It Cm qlimit Ar limit 1672The maximum number of packets held in the queue. 1673The default is 50. 1674.El 1675.Pp 1676Packets can be assigned to queues based on filter rules by using the 1677.Cm queue 1678keyword. 1679Normally only one 1680.Ar queue 1681is specified; when a second one is specified it will instead be used for 1682packets which have a TOS of 1683.Cm lowdelay 1684and for TCP ACKs with no data payload. 1685.Pp 1686To continue the previous example, the examples below would specify the 1687four referenced 1688queues, plus a few child queues. 1689Interactive 1690.Xr ssh 1 1691sessions get a queue with a minimum bandwidth; 1692.Xr scp 1 1693and 1694.Xr sftp 1 1695bulk transfers go to a separate queue. 1696The queues are then referenced by filtering rules. 1697.Bd -literal -offset 4n 1698queue rootq on em0 bandwidth 100M max 100M 1699queue http parent rootq bandwidth 60M burst 90M for 100ms 1700queue developers parent http bandwidth 45M 1701queue employees parent http bandwidth 15M 1702queue mail parent rootq bandwidth 10M 1703queue ssh parent rootq bandwidth 20M 1704queue ssh_interactive parent ssh bandwidth 10M min 5M 1705queue ssh_bulk parent ssh bandwidth 10M 1706queue std parent rootq bandwidth 20M default 1707 1708block return out on em0 inet all set queue std 1709pass out on em0 inet proto tcp from $developerhosts to any port 80 \e 1710 set queue developers 1711pass out on em0 inet proto tcp from $employeehosts to any port 80 \e 1712 set queue employees 1713pass out on em0 inet proto tcp from any to any port 22 \e 1714 set queue(ssh_bulk, ssh_interactive) 1715pass out on em0 inet proto tcp from any to any port 25 \e 1716 set queue mail 1717.Ed 1718.Sh TABLES 1719Tables are named structures which can hold a collection of addresses and 1720networks. 1721Lookups against tables in 1722.Xr pf 4 1723are relatively fast, making a single rule with tables much more efficient, 1724in terms of 1725processor usage and memory consumption, than a large number of rules which 1726differ only in IP address (either created explicitly or automatically by rule 1727expansion). 1728.Pp 1729Tables can be used as the source or destination of filter 1730or translation rules. 1731They can also be used for the redirect address of 1732.Cm nat-to 1733and 1734.Cm rdr-to 1735and in the routing options of filter rules, but not for 1736.Cm bitmask 1737pools. 1738.Pp 1739Tables can be defined with any of the following 1740.Xr pfctl 8 1741mechanisms. 1742As with macros, reserved words may not be used as table names. 1743.Bl -tag -width "manually" 1744.It manually 1745Persistent tables can be manually created with the 1746.Cm add 1747or 1748.Cm replace 1749option of 1750.Xr pfctl 8 , 1751before or after the ruleset has been loaded. 1752.It Nm 1753Table definitions can be placed directly in this file and loaded at the 1754same time as other rules are loaded, atomically. 1755Table definitions inside 1756.Nm 1757use the 1758.Ic table 1759statement, and are especially useful to define non-persistent tables. 1760The contents of a pre-existing table defined without a list of addresses 1761to initialize it is not altered when 1762.Nm 1763is loaded. 1764A table initialized with the empty list, 1765.Li { } , 1766will be cleared on load. 1767.El 1768.Pp 1769Tables may be defined with the following attributes: 1770.Bl -tag -width counters 1771.It Cm const 1772The 1773.Cm const 1774flag prevents the user from altering the contents of the table once it 1775has been created. 1776Without that flag, 1777.Xr pfctl 8 1778can be used to add or remove addresses from the table at any time, even 1779when running with 1780.Xr securelevel 7 1781= 2. 1782.It Cm counters 1783The 1784.Cm counters 1785flag enables per-address packet and byte counters, which can be displayed with 1786.Xr pfctl 8 . 1787.It Cm persist 1788The 1789.Cm persist 1790flag forces the kernel to keep the table even when no rules refer to it. 1791If the flag is not set, the kernel will automatically remove the table 1792when the last rule referring to it is flushed. 1793.El 1794.Pp 1795This example creates a table called 1796.Dq private , 1797to hold RFC 1918 private network blocks, 1798and a table called 1799.Dq badhosts , 1800which is initially empty. 1801A filter rule is set up to block all traffic coming from addresses listed in 1802either table: 1803.Bd -literal -offset indent 1804table <private> const { 10/8, 172.16/12, 192.168/16 } 1805table <badhosts> persist 1806block on fxp0 from { <private>, <badhosts> } to any 1807.Ed 1808.Pp 1809The private table cannot have its contents changed and the badhosts table 1810will exist even when no active filter rules reference it. 1811Addresses may later be added to the badhosts table, so that traffic from 1812these hosts can be blocked by using the following: 1813.Pp 1814.Dl # pfctl -t badhosts -Tadd 204.92.77.111 1815.Pp 1816A table can also be initialized with an address list specified in one or more 1817external files, using the following syntax: 1818.Bd -literal -offset indent 1819table <spam> persist file "/etc/spammers" file "/etc/openrelays" 1820block on fxp0 from <spam> to any 1821.Ed 1822.Pp 1823The files 1824.Pa /etc/spammers 1825and 1826.Pa /etc/openrelays 1827list IP addresses, one per line. 1828Any lines beginning with a 1829.Sq # 1830are treated as comments and ignored. 1831In addition to being specified by IP address, hosts may also be 1832specified by their hostname. 1833When the resolver is called to add a hostname to a table, 1834.Em all 1835resulting IPv4 and IPv6 addresses are placed into the table. 1836IP addresses can also be entered in a table by specifying a valid interface 1837name, a valid interface group, or the 1838.Cm self 1839keyword, in which case all addresses assigned to the interface(s) will be 1840added to the table. 1841.Sh ANCHORS 1842Besides the main ruleset, 1843.Nm 1844can specify anchor attachment points. 1845An anchor is a container that can hold rules, 1846address tables, and other anchors. 1847When evaluation of the main ruleset reaches an 1848.Ic anchor 1849rule, 1850.Xr pf 4 1851will proceed to evaluate all rules specified in that anchor. 1852.Pp 1853The following example blocks all packets on the external interface by default, 1854then evaluates all rules in the anchor named "spam", 1855and finally passes all outgoing connections and 1856incoming connections to port 25: 1857.Bd -literal -offset indent 1858ext_if = "kue0" 1859block on $ext_if all 1860anchor spam 1861pass out on $ext_if all 1862pass in on $ext_if proto tcp from any to $ext_if port smtp 1863.Ed 1864.Pp 1865Anchors can be manipulated through 1866.Xr pfctl 8 1867without reloading the main ruleset or other anchors. 1868This loads a single rule into the anchor, 1869which blocks all packets from a specific address: 1870.Bd -literal -offset indent 1871# echo "block in quick from 1.2.3.4 to any" | pfctl -a spam -f - 1872.Ed 1873.Pp 1874The anchor can also be populated by adding a 1875.Ic load anchor 1876rule after the anchor rule. 1877When 1878.Xr pfctl 8 1879loads 1880.Nm , 1881it will also load all the rules from the file 1882.Pa /etc/pf-spam.conf 1883into the anchor. 1884.Bd -literal -offset indent 1885anchor spam 1886load anchor spam from "/etc/pf-spam.conf" 1887.Ed 1888.Pp 1889An anchor rule can also contain a filter ruleset 1890in a brace-delimited block. 1891In that case, no separate loading of rules into the anchor 1892is required. 1893Brace delimited blocks may contain rules or other brace-delimited blocks. 1894When an anchor is populated this way, the anchor name becomes optional. 1895Since the parser specification for anchor names is a string, 1896double quote characters 1897.Pq Sq \&" 1898should be placed around the anchor name. 1899.Bd -literal -offset indent 1900anchor "external" on egress { 1901 block 1902 anchor out { 1903 pass proto tcp from any to port { 25, 80, 443 } 1904 } 1905 pass in proto tcp to any port 22 1906} 1907.Ed 1908.Pp 1909Anchor rules can also specify packet filtering parameters 1910using the same syntax as filter rules. 1911When parameters are used, 1912the anchor rule is only evaluated for matching packets. 1913This allows conditional evaluation of anchors, like: 1914.Bd -literal -offset indent 1915block on $ext_if all 1916anchor spam proto tcp from any to any port smtp 1917pass out on $ext_if all 1918pass in on $ext_if proto tcp from any to $ext_if port smtp 1919.Ed 1920.Pp 1921The rules inside anchor "spam" are only evaluated 1922for TCP packets with destination port 25. 1923Hence, the following 1924will only block connections from 1.2.3.4 to port 25: 1925.Bd -literal -offset indent 1926# echo "block in quick from 1.2.3.4 to any" | pfctl -a spam -f - 1927.Ed 1928.Pp 1929Matching filter and translation rules marked with the 1930.Cm quick 1931option are final and abort the evaluation of the rules in other 1932anchors and the main ruleset. 1933If the anchor itself is marked with the 1934.Cm quick 1935option, 1936ruleset evaluation will terminate when the anchor is exited if the packet is 1937matched by any rule within the anchor. 1938.Pp 1939An anchor references other anchor attachment points 1940using the following syntax: 1941.Bl -tag -width xxxx 1942.It Ic anchor Ar name 1943Evaluates the filter rules in the specified anchor. 1944.El 1945.Pp 1946An anchor has a name which specifies the path where 1947.Xr pfctl 8 1948can be used to access the anchor to perform operations on it, such as 1949attaching child anchors to it or loading rules into it. 1950Anchors may be nested, with components separated by 1951.Sq / 1952characters, similar to how file system hierarchies are laid out. 1953The main ruleset is actually the default anchor, so filter and 1954translation rules, for example, may also be contained in any anchor. 1955.Pp 1956Anchor rules are evaluated relative to the anchor in which they are contained. 1957For example, 1958all anchor rules specified in the main ruleset will reference 1959anchor attachment points underneath the main ruleset, 1960and anchor rules specified in a file loaded from a 1961.Ic load anchor 1962rule will be attached under that anchor point. 1963.Pp 1964Anchors may end with the asterisk 1965.Pq Sq * 1966character, which signifies that all anchors attached at that point 1967should be evaluated in the alphabetical ordering of their anchor name. 1968For example, 1969the following 1970will evaluate each rule in each anchor attached to the "spam" anchor: 1971.Bd -literal -offset indent 1972anchor "spam/*" 1973.Ed 1974.Pp 1975Note that it will only evaluate anchors that are directly attached to the 1976"spam" anchor, and will not descend to evaluate anchors recursively. 1977.Pp 1978Since anchors are evaluated relative to the anchor in which they are 1979contained, there is a mechanism for accessing the parent and ancestor 1980anchors of a given anchor. 1981Similar to file system path name resolution, if the sequence 1982.Sq .. 1983appears as an anchor path component, the parent anchor of the current 1984anchor in the path evaluation at that point will become the new current 1985anchor. 1986As an example, consider the following: 1987.Bd -literal -offset indent 1988# printf 'anchor "spam/allowed"\en' | pfctl -f - 1989# printf 'anchor "../banned"\enpass\en' | pfctl -a spam/allowed -f - 1990.Ed 1991.Pp 1992Evaluation of the main ruleset will lead into the 1993spam/allowed anchor, which will evaluate the rules in the 1994spam/banned anchor, if any, before finally evaluating the 1995.Ic pass 1996rule. 1997.Sh STATEFUL FILTERING 1998.Xr pf 4 1999filters packets statefully, 2000which has several advantages. 2001For TCP connections, comparing a packet to a state involves checking 2002its sequence numbers, as well as TCP timestamps if a rule using the 2003.Cm reassemble tcp 2004parameter applies to the connection. 2005If these values are outside the narrow windows of expected 2006values, the packet is dropped. 2007This prevents spoofing attacks, such as when an attacker sends packets with 2008a fake source address/port but does not know the connection's sequence 2009numbers. 2010Similarly, 2011.Xr pf 4 2012knows how to match ICMP replies to states. 2013For example, 2014to allow echo requests (such as those created by 2015.Xr ping 8 ) 2016out statefully and match incoming echo replies correctly to states: 2017.Pp 2018.Dl pass out inet proto icmp all icmp-type echoreq 2019.Pp 2020Also, looking up states is usually faster than evaluating rules. 2021If there are 50 rules, all of them are evaluated sequentially in O(n). 2022Even with 50000 states, only 16 comparisons are needed to match a 2023state, since states are stored in a binary search tree that allows 2024searches in O(log2\~n). 2025.Pp 2026Furthermore, correct handling of ICMP error messages is critical to 2027many protocols, particularly TCP. 2028.Xr pf 4 2029matches ICMP error messages to the correct connection, checks them against 2030connection parameters, and passes them if appropriate. 2031For example if an ICMP source quench message referring to a stateful TCP 2032connection arrives, it will be matched to the state and get passed. 2033.Pp 2034Finally, state tracking is required for 2035.Cm nat-to 2036and 2037.Cm rdr-to 2038options, in order to track address and port translations and reverse the 2039translation on returning packets. 2040.Pp 2041.Xr pf 4 2042will also create state for other protocols which are effectively stateless by 2043nature. 2044UDP packets are matched to states using only host addresses and ports, 2045and other protocols are matched to states using only the host addresses. 2046.Pp 2047If stateless filtering of individual packets is desired, 2048the 2049.Cm no state 2050keyword can be used to specify that state will not be created 2051if this is the last matching rule. 2052Note that packets which match neither block nor pass rules, 2053and thus are passed by default, 2054are effectively passed as if 2055.Cm no state 2056had been specified. 2057.Pp 2058A number of parameters can also be set to affect how 2059.Xr pf 4 2060handles state tracking, 2061as detailed below. 2062.Ss State Modulation 2063Much of the security derived from TCP is attributable to how well the 2064initial sequence numbers (ISNs) are chosen. 2065Some popular stack implementations choose 2066.Em very 2067poor ISNs and thus are normally susceptible to ISN prediction exploits. 2068By applying a 2069.Cm modulate state 2070rule to a TCP connection, 2071.Xr pf 4 2072will create a high quality random sequence number for each connection 2073endpoint. 2074.Pp 2075The 2076.Cm modulate state 2077directive implicitly keeps state on the rule and is 2078only applicable to TCP connections. 2079.Pp 2080For instance: 2081.Bd -literal -offset indent 2082block all 2083pass out proto tcp from any to any modulate state 2084pass in proto tcp from any to any port 25 flags S/SFRA \e 2085 modulate state 2086.Ed 2087.Pp 2088Note that modulated connections will not recover when the state table 2089is lost (firewall reboot, flushing the state table, etc.). 2090.Xr pf 4 2091will not be able to infer a connection again after the state table flushes 2092the connection's modulator. 2093When the state is lost, the connection may be left dangling until the 2094respective endpoints time out the connection. 2095It is possible on a fast local network for the endpoints to start an ACK 2096storm while trying to resynchronize after the loss of the modulator. 2097The default 2098.Cm flags 2099settings (or a more strict equivalent) should be used on 2100.Cm modulate state 2101rules to prevent ACK storms. 2102.Pp 2103Note that alternative methods are available 2104to prevent loss of the state table 2105and allow for firewall failover. 2106See 2107.Xr carp 4 2108and 2109.Xr pfsync 4 2110for further information. 2111.Ss SYN Proxy 2112By default, 2113.Xr pf 4 2114passes packets that are part of a 2115TCP handshake between the endpoints. 2116The 2117.Cm synproxy state 2118option can be used to cause 2119.Xr pf 4 2120itself to complete the handshake with the active endpoint, perform a handshake 2121with the passive endpoint, and then forward packets between the endpoints. 2122.Pp 2123No packets are sent to the passive endpoint before the active endpoint has 2124completed the handshake, hence so-called SYN floods with spoofed source 2125addresses will not reach the passive endpoint, as the sender can't complete the 2126handshake. 2127.Pp 2128The proxy is transparent to both endpoints; they each see a single 2129connection from/to the other endpoint. 2130.Xr pf 4 2131chooses random initial sequence numbers for both handshakes. 2132Once the handshakes are completed, the sequence number modulators 2133(see previous section) are used to translate further packets of the 2134connection. 2135.Cm synproxy state 2136includes 2137.Cm modulate state . 2138.Pp 2139Rules with 2140.Cm synproxy state 2141will not work if 2142.Xr pf 4 2143operates on a 2144.Xr bridge 4 . 2145Also they act on incoming SYN packets only. 2146.Pp 2147Example: 2148.Bd -literal -offset indent 2149pass in proto tcp from any to any port www synproxy state 2150.Ed 2151.Ss Stateful Tracking Options 2152A number of options related to stateful tracking can be applied on a 2153per-rule basis. 2154One of 2155.Cm keep state , 2156.Cm modulate state , 2157or 2158.Cm synproxy state 2159must be specified explicitly to apply these options to a rule. 2160.Pp 2161.Bl -tag -width xxxx -compact 2162.It Cm floating 2163States can match packets on any interfaces 2164(the opposite of 2165.Cm if-bound ) . 2166This is the default. 2167.It Cm if-bound 2168States are bound to an interface 2169(the opposite of 2170.Cm floating ) . 2171.It Cm max Ar number 2172Limits the number of concurrent states the rule may create. 2173When this limit is reached, further packets that would create 2174state are dropped until existing states time out. 2175.It Cm no-sync 2176Prevent state changes for states created by this rule from appearing on the 2177.Xr pfsync 4 2178interface. 2179.It Cm pflow 2180States created by this rule are exported on the 2181.Xr pflow 4 2182interface. 2183.It Cm sloppy 2184For TCP, uses a sloppy connection tracker that does not check sequence 2185numbers at all, which makes insertion and ICMP teardown attacks way 2186easier. 2187This is intended to be used in situations where one does not see all 2188packets of a connection, e.g. in asymmetric routing situations. 2189It cannot be used with 2190.Cm modulate state 2191or 2192.Cm synproxy state . 2193For ICMP, this option allows states to be created from replies, 2194not just requests. 2195.It Ar timeout seconds 2196Changes the 2197.Ar timeout 2198values used for states created by this rule. 2199For a list of all valid 2200.Ar timeout 2201names, see 2202.Sx OPTIONS 2203above. 2204.El 2205.Pp 2206Multiple options can be specified, separated by commas: 2207.Bd -literal -offset indent 2208pass in proto tcp from any to any \e 2209 port www keep state \e 2210 (max 100, source-track rule, max-src-nodes 75, \e 2211 max-src-states 3, tcp.established 60, tcp.closing 5) 2212.Ed 2213.Pp 2214When the 2215.Cm source-track 2216keyword is specified, the number of states per source IP is tracked. 2217.Pp 2218.Bl -tag -width xxxx -compact 2219.It Cm source-track global 2220The number of states created by all rules that use this option is limited. 2221Each rule can specify different 2222.Cm max-src-nodes 2223and 2224.Cm max-src-states 2225options, however state entries created by any participating rule count towards 2226each individual rule's limits. 2227.It Cm source-track rule 2228The maximum number of states created by this rule is limited by the rule's 2229.Cm max-src-nodes 2230and 2231.Cm max-src-states 2232options. 2233Only state entries created by this particular rule count toward the rule's 2234limits. 2235.El 2236.Pp 2237The following limits can be set: 2238.Pp 2239.Bl -tag -width xxxx -compact 2240.It Cm max-src-nodes Ar number 2241Limits the maximum number of source addresses which can simultaneously 2242have state table entries. 2243.It Cm max-src-states Ar number 2244Limits the maximum number of simultaneous state entries that a single 2245source address can create with this rule. 2246.El 2247.Pp 2248For stateful TCP connections, limits on established connections (connections 2249which have completed the TCP 3-way handshake) can also be enforced 2250per source IP. 2251.Pp 2252.Bl -tag -width xxxx -compact 2253.It Cm max-src-conn Ar number 2254Limits the maximum number of simultaneous TCP connections which have 2255completed the 3-way handshake that a single host can make. 2256.It Cm max-src-conn-rate Ar number Ns / Ns Ar seconds 2257Limit the rate of new connections over a time interval. 2258The connection rate is an approximation calculated as a moving average. 2259.El 2260.Pp 2261When one of these limits is reached, further packets that would create 2262state are dropped until existing states time out. 2263.Pp 2264Because the 3-way handshake ensures that the source address is not being 2265spoofed, more aggressive action can be taken based on these limits. 2266With the 2267.Cm overload Pf < Ar table Ns > 2268state option, source IP addresses which hit either of the limits on 2269established connections will be added to the named 2270.Ar table . 2271This table can be used in the ruleset to block further activity from 2272the offending host, redirect it to a tarpit process, or restrict its 2273bandwidth. 2274.Pp 2275The optional 2276.Cm flush 2277keyword kills all states created by the matching rule which originate 2278from the host which exceeds these limits. 2279The 2280.Cm global 2281modifier to the 2282.Cm flush 2283command kills all states originating from the 2284offending host, regardless of which rule created the state. 2285.Pp 2286For example, the following rules will protect the webserver against 2287hosts making more than 100 connections in 10 seconds. 2288Any host which connects faster than this rate will have its address added 2289to the <bad_hosts> table and have all states originating from it flushed. 2290Any new packets arriving from this host will be dropped unconditionally 2291by the block rule. 2292.Bd -literal -offset indent 2293block quick from <bad_hosts> 2294pass in on $ext_if proto tcp to $webserver port www keep state \e 2295 (max-src-conn-rate 100/10, overload <bad_hosts> flush global) 2296.Ed 2297.Sh TRAFFIC NORMALISATION 2298Traffic normalisation is a broad umbrella term 2299for aspects of the packet filter which deal with 2300verifying packets, packet fragments, spoof traffic, 2301and other irregularities. 2302.Ss Scrub 2303Scrub involves sanitising packet content in such a way 2304that there are no ambiguities in packet interpretation on the receiving side. 2305It is invoked with the 2306.Cm scrub 2307option, added to regular rules. 2308.Pp 2309Parameters are specified enclosed in parentheses. 2310At least one of the following parameters must be specified: 2311.Bl -tag -width xxxx 2312.It Cm max-mss Ar number 2313Reduces the maximum segment size (MSS) 2314on TCP SYN packets to be no greater than 2315.Ar number . 2316This is sometimes required in scenarios where the two endpoints 2317of a TCP connection are not able to carry similar sized packets 2318and the resulting mismatch can lead to packet fragmentation or loss. 2319Note that setting the MSS this way can have undesirable effects, 2320such as interfering with the OS detection features of 2321.Xr pf 4 . 2322.It Cm min-ttl Ar number 2323Enforces a minimum TTL for matching IP packets. 2324.It Cm no-df 2325Clears the 2326.Dq dont-fragment 2327bit from a matching IPv4 packet. 2328Some operating systems have NFS implementations 2329which are known to generate fragmented packets with the 2330.Dq dont-fragment 2331bit set. 2332.Xr pf 4 2333will drop such fragmented 2334.Dq dont-fragment 2335packets unless 2336.Cm no-df 2337is specified. 2338.Pp 2339Unfortunately some operating systems also generate their 2340.Dq dont-fragment 2341packets with a zero IP identification field. 2342Clearing the 2343.Dq dont-fragment 2344bit on packets with a zero IP ID may cause deleterious results if an 2345upstream router later fragments the packet. 2346Using 2347.Cm random-id 2348is recommended in combination with 2349.Cm no-df 2350to ensure unique IP identifiers. 2351.It Cm random-id 2352Replaces the IPv4 identification field with random values to compensate 2353for predictable values generated by many hosts. 2354This option only applies to packets that are not fragmented 2355after the optional fragment reassembly. 2356.It Cm reassemble tcp 2357Statefully normalises TCP connections. 2358.Cm reassemble tcp 2359performs the following normalisations: 2360.Bl -ohang 2361.It TTL 2362Neither side of the connection is allowed to reduce their IP TTL. 2363An attacker may send a packet such that it reaches the firewall, affects 2364the firewall state, and expires before reaching the destination host. 2365.Cm reassemble tcp 2366will raise the TTL of all packets back up to the highest value seen on 2367the connection. 2368.It Timestamp Modulation 2369Modern TCP stacks will send a timestamp on every TCP packet and echo 2370the other endpoint's timestamp back to them. 2371Many operating systems will merely start the timestamp at zero when 2372first booted, and increment it several times a second. 2373The uptime of the host can be deduced by reading the timestamp and multiplying 2374by a constant. 2375Also observing several different timestamps can be used to count hosts 2376behind a NAT device. 2377And spoofing TCP packets into a connection requires knowing or guessing 2378valid timestamps. 2379Timestamps merely need to be monotonically increasing and not derived off a 2380guessable base time. 2381.Cm reassemble tcp 2382will cause 2383.Cm scrub 2384to modulate the TCP timestamps with a random number. 2385.It Extended PAWS Checks 2386There is a problem with TCP on long fat pipes, in that a packet might get 2387delayed for longer than it takes the connection to wrap its 32-bit sequence 2388space. 2389In such an occurrence, the old packet would be indistinguishable from a 2390new packet and would be accepted as such. 2391The solution to this is called PAWS: Protection Against Wrapped Sequence 2392numbers. 2393It protects against it by making sure the timestamp on each packet does 2394not go backwards. 2395.Cm reassemble tcp 2396also makes sure the timestamp on the packet does not go forward more 2397than the RFC allows. 2398By doing this, 2399.Xr pf 4 2400artificially extends the security of TCP sequence numbers by 10 to 18 2401bits when the host uses appropriately randomized timestamps, since a 2402blind attacker would have to guess the timestamp as well. 2403.El 2404.El 2405.Pp 2406For example: 2407.Pp 2408.Dl match in all scrub (no-df random-id max-mss 1440) 2409.Ss Fragment Handling 2410The size of IP datagrams (packets) can be significantly larger than the 2411maximum transmission unit (MTU) of the network. 2412In cases when it is necessary or more efficient to send such large packets, 2413the large packet will be fragmented into many smaller packets that will each 2414fit onto the wire. 2415Unfortunately for a firewalling device, only the first logical fragment will 2416contain the necessary header information for the subprotocol that allows 2417.Xr pf 4 2418to filter on things such as TCP ports or to perform NAT. 2419.Pp 2420One alternative is to filter individual fragments with filter rules. 2421If packet reassembly is turned off, it is passed to the filter. 2422Filter rules with matching IP header parameters decide whether the 2423fragment is passed or blocked, in the same way as complete packets 2424are filtered. 2425Without reassembly, fragments can only be filtered based on IP header 2426fields (source/destination address, protocol), since subprotocol header 2427fields are not available (TCP/UDP port numbers, ICMP code/type). 2428The 2429.Cm fragment 2430option can be used to restrict filter rules to apply only to 2431fragments, but not complete packets. 2432Filter rules without the 2433.Cm fragment 2434option still apply to fragments, if they only specify IP header fields. 2435For instance: 2436.Bd -literal -offset indent 2437pass in proto tcp from any to any port 80 2438.Ed 2439.Pp 2440The rule above never applies to a fragment, 2441even if the fragment is part of a TCP packet with destination port 80, 2442because without reassembly this information 2443is not available for each fragment. 2444This also means that fragments cannot create new or match existing 2445state table entries, which makes stateful filtering and address 2446translation (NAT, redirection) for fragments impossible. 2447.Pp 2448In most cases, the benefits of reassembly outweigh the additional 2449memory cost, 2450so reassembly is on by default. 2451.Pp 2452The memory allocated for fragment caching can be limited using 2453.Xr pfctl 8 . 2454Once this limit is reached, fragments that would have to be cached 2455are dropped until other entries time out. 2456The timeout value can also be adjusted. 2457.Pp 2458When forwarding reassembled IPv6 packets, pf refragments them with 2459the original maximum fragment size. 2460This allows the sender to determine the optimal fragment size by 2461path MTU discovery. 2462.Ss Blocking Spoofed Traffic 2463Spoofing is the faking of IP addresses, 2464typically for malicious purposes. 2465The 2466.Ic antispoof 2467directive expands to a set of filter rules which will block all 2468traffic with a source IP from the network(s) directly connected 2469to the specified interface(s) from entering the system through 2470any other interface. 2471.Pp 2472For example: 2473.Dl antispoof for lo0 2474.Pp 2475Expands to: 2476.Bd -literal -offset indent -compact 2477block drop in on ! lo0 inet from 127.0.0.1/8 to any 2478block drop in on ! lo0 inet6 from ::1 to any 2479.Ed 2480.Pp 2481For non-loopback interfaces, there are additional rules to block incoming 2482packets with a source IP address identical to the interface's IP(s). 2483For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a 2484netmask of 255.255.255.0: 2485.Pp 2486.Dl antispoof for wi0 inet 2487.Pp 2488Expands to: 2489.Bd -literal -offset indent -compact 2490block drop in on ! wi0 inet from 10.0.0.0/24 to any 2491block drop in inet from 10.0.0.1 to any 2492.Ed 2493.Pp 2494Caveat: Rules created by the 2495.Ic antispoof 2496directive interfere with packets sent over loopback interfaces 2497to local addresses. 2498One should pass these explicitly. 2499.Sh OPERATING SYSTEM FINGERPRINTING 2500Passive OS fingerprinting is a mechanism to inspect nuances of a TCP 2501connection's initial SYN packet and guess at the host's operating system. 2502Unfortunately these nuances are easily spoofed by an attacker so the 2503fingerprint is not useful in making security decisions. 2504But the fingerprint is typically accurate enough to make policy decisions 2505upon. 2506.Pp 2507The fingerprints may be specified by operating system class, by 2508version, or by subtype/patchlevel. 2509The class of an operating system is typically the vendor or genre 2510and would be 2511.Ox 2512for the 2513.Xr pf 4 2514firewall itself. 2515The version of the oldest available 2516.Ox 2517release on the main FTP site 2518would be 2.6 and the fingerprint would be written as: 2519.Pp 2520.Dl \&"OpenBSD 2.6\&" 2521.Pp 2522The subtype of an operating system is typically used to describe the 2523patchlevel if that patch led to changes in the TCP stack behavior. 2524In the case of 2525.Ox , 2526the only subtype is for a fingerprint that was 2527normalised by the 2528.Cm no-df 2529scrub option and would be specified as: 2530.Pp 2531.Dl \&"OpenBSD 3.3 no-df\&" 2532.Pp 2533Fingerprints for most popular operating systems are provided by 2534.Xr pf.os 5 . 2535Once 2536.Xr pf 4 2537is running, a complete list of known operating system fingerprints may 2538be listed by running: 2539.Pp 2540.Dl # pfctl -so 2541.Pp 2542Filter rules can enforce policy at any level of operating system specification 2543assuming a fingerprint is present. 2544Policy could limit traffic to approved operating systems or even ban traffic 2545from hosts that aren't at the latest service pack. 2546.Pp 2547The 2548.Cm unknown 2549class can also be used as the fingerprint which will match packets for 2550which no operating system fingerprint is known. 2551.Pp 2552Examples: 2553.Bd -literal -offset indent 2554pass out proto tcp from any os OpenBSD 2555block out proto tcp from any os Doors 2556block out proto tcp from any os "Doors PT" 2557block out proto tcp from any os "Doors PT SP3" 2558block out from any os "unknown" 2559pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" 2560.Ed 2561.Pp 2562Operating system fingerprinting is limited only to the TCP SYN packet. 2563This means that it will not work on other protocols and will not match 2564a currently established connection. 2565.Pp 2566Caveat: operating system fingerprints are occasionally wrong. 2567There are three problems: an attacker can trivially craft packets to 2568appear as any operating system; 2569an operating system patch could change the stack behavior and no fingerprints 2570will match it until the database is updated; 2571and multiple operating systems may have the same fingerprint. 2572.Sh EXAMPLES 2573In this example, 2574the external interface is 2575.Pa kue0 . 2576We use a macro for the interface name, so it can be changed easily. 2577All incoming traffic is "normalised", 2578and everything is blocked and logged by default. 2579.Bd -literal -offset 4n 2580ext_if = "kue0" 2581match in all scrub (no-df max-mss 1440) 2582block return log on $ext_if all 2583.Ed 2584.Pp 2585Here we specifically block packets we don't want: 2586anything coming from source we have no back routes for; 2587packets whose ingress interface does not match the one in 2588the route back to their source address; 2589anything that does not have our address (157.161.48.183) as source; 2590broadcasts (cable modem noise); 2591and anything from reserved address space or invalid addresses. 2592.Bd -literal -offset 4n 2593block in from no-route to any 2594block in from urpf-failed to any 2595block out log quick on $ext_if from ! 157.161.48.183 to any 2596block in quick on $ext_if from any to 255.255.255.255 2597block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e 2598 192.168.0.0/16, 255.255.255.255/32 } to any 2599.Ed 2600.Pp 2601For ICMP, 2602pass out/in ping queries. 2603State matching is done on host addresses and ICMP ID (not type/code), 2604so replies (like 0/0 for 8/0) will match queries. 2605ICMP error messages (which always refer to a TCP/UDP packet) 2606are handled by the TCP/UDP states. 2607.Bd -literal -offset 4n 2608pass on $ext_if inet proto icmp all icmp-type 8 code 0 2609.Ed 2610.Pp 2611For UDP, 2612pass out all UDP connections. 2613DNS connections are passed in. 2614.Bd -literal -offset 4n 2615pass out on $ext_if proto udp all 2616pass in on $ext_if proto udp from any to any port domain 2617.Ed 2618.Pp 2619For TCP, 2620pass out all TCP connections and modulate state. 2621SSH, SMTP, DNS, and IDENT connections are passed in. 2622We do not allow Windows 9x SMTP connections since they are typically 2623a viral worm. 2624.Bd -literal -offset 4n 2625pass out on $ext_if proto tcp all modulate state 2626pass in on $ext_if proto tcp from any to any \e 2627 port { ssh, smtp, domain, auth } 2628block in on $ext_if proto tcp from any \e 2629 os { "Windows 95", "Windows 98" } to any port smtp 2630.Ed 2631.Pp 2632Here we pass in/out all IPv6 traffic: 2633note that we have to enable this in two different ways, 2634on both our physical interface and our tunnel. 2635.Bd -literal -offset 4n 2636pass quick on gif0 inet6 2637pass quick on $ext_if proto ipv6 2638.Ed 2639.Pp 2640This example illustrates packet tagging. 2641There are three interfaces: $int_if, $ext_if, and $wifi_if (wireless). 2642NAT is being done on $ext_if for all outgoing packets. 2643Packets in on $int_if are tagged and passed out on $ext_if. 2644All other outgoing packets 2645(i.e. packets from the wireless network) 2646are only permitted to access port 80. 2647.Bd -literal -offset 4n 2648pass in on $int_if from any to any tag INTNET 2649pass in on $wifi_if from any to any 2650 2651block out on $ext_if from any to any 2652pass out quick on $ext_if tagged INTNET 2653pass out on $ext_if proto tcp from any to any port 80 2654.Ed 2655.Pp 2656In this example, 2657we tag incoming packets as they are redirected to 2658.Xr spamd 8 . 2659The tag is used to pass those packets through the packet filter. 2660.Bd -literal -offset 4n 2661match in on $ext_if inet proto tcp from <spammers> to port smtp \e 2662 tag SPAMD rdr-to 127.0.0.1 port spamd 2663 2664block in on $ext_if 2665pass in on $ext_if inet proto tcp tagged SPAMD 2666.Ed 2667.Pp 2668This example maps incoming requests on port 80 to port 8080, on 2669which a daemon is running (because, for example, it is not run as root, 2670and therefore lacks permission to bind to port 80). 2671.Bd -literal -offset 4n 2672match in on $ext_if proto tcp from any to any port 80 \e 2673 rdr-to 127.0.0.1 port 8080 2674.Ed 2675.Pp 2676If a 2677.Ic pass 2678rule is used with the 2679.Cm quick 2680modifier, packets matching the translation rule are passed without 2681inspecting subsequent filter rules. 2682.Bd -literal -offset 4n 2683pass in quick on $ext_if proto tcp from any to any port 80 \e 2684 rdr-to 127.0.0.1 port 8080 2685.Ed 2686.Pp 2687In the example below, vlan12 is configured as 192.168.168.1; 2688the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 2689when they are going out any interface except vlan12. 2690This has the net effect of making traffic from the 192.168.168.0/24 2691network appear as though it is the Internet routable address 2692204.92.77.111 to nodes behind any interface on the router except 2693for the nodes on vlan12. 2694Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes. 2695.Bd -literal -offset 4n 2696match out on ! vlan12 from 192.168.168.0/24 to any nat-to 204.92.77.111 2697.Ed 2698.Pp 2699In the example below, the machine sits between a fake internal 2700144.19.74.* network, and a routable external IP of 204.92.77.100. 2701The last rule excludes protocol AH from being translated. 2702.Bd -literal -offset 4n 2703pass out on $ext_if from 144.19.74.0/24 nat-to 204.92.77.100 2704pass out on $ext_if proto ah from 144.19.74.0/24 2705.Ed 2706.Pp 2707In the example below, packets bound for one specific server, as well as those 2708generated by the sysadmins are not proxied; all other connections are. 2709.Bd -literal -offset 4n 2710pass in on $int_if proto { tcp, udp } from any to any port 80 \e 2711 rdr-to 127.0.0.1 port 80 2712pass in on $int_if proto { tcp, udp } from any to $server port 80 2713pass in on $int_if proto { tcp, udp } from $sysadmins to any port 80 2714.Ed 2715.Pp 2716This example maps outgoing packets' source port 2717to an assigned proxy port instead of an arbitrary port. 2718In this case, proxy outgoing isakmp with port 500 on the gateway. 2719.Bd -literal -offset 4n 2720match out on $ext_if inet proto udp from any port isakmp to any \e 2721 nat-to ($ext_if) port 500 2722.Ed 2723.Pp 2724One more example uses 2725.Cm rdr-to 2726to redirect a TCP and UDP port to an internal machine. 2727.Bd -literal -offset 4n 2728match in on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e 2729 rdr-to 10.1.2.151 port 22 2730match in on $ext_if inet proto udp from any to ($ext_if) port 8080 \e 2731 rdr-to 10.1.2.151 port 53 2732.Ed 2733.Pp 2734In this example, a NAT gateway is set up to translate internal addresses 2735using a pool of public addresses (192.0.2.16/28). 2736A given source address is always translated to the same pool address by 2737using the 2738.Cm source-hash 2739keyword. 2740The gateway also translates incoming web server connections 2741to a group of web servers on the internal network. 2742.Bd -literal -offset 4n 2743match out on $ext_if inet from any to any nat-to 192.0.2.16/28 \e 2744 source-hash 2745match in on $ext_if proto tcp from any to any port 80 \e 2746 rdr-to { 10.1.2.155 weight 2, 10.1.2.160 weight 1, \e 2747 10.1.2.161 weight 8 } round-robin 2748.Ed 2749.Pp 2750The bidirectional address translation example uses a single 2751.Cm binat-to 2752rule that expands to a 2753.Cm nat-to 2754and an 2755.Cm rdr-to 2756rule. 2757.Bd -literal -offset 4n 2758pass on $ext_if from 10.1.2.120 to any binat-to 192.0.2.17 2759.Ed 2760.Pp 2761The previous example is identical to the following set of rules: 2762.Bd -literal -offset 4n 2763pass out on $ext_if inet from 10.1.2.120 to any \e 2764 nat-to 192.0.2.17 static-port 2765pass in on $ext_if inet from any to 192.0.2.17 rdr-to 10.1.2.120 2766.Ed 2767.Pp 2768In the example below, a router handling both address families 2769translates an internal IPv4 subnet to IPv6 using the well-known 277064:ff9b::/96 prefix: 2771.Bd -literal -offset 4n 2772pass in on $v4_if inet af-to inet6 from ($v6_if) to 64:ff9b::/96 2773.Ed 2774.Pp 2775Paired with the example above, the example below can be used on 2776another router handling both address families to translate back 2777to IPv4: 2778.Bd -literal -offset 4n 2779pass in on $v6_if inet6 to 64:ff9b::/96 af-to inet from ($v4_if) 2780.Ed 2781.Sh GRAMMAR 2782Syntax for 2783.Nm 2784in BNF: 2785.Bd -literal 2786line = ( option | pf-rule | 2787 antispoof-rule | queue-rule | anchor-rule | 2788 anchor-close | load-anchor | table-rule | include ) 2789 2790option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | 2791 [ "ruleset-optimization" [ "none" | "basic" | 2792 "profile" ] ] | 2793 [ "optimization" [ "default" | "normal" | "high-latency" | 2794 "satellite" | "aggressive" | "conservative" ] ] 2795 [ "limit" ( limit-item | "{" limit-list "}" ) ] | 2796 [ "loginterface" ( interface-name | "none" ) ] | 2797 [ "block-policy" ( "drop" | "return" ) ] | 2798 [ "state-policy" ( "if-bound" | "floating" ) ] 2799 [ "state-defaults" state-opts ] 2800 [ "fingerprints" filename ] | 2801 [ "skip on" ifspec ] | 2802 [ "debug" ( "emerg" | "alert" | "crit" | "err" | 2803 "warning" | "notice" | "info" | "debug" ) ] | 2804 [ "reassemble" ( "yes" | "no" ) [ "no-df" ] ] ) 2805 2806pf-rule = action [ ( "in" | "out" ) ] 2807 [ "log" [ "(" logopts ")"] ] [ "quick" ] 2808 [ "on" ( ifspec | "rdomain" number ) ] [ af ] 2809 [ protospec ] [ hosts ] [ filteropts ] 2810 2811logopts = logopt [ [ "," ] logopts ] 2812logopt = "all" | "matches" | "user" | "to" interface-name 2813 2814filteropts = filteropt [ [ "," ] filteropts ] 2815filteropt = user | group | flags | icmp-type | icmp6-type | 2816 "tos" tos | 2817 ( "no" | "keep" | "modulate" | "synproxy" ) "state" 2818 [ "(" state-opts ")" ] | "scrub" "(" scrubopts ")" | 2819 "fragment" | "allow-opts" | "once" | 2820 "divert-packet" "port" port | "divert-reply" | 2821 "divert-to" host "port" port | 2822 "label" string | "tag" string | [ "!" ] "tagged" string | 2823 "max-pkt-rate" number "/" seconds | 2824 "set delay" number | 2825 "set prio" ( number | "(" number [ [ "," ] number ] ")" ) | 2826 "set queue" ( string | "(" string [ [ "," ] string ] ")" ) | 2827 "rtable" number | "probability" number"%" | "prio" number | 2828 "af-to" af "from" ( redirhost | "{" redirhost-list "}" ) 2829 [ "to" ( redirhost | "{" redirhost-list "}" ) ] | 2830 "binat-to" ( redirhost | "{" redirhost-list "}" ) 2831 [ portspec ] [ pooltype ] | 2832 "rdr-to" ( redirhost | "{" redirhost-list "}" ) 2833 [ portspec ] [ pooltype ] | 2834 "nat-to" ( redirhost | "{" redirhost-list "}" ) 2835 [ portspec ] [ pooltype ] [ "static-port" ] | 2836 [ route ] | [ "set tos" tos ] | 2837 [ [ "!" ] "received-on" ( interface-name | interface-group ) ] 2838 2839scrubopts = scrubopt [ [ "," ] scrubopts ] 2840scrubopt = "no-df" | "min-ttl" number | "max-mss" number | 2841 "reassemble tcp" | "random-id" 2842 2843antispoof-rule = "antispoof" [ "log" ] [ "quick" ] 2844 "for" ifspec [ af ] [ "label" string ] 2845 2846table-rule = "table" "<" string ">" [ tableopts ] 2847tableopts = tableopt [ tableopts ] 2848tableopt = "persist" | "const" | "counters" | 2849 "file" string | "{" [ tableaddrs ] "}" 2850tableaddrs = tableaddr-spec [ [ "," ] tableaddrs ] 2851tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ] 2852tableaddr = hostname | ifspec | "self" | 2853 ipv4-dotted-quad | ipv6-coloned-hex 2854 2855queue-rule = "queue" string [ "on" interface-name ] queueopts-list 2856 2857anchor-rule = "anchor" [ string ] [ ( "in" | "out" ) ] [ "on" ifspec ] 2858 [ af ] [ protospec ] [ hosts ] [ filteropt-list ] [ "{" ] 2859 2860anchor-close = "}" 2861 2862load-anchor = "load anchor" string "from" filename 2863 2864queueopts-list = queueopts-list queueopts | queueopts 2865queueopts = ([ "bandwidth" bandwidth ] | [ "min" bandwidth ] | 2866 [ "max" bandwidth ] | [ "parent" string ] | 2867 [ "default" ]) | 2868 ([ "flows" number ] | [ "quantum" number ]) | 2869 [ "qlimit" number ] 2870 2871bandwidth = bandwidth-spec [ "burst" bandwidth-spec "for" number "ms" ] 2872bandwidth-spec = number ( "" | "K" | "M" | "G" ) 2873 2874action = "pass" | "match" | "block" [ return ] 2875return = "drop" | "return" | 2876 "return-rst" [ "(" "ttl" number ")" ] | 2877 "return-icmp" [ "(" icmpcode [ [ "," ] icmp6code ] ")" ] | 2878 "return-icmp6" [ "(" icmp6code ")" ] 2879icmpcode = ( icmp-code-name | icmp-code-number ) 2880icmp6code = ( icmp6-code-name | icmp6-code-number ) 2881 2882ifspec = ( [ "!" ] ( interface-name | interface-group ) ) | 2883 "{" interface-list "}" 2884interface-list = [ "!" ] ( interface-name | interface-group ) 2885 [ [ "," ] interface-list ] 2886route = ( "route-to" | "reply-to" | "dup-to" ) 2887 ( redirhost | "{" redirhost-list "}" ) 2888af = "inet" | "inet6" 2889 2890protospec = "proto" ( proto-name | proto-number | 2891 "{" proto-list "}" ) 2892proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] 2893 2894hosts = "all" | 2895 "from" ( "any" | "no-route" | "urpf-failed" | "self" | 2896 host | "{" host-list "}" | "route" string ) [ port ] 2897 [ os ] 2898 "to" ( "any" | "no-route" | "self" | host | 2899 "{" host-list "}" | "route" string ) [ port ] 2900 2901ipspec = "any" | host | "{" host-list "}" 2902host = [ "!" ] ( address [ "weight" number ] | 2903 address [ "/" mask-bits ] [ "weight" number ] | 2904 "<" string ">" ) 2905redirhost = address [ "/" mask-bits ] 2906address = ( interface-name | interface-group | 2907 "(" ( interface-name | interface-group ) ")" | 2908 hostname | ipv4-dotted-quad | ipv6-coloned-hex ) 2909host-list = host [ [ "," ] host-list ] 2910redirhost-list = redirhost [ [ "," ] redirhost-list ] 2911 2912port = "port" ( unary-op | binary-op | "{" op-list "}" ) 2913portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ] 2914os = "os" ( os-name | "{" os-list "}" ) 2915user = "user" ( unary-op | binary-op | "{" op-list "}" ) 2916group = "group" ( unary-op | binary-op | "{" op-list "}" ) 2917 2918unary-op = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ] 2919 ( name | number ) 2920binary-op = number ( "<>" | "><" | ":" ) number 2921op-list = ( unary-op | binary-op ) [ [ "," ] op-list ] 2922 2923os-name = operating-system-name 2924os-list = os-name [ [ "," ] os-list ] 2925 2926flags = "flags" ( [ flag-set ] "/" flag-set | "any" ) 2927flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ] 2928 [ "W" ] 2929 2930icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) 2931icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" ) 2932icmp-type-code = ( icmp-type-name | icmp-type-number ) 2933 [ "code" ( icmp-code-name | icmp-code-number ) ] 2934icmp-list = icmp-type-code [ [ "," ] icmp-list ] 2935 2936tos = ( "lowdelay" | "throughput" | "reliability" | 2937 [ "0x" ] number ) 2938 2939state-opts = state-opt [ [ "," ] state-opts ] 2940state-opt = ( "max" number | "no-sync" | timeout | "sloppy" | 2941 "pflow" | "source-track" [ ( "rule" | "global" ) ] | 2942 "max-src-nodes" number | "max-src-states" number | 2943 "max-src-conn" number | 2944 "max-src-conn-rate" number "/" number | 2945 "overload" "<" string ">" [ "flush" [ "global" ] ] | 2946 "if-bound" | "floating" ) 2947 2948timeout-list = timeout [ [ "," ] timeout-list ] 2949timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | 2950 "tcp.closing" | "tcp.finwait" | "tcp.closed" | "tcp.tsdiff" | 2951 "udp.first" | "udp.single" | "udp.multiple" | 2952 "icmp.first" | "icmp.error" | 2953 "other.first" | "other.single" | "other.multiple" | 2954 "frag" | "interval" | "src.track" | 2955 "adaptive.start" | "adaptive.end" ) number 2956 2957limit-list = limit-item [ [ "," ] limit-list ] 2958limit-item = ( "states" | "frags" | "src-nodes" | "tables" | 2959 "table-entries" ) number 2960 2961pooltype = ( "bitmask" | "least-states" | 2962 "random" | "round-robin" | 2963 "source-hash" [ ( hex-key | string-key ) ] ) 2964 [ "sticky-address" ] 2965 2966include = "include" filename 2967.Ed 2968.Sh FILES 2969.Bl -tag -width /etc/examples/pf.conf -compact 2970.It Pa /etc/hosts 2971Host name database. 2972.It Pa /etc/pf.conf 2973Default location of the ruleset file. 2974.It Pa /etc/examples/pf.conf 2975Example ruleset file. 2976.It Pa /etc/pf.os 2977Default location of OS fingerprints. 2978.It Pa /etc/protocols 2979Protocol name database. 2980.It Pa /etc/services 2981Service name database. 2982.El 2983.Sh SEE ALSO 2984.Xr pf 4 , 2985.Xr pflow 4 , 2986.Xr pfsync 4 , 2987.Xr pf.os 5 , 2988.Xr pfctl 8 , 2989.Xr pflogd 8 2990.Sh HISTORY 2991The 2992.Nm 2993file format first appeared in 2994.Ox 3.0 . 2995