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 ... 55.Oc 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.It Fl m 319Merge in explicitly given options without resetting those 320which are omitted. 321Allows single options to be modified without disturbing the others: 322.Bd -literal -offset indent 323# echo "set loginterface fxp0" | pfctl -mf - 324.Ed 325.It Fl N 326Load only the NAT rules present in the rule file. 327Other rules and options are ignored. 328.It Fl n 329Do not actually load rules, just parse them. 330.It Fl O 331Load only the options present in the rule file. 332Other rules and options are ignored. 333.It Fl o Ar level 334Control the ruleset optimizer, overriding any rule file settings. 335.Pp 336.Bl -tag -width xxxxxxxxxxxx -compact 337.It Fl o Cm none 338Disable the ruleset optimizer. 339.It Fl o Cm basic 340Enable basic ruleset optimizations. 341This is the default behaviour. 342.It Fl o Cm profile 343Enable basic ruleset optimizations with profiling. 344.El 345For further information on the ruleset optimizer, see 346.Xr pf.conf 5 . 347.It Fl p Ar device 348Use the device file 349.Ar device 350instead of the default 351.Pa /dev/pf . 352.It Fl q 353Only print errors and warnings. 354.It Fl R 355Load only the filter rules present in the rule file. 356Other rules and options are ignored. 357.It Fl r 358Perform reverse DNS lookups on states when displaying them. 359.It Fl s Ar modifier 360Show the filter parameters specified by 361.Ar modifier 362(may be abbreviated): 363.Pp 364.Bl -tag -width xxxxxxxxxxxxx -compact 365.It Fl s Cm nat 366Show the currently loaded NAT rules. 367.It Fl s Cm queue 368Show the currently loaded queue rules. 369When used together with 370.Fl v , 371per-queue statistics are also shown. 372When used together with 373.Fl v v , 374.Nm 375will loop and show updated queue statistics every five seconds, including 376measured bandwidth and packets per second. 377.It Fl s Cm rules 378Show the currently loaded filter rules. 379When used together with 380.Fl v , 381the per-rule statistics (number of evaluations, 382packets and bytes) are also shown. 383Note that the 384.Dq skip step 385optimization done automatically by the kernel 386will skip evaluation of rules where possible. 387Packets passed statefully are counted in the rule that created the state 388(even though the rule isn't evaluated more than once for the entire 389connection). 390.It Fl s Cm Anchors 391Show the currently loaded anchors directly attached to the main ruleset. 392If 393.Fl a Ar anchor 394is specified as well, the anchors loaded directly below the given 395.Ar anchor 396are shown instead. 397If 398.Fl v 399is specified, all anchors attached under the target anchor will be 400displayed recursively. 401.It Fl s Cm states 402Show the contents of the state table. 403.It Fl s Cm Sources 404Show the contents of the source tracking table. 405.It Fl s Cm info 406Show filter information (statistics and counters). 407When used together with 408.Fl v , 409source tracking statistics are also shown. 410.It Fl s Cm labels 411Show per-rule statistics (label, evaluations, packets total, bytes total, 412packets in, bytes in, packets out, bytes out, state creations) of 413filter rules with labels, useful for accounting. 414.It Fl s Cm timeouts 415Show the current global timeouts. 416.It Fl s Cm memory 417Show the current pool memory hard limits. 418.It Fl s Cm Tables 419Show the list of tables. 420.It Fl s Cm osfp 421Show the list of operating system fingerprints. 422.It Fl s Cm Interfaces 423Show the list of interfaces and interface drivers available to PF. 424When used together with 425.Fl v , 426it additionally lists which interfaces have skip rules activated. 427When used together with 428.Fl vv , 429interface statistics are also shown. 430.Fl i 431can be used to select an interface or a group of interfaces. 432.It Fl s Cm all 433Show all of the above, except for the lists of interfaces and operating 434system fingerprints. 435.El 436.It Fl T Ar command Op Ar address ... 437Specify the 438.Ar command 439(may be abbreviated) to apply to the table. 440Commands include: 441.Pp 442.Bl -tag -width xxxxxxxxxxxx -compact 443.It Fl T Cm kill 444Kill a table. 445.It Fl T Cm flush 446Flush all addresses of a table. 447.It Fl T Cm add 448Add one or more addresses in a table. 449Automatically create a nonexisting table. 450.It Fl T Cm delete 451Delete one or more addresses from a table. 452.It Fl T Cm expire Ar number 453Delete addresses which had their statistics cleared more than 454.Ar number 455seconds ago. 456For entries which have never had their statistics cleared, 457.Ar number 458refers to the time they were added to the table. 459.It Fl T Cm replace 460Replace the addresses of the table. 461Automatically create a nonexisting table. 462.It Fl T Cm show 463Show the content (addresses) of a table. 464.It Fl T Cm test 465Test if the given addresses match a table. 466.It Fl T Cm zero 467Clear all the statistics of a table. 468.It Fl T Cm load 469Load only the table definitions from 470.Xr pf.conf 5 . 471This is used in conjunction with the 472.Fl f 473flag, as in: 474.Bd -literal -offset indent 475# pfctl -Tl -f pf.conf 476.Ed 477.El 478.Pp 479For the 480.Cm add , 481.Cm delete , 482.Cm replace , 483and 484.Cm test 485commands, the list of addresses can be specified either directly on the command 486line and/or in an unformatted text file, using the 487.Fl f 488flag. 489Comments starting with a 490.Sq # 491are allowed in the text file. 492With these commands, the 493.Fl v 494flag can also be used once or twice, in which case 495.Nm 496will print the 497detailed result of the operation for each individual address, prefixed by 498one of the following letters: 499.Pp 500.Bl -tag -width XXX -compact 501.It A 502The address/network has been added. 503.It C 504The address/network has been changed (negated). 505.It D 506The address/network has been deleted. 507.It M 508The address matches 509.Po 510.Cm test 511operation only 512.Pc . 513.It X 514The address/network is duplicated and therefore ignored. 515.It Y 516The address/network cannot be added/deleted due to conflicting 517.Sq \&! 518attributes. 519.It Z 520The address/network has been cleared (statistics). 521.El 522.Pp 523Each table can maintain a set of counters that can be retrieved using the 524.Fl v 525flag of 526.Nm . 527For example, the following commands define a wide open firewall which will keep 528track of packets going to or coming from the 529.Ox 530FTP server. 531The following commands configure the firewall and send 10 pings to the FTP 532server: 533.Bd -literal -offset indent 534# printf "table <test> counters { ftp.openbsd.org }\en \e 535 pass out to <test>\en" | pfctl -f- 536# ping -qc10 ftp.openbsd.org 537.Ed 538.Pp 539We can now use the table 540.Cm show 541command to output, for each address and packet direction, the number of packets 542and bytes that are being passed or blocked by rules referencing the table. 543The time at which the current accounting started is also shown with the 544.Dq Cleared 545line. 546.Bd -literal -offset indent 547# pfctl -t test -vTshow 548 129.128.5.191 549 Cleared: Thu Feb 13 18:55:18 2003 550 In/Block: [ Packets: 0 Bytes: 0 ] 551 In/Pass: [ Packets: 10 Bytes: 840 ] 552 Out/Block: [ Packets: 0 Bytes: 0 ] 553 Out/Pass: [ Packets: 10 Bytes: 840 ] 554.Ed 555.Pp 556Similarly, it is possible to view global information about the tables 557by using the 558.Fl v 559modifier twice and the 560.Fl s 561.Cm Tables 562command. 563This will display the number of addresses on each table, 564the number of rules which reference the table, and the global 565packet statistics for the whole table: 566.Bd -literal -offset indent 567# pfctl -vvsTables 568--a-r-C test 569 Addresses: 1 570 Cleared: Thu Feb 13 18:55:18 2003 571 References: [ Anchors: 0 Rules: 1 ] 572 Evaluations: [ NoMatch: 3496 Match: 1 ] 573 In/Block: [ Packets: 0 Bytes: 0 ] 574 In/Pass: [ Packets: 10 Bytes: 840 ] 575 In/XPass: [ Packets: 0 Bytes: 0 ] 576 Out/Block: [ Packets: 0 Bytes: 0 ] 577 Out/Pass: [ Packets: 10 Bytes: 840 ] 578 Out/XPass: [ Packets: 0 Bytes: 0 ] 579.Ed 580.Pp 581As we can see here, only one packet \- the initial ping request \- matched the 582table, but all packets passing as the result of the state are correctly 583accounted for. 584Reloading the table(s) or ruleset will not affect packet accounting in any way. 585The two 586.Dq XPass 587counters are incremented instead of the 588.Dq Pass 589counters when a 590.Dq stateful 591packet is passed but doesn't match the table anymore. 592This will happen in our example if someone flushes the table while the 593.Xr ping 8 594command is running. 595.Pp 596When used with a single 597.Fl v , 598.Nm 599will only display the first line containing the table flags and name. 600The flags are defined as follows: 601.Pp 602.Bl -tag -width XXX -compact 603.It c 604For constant tables, which cannot be altered outside 605.Xr pf.conf 5 . 606.It p 607For persistent tables, which don't get automatically killed when no rules 608refer to them. 609.It a 610For tables which are part of the 611.Em active 612tableset. 613Tables without this flag do not really exist, cannot contain addresses, and are 614only listed if the 615.Fl g 616flag is given. 617.It i 618For tables which are part of the 619.Em inactive 620tableset. 621This flag can only be witnessed briefly during the loading of 622.Xr pf.conf 5 . 623.It r 624For tables which are referenced (used) by rules. 625.It h 626This flag is set when a table in the main ruleset is hidden by one or more 627tables of the same name from anchors attached below it. 628.It C 629This flag is set when per-address counters are enabled on the table. 630.El 631.It Fl t Ar table 632Specify the name of the table. 633.It Fl v 634Produce more verbose output. 635A second use of 636.Fl v 637will produce even more verbose output including ruleset warnings. 638See the previous section for its effect on table commands. 639.It Fl x Ar level 640Set the debug 641.Ar level 642(may be abbreviated) to one of the following: 643.Pp 644.Bl -tag -width xxxxxxxxxxxx -compact 645.It Fl x Cm none 646Don't generate debug messages. 647.It Fl x Cm urgent 648Generate debug messages only for serious errors. 649.It Fl x Cm misc 650Generate debug messages for various errors. 651.It Fl x Cm loud 652Generate debug messages for common conditions. 653.El 654.It Fl z 655Clear per-rule statistics. 656.El 657.Sh FILES 658.Bl -tag -width "/etc/pf.conf" -compact 659.It Pa /etc/pf.conf 660Packet filter rules file. 661.It Pa /etc/pf.os 662Passive operating system fingerprint database. 663.El 664.Sh SEE ALSO 665.Xr pf 4 , 666.Xr pf.conf 5 , 667.Xr pf.os 5 , 668.Xr rc.conf 5 , 669.Xr sysctl.conf 5 , 670.Xr authpf 8 , 671.Xr ftp-proxy 8 , 672.Xr rc 8 , 673.Xr sysctl 8 674.Sh HISTORY 675The 676.Nm 677program and the 678.Xr pf 4 679filter mechanism first appeared in 680.Ox 3.0 . 681