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