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