1.\" $OpenBSD: pf.conf.5,v 1.26 2001/10/24 10:23:53 dhartmei Exp $ 2.\" 3.\" Copyright (c) 2001, 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 July 8, 2001 31.Dt PF.CONF 5 32.Os 33.Sh NAME 34.Nm pf.conf 35.Nd filter rule configuration file for packet filtering 36.Sh DESCRIPTION 37The 38.Xr pf 4 39packet filter drops, passes and modifies packets according to the 40rules defined in this file. 41For each packet inspected by the filter, the set of rules is evaluated 42from top to bottom, and the last matching rule decides what action is 43performed. 44.Sh GRAMMAR 45Syntax for filter rules in BNF: 46.Bd -literal 47rule = action ( "in" | "out" ) 48 [ "log" | "log-all" ] [ "quick" ] 49 [ "on" interface-name ] [ af ] 50 [ "proto" ( proto-name | proto-number | "{" proto-list "}" ) ] 51 hosts 52 [ flags ] ( [ icmp-type ] | [ ipv6-icmp-type ] ) 53 [ "keep state" ] [ "modulate state" ] 54 [ "no-df" ] [ "min-ttl" number ] [ "allow-opts" ] . 55 56action = "pass" | "block" [ return ] | "scrub" . 57return = "return-rst" | 58 "return-icmp" [ "(" ( icmp-code-name | icmp-code-number ) ")" ] | 59 "return-icmp6" [ "(" ( icmp-code-name | icmp-code-number ) ")" ] . 60 61af = "inet" | "inet6" . 62proto-list = ( proto-name | proto-number ) [ "," proto-list ] . 63 64hosts = "all" | 65 "from" ( "any" | host | "{" host-list "}" ) [ port ] 66 "to" ( "any" | host | "{" host-list "}" ) [ port ] . 67 68host = [ "!" ] address [ "/" mask-bits ] . 69host-list = host [ "," host-list ] . 70port = "port" ( unary-op | binary-op | "{" port-list "}" ) . 71port-list = ( unary-op | binary-op ) [ "," port-list ] . 72unary-op = ( "=" | "!=" | "<" | "<=" | ">" | ">=" ) 73 ( port-name | port-number ) . 74binary-op = port-number ( "<>" | "><" ) port-number . 75 76flags = "flags" ( flag-set | flag-set "/" flag-set | "/" flag-set ) . 77flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] . 78 79icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) . 80ipv6-icmp-type = "ipv6-icmp-type" ( icmp-type-code | "{" icmp-list "}" ) . 81icmp-type-code = ( icmp-type-name | icmp-type-number ) 82 [ "code" ( icmp-code-name | icmp-code-number ) ] . 83icmp-list = icmp-type-code [ "," icmp-list ] . 84 85.Ed 86.Sh FILTER RULES 87Filter rules are typically manipulated using 88.Xr pfctl 8 . 89Filter rules are loaded from a text file into the kernel using 90.Pp 91.Cm # pfctl -R file 92.Pp 93which replaces the active rule set with the new one. 94The active rule set can be displayed using 95.Pp 96.Cm # pfctl -s r 97.Pp 98For each packet processed by the packet filter, the filter rules are 99evaluated in sequential order, from first to last. 100Each rule either matches the packet or doesn't. 101The last matching rule decides what action is taken. 102.Pp 103If no rule matches the packet, the default action is 104.Em pass . 105.Pp 106To block everything by default and only pass packets 107that match explicit rules, one uses 108.Bd -literal 109.Cm block in all 110.Cm block out all 111.Ed 112.Pp 113as the first two rules. 114.Sh ACTIONS 115.Bl -tag -width Fl 116.It Em pass 117The packet is passed. 118.It Em block 119The packet is blocked. 120Optionally, the filter can return a TCP RST or ICMP UNREACHABLE packet 121to the sender, where applicable. 122.It Em scrub 123The packet is run through normalization/defragmentation. 124Scrub rules are not considered last matching rules. 125IPv6 packets are not defragmented. 126.El 127.Sh LOGGING 128.Bl -tag -width Fl 129.It Em log 130In addition to the action specified, a log message is generated. 131.It Em log-all 132Used with 133.Sq keep state 134or 135.Sq modulate state 136rules. 137Not only the packet that creates state is logged, but all packets of 138the connection. 139.El 140.Pp 141The logged packets are sent to the 142.Em pflog0 143interface. 144This interface is monitored by the 145.Xr pflogd 8 146logging daemon which dumps the logged packets to the file 147.Em /var/log/pflog 148in 149.Xr tcpdump 8 150binary format. 151The log files can be read using tcpdump: 152.Bd -literal 153.Cm # tcpdump -n -e -ttt -r /var/log/pflog 154.Ed 155.Sh QUICK 156If a packet matches a rule which has the 157.Sq quick 158option set, this rule 159is considered the last matching rule, and evaluation of subsequent rules 160is skipped. 161.Sh PARAMETERS 162The rule parameters specify for what packets a rule applies. 163A packet always comes in on or goes out through one interface. 164Most parameters are optional. 165If a parameter is specified, the rule only applies to packets with 166matching attributes. 167Certain parameters can be expressed as lists, in which case 168.Em pfctl 169generates all needed rule combinations. 170.Ss in or out 171The rule applies to incoming or outgoing packets. 172Either 173.Em in 174or 175.Em out 176must be specified. 177To cover both directions, two rules are needed. 178.Ss on <interface> 179The rule applies only to packets coming in on or going out through this 180particular interface. 181.Ss <af> 182The rule applies only to packets of this address family. 183Supported values are inet and inet6. 184.Ss proto <protocol> 185The rule applies only to packets of this protocol. 186Common protocols used here are tcp, udp, icmp and ipv6-icmp. 187.Ss from <source> port <source> to <dest> port <dest> 188The rule applies only to packets with the specified source and destination 189addresses/ports. 190.Pp 191Addresses can be specified in CIDR notation (matching netblocks), as 192symbolic host names or interface names. 193Host name resolution and interface to address translation are done at 194rule set load-time. 195When the address of an interface (or host name) changes (by DHCP or PPP, 196for instance), the rule set must be reloaded for the change to be reflected 197in the kernel. 198See 199.Xr dhclient-script 8 200or 201.Xr ppp 8 202for information on how to automate this task. 203.Pp 204Ports can be specified using these operators 205.Bd -literal 206 = (equal), != (unequal), < (lesser), <= (lesser or equal), > (greater), 207 >= (greater or equal), >< (range) and <> (except range). 208.Ed 209.Pp 210>< and <> are binary operators (they take two arguments), and the range 211doesn't include the limits, for instance: 212.Bl -tag -width Fl 213.It Em port 2000 >< 2004 214means 215.Sq all ports > 2000 and < 2004 , 216hence ports 2001, 2002 and 2003. 217.It Em port 2000 <> 2004 218means 219.Sq all ports < 2000 or > 2004 , 220hence ports 1-1999 and 2005-65535. 221.El 222.Pp 223The host and port specifications are optional, as the following examples 224show: 225.Bd -literal 226 pass in all 227 pass in from any to any 228 pass in proto tcp from any port <= 1024 to any 229 pass in proto tcp from any to any port = 25 230 pass in proto tcp from 10.0.0.0/8 port > 1024 to ! 10.1.2.3 port != 22 231.Ed 232.Ss flags <a> | <a>/<b> | /<b> 233The rule only applies to TCP packets that have the flags <a> set 234out of set <b>. 235Flags not specified in <b> are ignored. 236Possible flags are F (FIN), S (SYN), R (RST), P (PUSH), A (ACK) and U (URG). 237.Bl -tag -width Fl 238.It Em flags S/S 239Flag SYN is set. 240The other flags are ignored. 241.It Em flags S/SA 242Of SYN and ACK, exactly SYN is set. 243SYN, SYN+PSH, SYN+RST match, but SYN+ACK, ACK and ACK+RST don't. 244This is more restrictive than the previous example. 245.It Em flags S 246If the second set is not specified, it defaults to FSRPAU. 247Hence, only packets with SYN set and all other flags unset match this 248rule. 249This is more restrictive than the previous example. 250.It Em flags /SFRA 251If the first set is not specified, it defaults to none. 252All of SYN, FIN, RST and ACK must be unset. 253.El 254.Ss icmp-type <type> code <code> and ipv6-icmp-type <type> code <code> 255The rule only applies to ICMP or ICMPv6 packets with the specified type 256and code. 257This parameter is only valid for rules that cover protocols icmp or 258ipv6-icmp. 259The protocol and the icmp type indicator (icmp-type or ipv6-icmp-type) 260must match. 261.Ss allow-opts 262By default, packets which contain IP options are blocked. 263When 264.Em allow-opts 265is specified for a 266.Em pass 267rule, packets that pass the filter based on that rule (last matching) 268do so even if they contain IP options. 269For packets that match state, the rule that initially created the 270state is used. 271The implicit 272.Em pass 273rule that is used when a packet doesn't match any rules does not 274allow IP options. 275.Sh MACROS 276.Em pfctl 277supports macro definition and expansion like: 278.Bd -literal 279 ext_if = "kue0" 280 pass out on $ext_if from any to any keep state 281 pass in on $ext_if from any to any port = 25 keep state 282.Ed 283.Pp 284Macro names must start with a letter and may contain letters, digits 285and underscores. 286Macros are not expanded recursively. 287.Sh STATEFUL INSPECTION 288.Em pf 289is a stateful packet filter, which means it can track the state of 290a connection. 291Instead of passing all traffic to port 25, for instance, one can pass 292only the initial packet and keep state. 293.Pp 294If a packet matches a pass ... keep state rule, the filter creates 295a state for this connection and automatically lets pass all following 296packets of that connection. 297.Pp 298Before any rules are evaluated, the filter checks whether the packet 299matches any state. 300If it does, the packet is passed without evaluation of any rules. 301.Pp 302States are removed after the connection is closed or has timed out. 303.Pp 304This has several advantages. 305Comparing a packet to a state involves checking its sequence numbers. 306If the sequence numbers are outside the narrow windows of expected 307values, the packet is dropped. 308This prevents spoofing attacks, where the attacker sends packets with 309a fake source address/port but doesn't know the connection's sequence 310numbers. 311.Pp 312Also, looking up states is usually faster than evaluating rules. 313If one has 50 rules, all of them are evaluated sequentially in O(n). 314Even with 50'000 states, only 16 comparisons are needed to match a 315state, since states are stored in a binary search tree that allows 316searches in O(log2 n). 317.Pp 318For instance: 319.Bd -literal 320 block out all 321 block in all 322 pass out proto tcp from any to any flags S/SA keep state 323 pass in proto tcp from any to any port = 25 flags S/SA keep state 324.Ed 325.Pp 326This rule set blocks everything by default. 327Only outgoing connections and incoming connection to port 25 are allowed. 328The inital packet of each connection has the SYN flag set, will be passed 329and creates state. 330All further packets of these connections are passed if they match a state. 331.Pp 332Specifying flags S/SA restricts state creation to the initial SYN 333packet of the TCP handshake. 334One can also be less restrictive, and allow state creation from 335intermediate 336.Pq non-SYN 337packets. 338This will cause 339.Em pf 340to synchronize to existing connections, for instance 341if one flushes the state table. 342.Pp 343For UDP, which is stateless by nature, keep state will create state 344as well. 345UDP packets are matched to states using only host addresses and ports. 346.Pp 347ICMP messages fall in two categories: ICMP error messages, which always 348refer to a TCP or UDP packet, are matched against the refered to connection. 349If one keeps state on a TCP connection, and an ICMP source quench message 350refering to this TCP connection arrives, it will be matched to the right 351state and get passed. 352.Pp 353For ICMP queries, keep state creates an ICMP state, and 354.Em pf 355knows how to match ICMP replies to states. 356For example 357.Bd -literal 358 pass out inet proto icmp all icmp-type echoreq keep state 359.Ed 360.Pp 361lets echo requests 362.Pq pings 363out, creates state, and matches incoming echo replies correctly to states. 364.Pp 365Note: nat/rdr rules 366.Po 367see 368.Xr nat.conf 5 369.Pc 370implicitly create state for connections. 371.Sh STATE MODULATION 372Much of the security derived from TCP is attributable to how well the 373initial sequence numbers (ISNs) are chosen. 374Some popular stack implementations choose 375.Cm very 376poor ISNs thus are normally susceptible to ISN prediction exploits. 377By applying a "modulate state" rule to a TCP connection, 378.Em pf 379will create a high quality random sequence number for each connection 380endpoint. 381.Pp 382The "modulate state" directive implicitly keeps state on the rule and is 383only applicable to TCP connections. 384.Pp 385For instance: 386.Bd -literal 387 block out all 388 block in all 389 pass out proto tcp from any to any modulate state 390 pass in proto tcp from any to any port = 25 flags S/SA modulate state 391.Ed 392.Pp 393Caveat: If 394.Em pf 395picks up an already established connection (the firewall was rebooted, the 396state table was flushed, ...) it will not randomize the sequence number and it 397will fall back to operating as if "keep state" was specified for that 398connection. 399.Pp 400Caveat: If the state table is flushed or the firewall is rebooted, 401currently established modulated connections can not be continued or picked 402up again by the firewall. 403The sequence numbers will be out of sync without the modulator. 404.Sh NORMALIZATION 405Packet normalization is invoked via the 406.Pa scrub 407directive. 408Normalization is used to sanitize packet content in such 409a way that there are no ambiguities in packet interpretation on 410the receiving side. 411.Pp 412The normalizer does full IP fragment reassembly to prevent attacks 413that confuse intrusion detection systems by sending overlapping 414IP fragments. 415.Ss no-df 416Clears the 417.Pa dont-fragment 418bit from a matching ip packet. 419.Ss min-ttl <number> 420Enforces a minimum ttl for matching ip packets. 421.Sh EXAMPLES 422.Bd -literal 423# The external interface is kue0 (157.161.48.183, the only routable address) 424# and the private network is 10.0.0.0/8, for which we are doing NAT. 425 426# use a macro for the interface name, so it can be changed easily 427ext_if = "kue0" 428 429# normalize all incoming traffic 430scrub in on $ext_if all 431 432# block and log everything by default 433block out log on $ext_if all 434block in log on $ext_if all 435block return-rst out log on $ext_if proto tcp all 436block return-rst in log on $ext_if proto tcp all 437block return-icmp out log on $ext_if proto udp all 438block return-icmp in log on $ext_if proto udp all 439 440# block and log outgoing packets that don't have our address as source, 441# they are either spoofed or something is misconfigured (NAT disabled, 442# for instance), we want to be nice and don't send out garbage. 443block out log quick on $ext_if from ! 157.161.48.183 to any 444 445# silently drop broadcasts (cable modem noise) 446block in quick on $ext_if from any to 255.255.255.255 447 448# block and log incoming packets from reserved address space and invalid 449# addresses, they are either spoofed or misconfigured, we can't reply to 450# them anyway (hence, no return-rst). 451block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \\ 452 192.168.0.0/16, 255.255.255.255/32 } to any 453 454# ICMP 455 456# pass out/in certain ICMP queries and keep state (ping) 457# state matching is done on host addresses and ICMP id (not type/code), 458# so replies (like 0/0 for 8/0) will match queries 459# ICMP error messages (which always refer to a TCP/UDP packet) are 460# handled by the TCP/UDP states 461pass out on $ext_if inet proto icmp all icmp-type 8 code 0 keep state 462pass in on $ext_if inet proto icmp all icmp-type 8 code 0 keep state 463 464# UDP 465 466# pass out all UDP connections and keep state 467pass out on $ext_if proto udp all keep state 468 469# pass in certain UDP connections and keep state (DNS) 470pass in on $ext_if proto udp from any to any port = domain keep state 471 472# TCP 473 474# pass out all TCP connections and modulate state 475pass out on $ext_if proto tcp all modulate state 476 477# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) 478pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \\ 479 auth } keep state 480.Ed 481.Sh FILES 482.Bl -tag -width "/etc/pf.conf" -compact 483.It Pa /etc/pf.conf 484.It Pa /etc/services 485.El 486.Sh SEE ALSO 487.Xr pf 4 , 488.Xr nat.conf 5 , 489.Xr services 5 , 490.Xr pfctl 8 , 491.Xr pflogd 8 492.Sh HISTORY 493The 494.Nm 495file format appeared in 496.Ox 3.0 . 497