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