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