1.\" $OpenBSD: pf.conf.5,v 1.10 2001/07/31 09:02:18 wilfried 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 ] 50 [ "proto" ( proto-name | proto-number ) ] 51 hosts 52 [ flags ] [ icmp-type ] [ "keep-state" ] 53 [ "no-df" ] [ "min-ttl" number ]. 54 55action = "pass" | "block" [ return ] | "scrub" . 56return = "return-rst" | 57 "return-icmp" [ "(" ( icmp-code-name | icmp-code-number ) ")" ] 58 . 59 60hosts = "all" | 61 "from" ( "any" | host ) [ port ] "to" ( "any" | host ) [ port ] 62 . 63host = [ "!" ] address [ "/" mask-bits ] . 64port = "port" ( unary-op | binary-op ) . 65unary-op = ( "=" | "!=" | "<" | "<=" | ">" | ">=" ) 66 ( port-name | port-number ) . 67binary-op = port-number ( "<>" | "><" ) port-number . 68 69flags = "flags" ( flag-set | flag-set "/" flag-set | "/" flag-set ) . 70flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] . 71 72icmp-type = "icmp-type" ( icmp-type-name | icmp-type-number ) 73 [ "code" ( icmp-code-name | icmp-code-number ) ] . 74.Ed 75.Sh FILTER RULES 76Filter rules are typically manipulated using 77.Xr pfctl 8 . 78Filter rules are loaded from a text file into the kernel using 79.Pp 80.Cm # pfctl -R file 81.Pp 82which replaces the active rule set with the new one. 83The active rule set can be displayed using 84.Pp 85.Cm # pfctl -s r 86.Pp 87For each packet processed by the packet filter, the filter rules are 88evaluated in sequential order, from first to last. 89Each rule either matches the packet or doesn't. 90The last matching rule decides what action is taken. 91.Pp 92If no rule matches the packet, the default action is 93.Em pass . 94.Pp 95To block everything by default and only pass packets 96that match explicit rules, one uses 97.Bd -literal 98.Cm block in all 99.Cm block out all 100.Ed 101.Pp 102as the first two rules. 103.Sh ACTIONS 104.Bl -tag -width Fl 105.It Em pass 106The packet is passed. 107.It Em block 108The packet is blocked. 109Optionally, the filter can return a TCP RST or ICMP UNREACHABLE packet 110to the sender, where applicable. 111.It Em scrub 112The packet is run through normalization/defragmentation. 113Scrub rules are not considered last matching rules. 114.El 115.Sh LOGGING 116.Bl -tag -width Fl 117.It Em log 118In addition to the action specified, a log message is generated. 119.It Em log-all 120Used with 121.Sq keep state 122rules. 123Not only the packet that creates state is logged, but all packets of 124the connection. 125.El 126.Pp 127The log messages can be viewed with tcpdump: 128.Bd -literal 129.Cm # ifconfig pflog0 up 130.Cm # tcpdump -n -i pflog0 131.Ed 132.Sh QUICK 133If a packet matches a rule which has the 134.Sq quick 135option set, this rule 136is considered the last matching rule, and evaluation of subsequent rules 137is skipped. 138.Sh PARAMETERS 139The rule parameters specify for what packets a rule applies. 140A packet always comes in on or goes out through one interface. 141Most parameters are optional. 142If a parameter is specified, the rule only applies to packets with 143matching attributes. 144.Ss in or out 145The rule applies to incoming or outgoing packets. 146Either 147.Em in 148or 149.Em out 150must be specified. 151To cover both directions, two rules are needed. 152.Ss on <interface> 153The rule applies only to packets coming in on or going out through this 154particular interface. 155.Ss proto <protocol> 156The rule applies only to packets of this protocol. 157Common protocols used here are tcp, udp and icmp. 158.Ss from <source> port <source> to <dest> port <dest> 159The rule applies only to packets with the specified source and destination 160addresses/ports. 161Addresses can be specified in CIDR notation (matching netblocks) and ports 162can be specified using these operators 163.Bd -literal 164 = (equal), != (unequal), < (lesser), <= (lesser or equal), > (greater), 165 >= (greater or equal), >< (range) and <> (except range). 166.Ed 167.Pp 168>< and <> are binary operators (they take two arguments), and the range 169doesn't include the limits, for instance: 170.Bl -tag -width Fl 171.It Em port 2000 >< 2004 172means 173.Sq all ports > 2000 and < 2004 , 174hence ports 2001, 2002 and 2003. 175.It Em port 2000 <> 2004 176means 177.Sq all ports < 2000 or > 2004 , 178hence ports 1-1999 and 2005-65535. 179.El 180.Pp 181The host and port specifications are optional, as the following examples 182show: 183.Bd -literal 184 pass in all 185 pass in from any to any 186 pass in proto tcp from any port <= 1024 to any 187 pass in proto tcp from any to any port = 25 188 pass in proto tcp from 10.0.0.0/8 port > 1024 to ! 10.1.2.3 port != 22 189.Ed 190.Ss flags <a> | <a>/<b> | /<b> 191The rule only applies to TCP packets that have the flags <a> set 192out of set <b>. 193Flags not specified in <b> are ignored. 194.Bl -tag -width Fl 195.It Em flags S/S 196Flag SYN is set. 197The other flags are ignored. 198.It Em flags S/SA 199Of SYN and ACK, exactly SYN is set. 200SYN, SYN+PSH, SYN+RST match, but SYN+ACK, ACK and ACK+RST don't. 201This is more restrictive than the previous example. 202.It Em flags S 203If the second set is not specified, it defaults to FSRPAU. 204Hence, only packets with SYN set and all other flags unset match this 205rule. This is more restrictive than the previous example. 206.It Em flags /SFRA 207If the first set is not specified, it defaults to none. 208All of SYN, FIN, RST and ACK must be unset. 209.El 210.Ss icmp-type <type> code <code> 211The rule only applies to ICMP packets with the specified type and code. 212This parameter is only valid for rules that cover protocol icmp. 213.Sh STATEFUL INSPECTION 214.Em pf 215is a stateful packet filter, which means it can track the state of 216a connection. 217Instead of passing all traffic to port 25, for instance, one can pass 218only the initial packet and keep state. 219.Pp 220If a packet matches a pass ... keep-state rule, the filter creates 221a state for this connection and automatically lets pass all following 222packets of that connection. 223.Pp 224Before any rules are evaluated, the filter checks whether the packet 225matches any state. 226If it does, the packet is passed without evaluation of any rules. 227.Pp 228States are removed after the connection is closed or has timed out. 229.Pp 230This has several advantages. 231Comparing a packet to a state involves checking its sequence numbers. 232If the sequence numbers are outside the narrow windows of expected 233values, the packet is dropped. 234This prevents spoofing attacks, where the attacker sends packets with 235a fake source address/port but doesn't know the connection's sequence 236numbers. 237.Pp 238Also, looking up states is usually faster than evaluating rules. 239If one has 50 rules, all of them are evaluated sequentially in O(n). 240Even with 50'000 states, only 16 comparisons are needed to match a 241state, since states are stored in a binary search tree that allows 242searches in O(log2 n). 243.Pp 244For instance: 245.Bd -literal 246 block out all 247 block in all 248 pass out proto tcp from any to any flags S/SA keep state 249 pass in proto tcp from any to any port = 25 flags S/SA keep state 250.Ed 251.Pp 252This rule set blocks everything by default. 253Only outgoing connections and incoming connection to port 25 are allowed. 254The inital packet of each connection has the SYN flag set, will be passed 255and creates state. 256All further packets of these connections are passed if they match a state. 257.Pp 258Specifying flags S/SA restricts state creation to the initial SYN 259packet of the TCP handshake. 260One can also be less restrictive, and allow state creation from 261intermediate 262.Pq non-SYN 263packets. 264This will cause pf to synchronize to existing connections, for instance 265if one flushes the state table. 266.Pp 267For UDP, which is stateless by nature, keep state will create state 268as well. 269UDP packets are matched to states using only host addresses and ports. 270.Pp 271ICMP messages fall in two categories: ICMP error messages, which always 272refer to a TCP or UDP packet, are matched against the refered to connection. 273If one keeps state on a TCP connection, and an ICMP source quench message 274refering to this TCP connection arrives, it will be matched to the right 275state and get passed. 276.Pp 277For ICMP queries, keep state creates an ICMP state, and 278.Em pf 279knows how to match ICMP replies to states. 280For example 281.Bd -literal 282 pass out proto icmp all icmp-type echoreq keep state 283.Ed 284.Pp 285lets echo requests 286.Pq pings 287out, creates state, and matches incoming echo replies correctly to states. 288.Pp 289Note: nat/rdr rules 290.Po 291see 292.Xr nat.conf 5 293.Pc 294implicitely create state for connections. 295.Sh NORMALIZATION 296Packet normalization is envoked via the 297.Pa scrub 298directive. Normalization is used to sanitize packet content in such 299a way that there are no ambiguities in packet interpretation on 300the receiver side. 301.Pp 302The normalizer does full IP fragment reassembly to prevent attacks 303that confuse intrusion detection systems by sending overlapping 304IP fragments. 305.Ss no-df 306Clears the 307.Pa dont-fragment 308bit from a matching ip packet. 309.Ss min-ttl <number> 310Enforces a minium ttl for matching ip packets. 311.Sh EXAMPLES 312.Bd -literal 313# My external interface is kue0 (157.161.48.183, my only routable address) 314# and the private network is 10.0.0.0/8, for which i'm doing NAT. 315 316# block and log everything by default 317block out log on kue0 all 318block in log on kue0 all 319block return-rst out log on kue0 proto tcp all 320block return-rst in log on kue0 proto tcp all 321block return-icmp out log on kue0 proto udp all 322block return-icmp in log on kue0 proto udp all 323 324# block and log outgoing packets that don't have my address as source, 325# they are either spoofed or something is misconfigured (NAT disabled, 326# for instance), we want to be nice and don't send out garbage. 327block out log quick on kue0 from ! 157.161.48.183 to any 328 329# silently drop broadcasts (cable modem noise) 330block in quick on kue0 from any to 255.255.255.255 331 332# block and log incoming packets from reserved address space and invalid 333# addresses, they are either spoofed or misconfigured, we can't reply to 334# them anyway (hence, no return-rst). 335block in log quick on kue0 from 10.0.0.0/8 to any 336block in log quick on kue0 from 172.16.0.0/12 to any 337block in log quick on kue0 from 192.168.0.0/16 to any 338block in log quick on kue0 from 255.255.255.255/32 to any 339 340# ----------------------------------------------------------------------- 341# ICMP 342# ----------------------------------------------------------------------- 343 344# pass out/in certain ICMP queries and keep state (ping) 345# state matching is done on host addresses and ICMP id (not type/code), 346# so replies (like 0/0 for 8/0) will match queries 347# ICMP error messages (which always refer to a TCP/UDP packet) are 348# handled by the TCP/UDP states 349pass out on kue0 proto icmp all icmp-type 8 code 0 keep state 350pass in on kue0 proto icmp all icmp-type 8 code 0 keep state 351 352# ----------------------------------------------------------------------- 353# UDP 354# ----------------------------------------------------------------------- 355 356# pass out all UDP connections and keep state 357pass out on kue0 proto udp all keep state 358 359# pass in certain UDP connections and keep state (DNS) 360pass in on kue0 proto udp from any to any port = domain keep state 361 362# ----------------------------------------------------------------------- 363# TCP 364# ----------------------------------------------------------------------- 365 366# pass out all TCP connections and keep state 367pass out on kue0 proto tcp all keep state 368 369# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) 370pass in on kue0 proto tcp from any to any port = ssh keep state 371pass in on kue0 proto tcp from any to any port = smtp keep state 372pass in on kue0 proto tcp from any to any port = domain keep state 373pass in on kue0 proto tcp from any to any port = auth keep state 374.Ed 375.Sh FILES 376.Bl -tag -width "/etc/pf.conf" -compact 377.It Pa /etc/pf.conf 378.It Pa /etc/services 379.El 380.Sh SEE ALSO 381.Xr pf 4 , 382.Xr nat.conf 5 , 383.Xr services 5 , 384.Xr pfctl 8 385.Pp 386.Pa http://www.obfuscation.org/ipf/ 387has an extensive filter rule tutorial which for the most part applies to 388.Em pf 389as well. 390.Sh HISTORY 391The 392.Nm 393file format appeared in 394.Ox 3.0 . 395