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