1.\" $OpenBSD: pfctl.8,v 1.110 2004/03/20 09:31:42 david Exp $ 2.\" $DragonFly: src/usr.sbin/pfctl/pfctl.8,v 1.1 2004/09/21 21:25:28 joerg Exp $ 3.\" 4.\" Copyright (c) 2001 Kjell Wooding. 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.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd November 20, 2002 29.Dt PFCTL 8 30.Os 31.Sh NAME 32.Nm pfctl 33.Nd "control the packet filter (PF) and network address translation (NAT) device" 34.Sh SYNOPSIS 35.Nm pfctl 36.Bk -words 37.Op Fl AdeghNnOqRrvz 38.Op Fl a Ar anchor Ns Op Ar :ruleset 39.Op Fl D Ar macro=value 40.Op Fl F Ar modifier 41.Op Fl f Ar file 42.Op Fl i Ar interface 43.Op Fl k Ar host 44.Op Fl p Ar device 45.Op Fl s Ar modifier 46.Op Fl T Ar command Op Ar address ... 47.Op Fl t Ar table 48.Op Fl x Ar level 49.Ek 50.Sh DESCRIPTION 51The 52.Nm 53utility communicates with the packet filter device using the 54ioctl interface described in 55.Xr pf 4 . 56It allows ruleset and parameter configuration and retrieval of status 57information from the packet filter. 58.Pp 59Packet filtering restricts the types of packets that pass through 60network interfaces entering or leaving the host based on filter 61rules as described in 62.Xr pf.conf 5 . 63The packet filter can also replace addresses and ports of packets. 64Replacing source addresses and ports of outgoing packets is called 65NAT (Network Address Translation) and is used to connect an internal 66network (usually reserved address space) to an external one (the 67Internet) by making all connections to external hosts appear to 68come from the gateway. 69Replacing destination addresses and ports of incoming packets 70is used to redirect connections to different hosts and/or ports. 71A combination of both translations, bidirectional NAT, is also 72supported. 73Translation rules are described in 74.Xr pf.conf 5 . 75.Pp 76When the variable pf is set to YES in 77.Xr rc.conf 8 , 78the rule file specified with the variable pf_rules 79is loaded automatically by the 80.Xr rc 8 81scripts and the packet filter is enabled. 82.Pp 83The packet filter does not itself forward packets between interfaces. 84Forwarding can be enabled by setting the 85.Xr sysctl 8 86variables 87.Em net.inet.ip.forwarding 88and/or 89.Em net.inet6.ip6.forwarding , 90to 1. 91Set them permanently in 92.Xr sysctl.conf 5 . 93.Pp 94The 95.Nm 96utility provides several commands. 97The options are as follows: 98.Bl -tag -width Ds 99.It Fl A 100Load only the queue rules present in the rule file. 101Other rules and options are ignored. 102.It Fl a Ar anchor Ns Op Ar :ruleset 103Apply flags 104.Fl f , 105.Fl F 106and 107.Fl s 108only to the rules in the specified 109.Ar anchor 110and optional named ruleset 111.Ar ruleset . 112In addition to the main ruleset, 113.Nm 114can load and manipulate additional rulesets by name. 115Named rulesets are attached at 116.Ar anchor 117points, which are also referenced by name. 118Evaluation of 119.Ar anchor 120rules from the main ruleset is described in 121.Xr pf.conf 5 . 122For example, to show all filter rules inside anchor 123.Li foo : 124.Bd -literal -offset indent 125# pfctl -a foo -s rules 126.Ed 127.Pp 128Private tables can also be put inside subrulesets, either by having table 129statements in the 130.Xr pf.conf 5 131file that is loaded in the anchor, or by using regular table commands as in: 132.Bd -literal -offset indent 133# pfctl -a foo:bar -t mytable -T add 1.2.3.4 5.6.7.8 134.Ed 135.Pp 136When a rule referring to a table is loaded in an anchor, the rule will use the 137private table if one is defined, and then fallback to the table defined in the 138main ruleset, if there is one. 139This is similar to C rules for variables. 140It is possible to create distinct tables with the same name in the global 141ruleset and in an anchor, but this is often bad design and a warning will be 142issued in that case. 143.It Fl D Ar macro=value 144Define 145.Ar macro 146to be set to 147.Ar value 148on the command line. 149Overrides the definition of 150.Ar macro 151in the ruleset. 152.It Fl d 153Disable the packet filter. 154.It Fl e 155Enable the packet filter. 156.It Fl F Ar modifier 157Flush the filter parameters specified by 158.Ar modifier 159(may be abbreviated): 160.Pp 161.Bl -tag -width xxxxxxxxxxxx -compact 162.It Fl F Ar nat 163Flush the NAT rules. 164.It Fl F Ar queue 165Flush the queue rules. 166.It Fl F Ar rules 167Flush the filter rules. 168.It Fl F Ar state 169Flush the state table (NAT and filter). 170.It Fl F Ar Sources 171Flush the source tracking table. 172.It Fl F Ar info 173Flush the filter information (statistics that are not bound to rules). 174.It Fl F Ar Tables 175Flush the tables. 176.It Fl F Ar osfp 177Flush the passive operating system fingerprints. 178.It Fl F Ar all 179Flush all of the above. 180.El 181.It Fl f Ar file 182Load the rules contained in 183.Ar file . 184This 185.Ar file 186may contain macros, tables, options, and normalization, queueing, 187translation, and filtering rules. 188With the exception of macros and tables, the statements must appear in that 189order. 190.It Fl g 191Include output helpful for debugging. 192.It Fl h 193Help. 194.It Fl i Ar interface 195Restrict the operation to the given 196.Ar interface . 197.It Fl k Ar host 198Kill all of the state entries originating from the specified 199.Ar host . 200A second 201.Fl k Ar host 202option may be specified, which will kill all the state entries 203from the first 204.Ar host 205to the second 206.Ar host . 207For example, to kill all of the state entries originating from 208.Li host : 209.Bd -literal -offset indent 210# pfctl -k host 211.Ed 212.Pp 213To kill all of the state entries from 214.Li host1 215to 216.Li host2 : 217.Bd -literal -offset indent 218# pfctl -k host1 -k host2 219.Ed 220.It Fl N 221Load only the NAT rules present in the rule file. 222Other rules and options are ignored. 223.It Fl n 224Do not actually load rules, just parse them. 225.It Fl O 226Load only the options present in the rule file. 227Other rules and options are ignored. 228.It Fl p Ar device 229Use the device file 230.Ar device 231instead of the default 232.Pa /dev/pf . 233.It Fl q 234Only print errors and warnings. 235.It Fl R 236Load only the filter rules present in the rule file. 237Other rules and options are ignored. 238.It Fl r 239Perform reverse DNS lookups on states when displaying them. 240.It Fl s Ar modifier 241Show the filter parameters specified by 242.Ar modifier 243(may be abbreviated): 244.Pp 245.Bl -tag -width xxxxxxxxxxxxx -compact 246.It Fl s Ar nat 247Show the currently loaded NAT rules. 248.It Fl s Ar queue 249Show the currently loaded queue rules. 250When used together with 251.Fl v , 252per-queue statistics are also shown. 253When used together with 254.Fl v v , 255.Nm 256will loop and show updated queue statistics every five seconds, including 257measured bandwidth and packets per second. 258.It Fl s Ar rules 259Show the currently loaded filter rules. 260When used together with 261.Fl v , 262the per-rule statistics (number of evaluations, 263packets and bytes) are also shown. 264Note that the 'skip step' optimization done automatically by the kernel 265will skip evaluation of rules where possible. 266Packets passed statefully are counted in the rule that created the state 267(even though the rule isn't evaluated more than once for the entire 268connection). 269.It Fl s Ar Anchors 270Show the currently loaded anchors. 271If 272.Fl a Ar anchor 273is specified as well, the named rulesets currently loaded in the specified 274anchor are shown instead. 275.It Fl s Ar state 276Show the contents of the state table. 277.It Fl s Ar Sources 278Show the contents of the source tracking table. 279.It Fl s Ar info 280Show filter information (statistics and counters). 281When used together with 282.Fl v , 283source tracking statistics are also shown. 284.It Fl s Ar labels 285Show per-rule statistics (label, evaluations, packets, bytes) of 286filter rules with labels, useful for accounting. 287.It Fl s Ar timeouts 288Show the current global timeouts. 289.It Fl s Ar memory 290Show the current pool memory hard limits. 291.It Fl s Ar Tables 292Show the list of tables. 293.It Fl s Ar osfp 294Show the list of operating system fingerprints. 295.It Fl s Ar Interfaces 296Show the list of interfaces and interface drivers available to PF. 297When used together with a double 298.Fl v , 299interface statistics are also shown. 300.Fl i 301can be used to select an interface or a group of interfaces. 302.It Fl s Ar all 303Show all of the above, except for the lists of interfaces and operating 304system fingerprints. 305.El 306.It Fl T Ar command Op Ar address ... 307Specify the 308.Ar command 309(may be abbreviated) to apply to the table. 310Commands include: 311.Pp 312.Bl -tag -width xxxxxxxxxxxx -compact 313.It Fl T Ar kill 314Kill a table. 315.It Fl T Ar flush 316Flush all addresses of a table. 317.It Fl T Ar add 318Add one or more addresses in a table. 319Automatically create a nonexisting table. 320.It Fl T Ar delete 321Delete one or more addresses from a table. 322.It Fl T Ar replace 323Replace the addresses of the table. 324Automatically create a nonexisting table. 325.It Fl T Ar show 326Show the content (addresses) of a table. 327.It Fl T Ar test 328Test if the given addresses match a table. 329.It Fl T Ar zero 330Clear all the statistics of a table. 331.It Fl T Ar load 332Load only the table definitions from 333.Xr pf.conf 5 . 334This is used in conjunction with the 335.Fl f 336flag, as in: 337.Bd -literal -offset indent 338# pfctl -Tl -f pf.conf 339.Ed 340.El 341.Pp 342For the 343.Ar add , 344.Ar delete , 345.Ar replace 346and 347.Ar test 348commands, the list of addresses can be specified either directly on the command 349line and/or in an unformatted text file, using the 350.Fl f 351flag. 352Comments starting with a "#" are allowed in the text file. 353With these commands, the 354.Fl v 355flag can also be used once or twice, in which case 356.Nm 357will print the 358detailed result of the operation for each individual address, prefixed by 359one of the following letters: 360.Pp 361.Bl -tag -width XXX -compact 362.It A 363The address/network has been added. 364.It C 365The address/network has been changed (negated). 366.It D 367The address/network has been deleted. 368.It M 369The address matches (test operation only). 370.It X 371The address/network is duplicated and therefore ignored. 372.It Y 373The address/network cannot be added/deleted due to conflicting "!" attribute. 374.It Z 375The address/network has been cleared (statistics). 376.El 377.Pp 378Each table maintains a set of counters that can be retrieved using the 379.Fl v 380flag of 381.Nm . 382For example, the following commands define a wide open firewall which will keep 383track of packets going to or coming from the 384.Ox 385ftp server. 386The following commands configure the firewall and send 10 pings to the ftp 387server: 388.Bd -literal -offset indent 389# printf "table <test> { ftp.openbsd.org }\en \e 390 pass out to <test> keep state\en" | pfctl -f- 391# ping -qc10 ftp.openbsd.org 392.Ed 393.Pp 394We can now use the table 395.Ar show 396command to output, for each address and packet direction, the number of packets 397and bytes that are being passed or blocked by rules referencing the table. 398The time at which the current accounting started is also shown with the 399.Ar Cleared 400line. 401.Bd -literal -offset indent 402# pfctl -t test -vTshow 403 129.128.5.191 404 Cleared: Thu Feb 13 18:55:18 2003 405 In/Block: [ Packets: 0 Bytes: 0 ] 406 In/Pass: [ Packets: 10 Bytes: 840 ] 407 Out/Block: [ Packets: 0 Bytes: 0 ] 408 Out/Pass: [ Packets: 10 Bytes: 840 ] 409.Ed 410.Pp 411Similarly, it is possible to view global information about the tables 412by using the 413.Fl v 414modifier twice and the 415.Ar show Tables 416command. 417This will display the number of addresses on each table, 418the number of rules which reference the table, and the global 419packet statistics for the whole table: 420.Bd -literal -offset indent 421# pfctl -vvsTables 422--a-r- test 423 Addresses: 1 424 Cleared: Thu Feb 13 18:55:18 2003 425 References: [ Anchors: 0 Rules: 1 ] 426 Evaluations: [ NoMatch: 3496 Match: 1 ] 427 In/Block: [ Packets: 0 Bytes: 0 ] 428 In/Pass: [ Packets: 10 Bytes: 840 ] 429 In/XPass: [ Packets: 0 Bytes: 0 ] 430 Out/Block: [ Packets: 0 Bytes: 0 ] 431 Out/Pass: [ Packets: 10 Bytes: 840 ] 432 Out/XPass: [ Packets: 0 Bytes: 0 ] 433.Ed 434.Pp 435As we can see here, only one packet \- the initial ping request \- matched the 436table; but all packets passing as the result of the state are correctly 437accounted for. 438Reloading the table(s) or ruleset will not affect packet accounting in any way. 439The two 440.Ar XPass 441counters are incremented instead of the 442.Ar Pass 443counters when a "stateful" packet is passed but doesn't match the table 444anymore. 445This will happen in our example if someone flushes the table while the ping 446command is running. 447.Pp 448When used with a single 449.Fl v , 450.Nm 451will only display the first line containing the table flags and name. 452The flags are defined as follows: 453.Pp 454.Bl -tag -width XXX -compact 455.It c 456For constant tables, which cannot be altered outside 457.Xr pf.conf 5 . 458.It p 459For persistent tables, which don't get automatically flushed when no rules 460refer to them. 461.It a 462For tables which are part of the 463.Ar active 464tableset. 465Tables without this flag do not really exist, cannot contain addresses, and are 466only listed if the 467.Fl g 468flag is given. 469.It i 470For tables which are part of the 471.Ar inactive 472tableset. 473This flag can only be witnessed briefly during the loading of 474.Xr pf.conf 5 . 475.It r 476For tables which are referenced (used) by rules. 477.It h 478This flag is set when a table in the main ruleset is hidden by one or more 479tables of the same name in sub-rulesets (anchors). 480.El 481.It Fl t Ar table 482Specify the name of the table. 483.It Fl v 484Produce more verbose output. 485A second use of 486.Fl v 487will produce even more verbose output including ruleset warnings. 488See previous section for its effect on table commands. 489.It Fl x Ar level 490Set the debug 491.Ar level 492(may be abbreviated) to one of the following: 493.Pp 494.Bl -tag -width xxxxxxxxxxxx -compact 495.It Fl x Ar none 496Don't generate debug messages. 497.It Fl x Ar urgent 498Generate debug messages only for serious errors. 499.It Fl x Ar misc 500Generate debug messages for various errors. 501.It Fl x Ar loud 502Generate debug messages for common conditions. 503.El 504.It Fl z 505Clear per-rule statistics. 506.El 507.Sh FILES 508.Bl -tag -width "/etc/pf.conf" -compact 509.It Pa /etc/pf.conf 510Packet filter rules file. 511.El 512.Sh SEE ALSO 513.Xr pf 4 , 514.Xr pf.conf 5 , 515.Xr pf.os 5 , 516.Xr sysctl.conf 5 , 517.Xr ftp-proxy 8 , 518.Xr rc 8 , 519.Xr rc.conf 8 , 520.Xr sysctl 8 521.Sh HISTORY 522The 523.Nm 524program and the 525.Xr pf 4 526filter mechanism first appeared in 527.Ox 3.0 . 528