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