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