1.\" $OpenBSD: pfctl.8,v 1.183 2022/11/18 18:11:10 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 18 2022 $ 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 xxxxxxxxxxxx -compact 195.It Fl F Cm rules 196Flush the filter rules. 197.It Fl F Cm states 198Flush the state table (NAT and filter). 199.It Fl F Cm Sources 200Flush the source tracking table. 201.It Fl F Cm info 202Flush the filter information (statistics that are not bound to rules). 203.It Fl F Cm Tables 204Flush the tables. 205.It Fl F Cm osfp 206Flush the passive operating system fingerprints. 207.It Fl F 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 Fl F 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 xxxxxxxxxxxx -compact 320.It Fl o Cm none 321Disable the ruleset optimizer. 322.It Fl o Cm basic 323Enable basic ruleset optimizations. 324This is the default behaviour. 325.It Fl o 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.It Fl s Ar modifier Op Fl R Ar id 352Show the filter parameters specified by 353.Ar modifier 354(may be abbreviated): 355.Pp 356.Bl -tag -width xxxxxxxxxxxxxx -compact 357.It Fl s Cm queue 358Show the currently loaded queue definitions. 359When used together with 360.Fl v , 361per-queue statistics are also shown. 362When used together with 363.Fl v v , 364.Nm 365will loop and show updated queue statistics every five seconds, including 366measured bandwidth and packets per second. 367.It Fl s Cm rules 368Show the currently loaded filter rules. 369If 370.Fl R Ar id 371is specified as well, 372only the rule with the specified numeric ID is shown. 373When used together with 374.Fl v , 375the per-rule statistics (number of evaluations, 376packets and bytes) are also shown. 377When used together with 378.Fl g 379or 380.Fl vv , 381expired rules 382.Pq marked as Dq # expired 383are 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. 404If 405.Fl R Ar id 406is specified as well, 407only states created by the rule with the specified numeric ID are shown. 408.It Fl s Cm Sources 409Show the contents of the source tracking table. 410.It Fl s Cm info 411Show filter information (statistics and counters). 412When used together with 413.Fl v , 414source tracking statistics, the firewall's 32-bit hostid number and the 415main ruleset's MD5 checksum for use with 416.Xr pfsync 4 417are also shown. 418.It Fl s Cm labels 419Show per-rule statistics (label, evaluations, packets total, bytes total, 420packets in, bytes in, packets out, bytes out, state creations) of 421filter rules with labels, useful for accounting. 422If 423.Fl R Ar id 424is specified as well, 425only the statistics for the rule with the specified numeric ID are shown. 426.It Fl s Cm timeouts 427Show the current global timeouts. 428.It Fl s Cm memory 429Show the current pool memory hard limits. 430.It Fl s Cm Tables 431Show the list of tables. 432.It Fl s Cm osfp 433Show the list of operating system fingerprints. 434.It Fl s Cm Interfaces 435Show the list of interfaces and interface groups available to PF. 436When used together with 437.Fl v , 438it additionally lists which interfaces have skip rules activated. 439When used together with 440.Fl vv , 441interface statistics are also shown. 442.Fl i 443can be used to select an interface or a group of interfaces. 444.It Fl s Cm all 445Show all of the above, except for the lists of interfaces and operating 446system fingerprints. 447.El 448.Pp 449Counters shown with 450.Fl s Cm info 451are: 452.Pp 453.Bl -tag -width xxxxxxxxxxxxxx -compact 454.It match 455explicit rule match 456.It bad-offset 457currently unused 458.It fragment 459invalid fragments dropped 460.It short 461short packets dropped 462.It normalize 463dropped by normalizer: illegal packets 464.It memory 465memory could not be allocated 466.It bad-timestamp 467bad TCP timestamp; RFC 1323 468.It congestion 469network interface queue congested 470.It ip-option 471bad IP/IPv6 options 472.It proto-cksum 473invalid protocol checksum 474.It state-mismatch 475packet was associated with a state entry, but sequence numbers did not match 476.It state-insert 477state insertion failure 478.It state-limit 479configured state limit was reached 480.It src-limit 481source node/connection limit 482.It synproxy 483dropped by synproxy 484.It translate 485no free ports in translation port range 486.It no-route 487dropped by no-route 488.El 489.It Fl t Ar table Fl T Ar command Op Ar address ... 490Specify the 491.Ar command 492(may be abbreviated) to apply to 493.Ar table . 494Commands include: 495.Pp 496.Bl -tag -width "-T expire number" -compact 497.It Fl T Cm add 498Add one or more addresses to a table. 499Automatically create a persistent table if it does not exist. 500.It Fl T Cm delete 501Delete one or more addresses from a table. 502.It Fl T Cm expire Ar number 503Delete addresses which had their statistics cleared more than 504.Ar number 505seconds ago. 506For entries which have never had their statistics cleared, 507.Ar number 508refers to the time they were added to the table. 509.It Fl T Cm flush 510Flush all addresses in a table. 511.It Fl T Cm kill 512Kill a table. 513.It Fl T Cm replace 514Replace the addresses of the table. 515Automatically create a persistent table if it does not exist. 516.It Fl T Cm show 517Show the content (addresses) of a table. 518.It Fl T Cm test 519Test if the given addresses match a table. 520.It Fl T Cm zero 521Clear all the statistics of a table. 522.El 523.Pp 524For the 525.Cm add , 526.Cm delete , 527.Cm replace , 528and 529.Cm test 530commands, the list of addresses can be specified either directly on the command 531line and/or in an unformatted text file, using the 532.Fl f 533flag. 534Comments starting with a 535.Sq # 536are allowed in the text file. 537With these commands, the 538.Fl v 539flag can also be used once or twice, in which case 540.Nm 541will print the 542detailed result of the operation for each individual address, prefixed by 543one of the following letters: 544.Pp 545.Bl -tag -width XXX -compact 546.It A 547The address/network has been added. 548.It C 549The address/network has been changed (negated). 550.It D 551The address/network has been deleted. 552.It M 553The address matches 554.Po 555.Cm test 556operation only 557.Pc . 558.It X 559The address/network is duplicated and therefore ignored. 560.It Y 561The address/network cannot be added/deleted due to conflicting 562.Sq \&! 563attributes. 564.It Z 565The address/network has been cleared (statistics). 566.El 567.Pp 568Each table can maintain a set of counters that can be retrieved using the 569.Fl v 570flag of 571.Nm . 572For example, the following commands define a wide open firewall which will keep 573track of packets going to or coming from the 574.Ox 575FTP server. 576The following commands configure the firewall and send 10 pings to the FTP 577server: 578.Bd -literal -offset indent 579# printf "table <test> counters { ftp.openbsd.org }\en \e 580 pass out to <test>\en" | pfctl -f- 581# ping -qc10 ftp.openbsd.org 582.Ed 583.Pp 584We can now use the table 585.Cm show 586command to output, for each address and packet direction, the number of packets 587and bytes that are being passed, matched or blocked by rules referencing the 588table. 589Note that the match counters are incremented for every match rule in which 590they are referenced, meaning that a single packet may be counted multiple times. 591The time at which the current accounting started is also shown with the 592.Dq Cleared 593line. 594.Bd -literal -offset indent 595# pfctl -t test -vTshow 596 198.51.100.81 597 Cleared: Fri Jun 28 11:17:37 2013 598 In/Block: [ Packets: 0 Bytes: 0 ] 599 In/Match [ Packets: 54 Bytes: 10028 ] 600 In/Pass: [ Packets: 5 Bytes: 1949 ] 601 Out/Block: [ Packets: 0 Bytes: 0 ] 602 Out/Match [ Packets: 65 Bytes: 12684 ] 603 Out/Pass: [ Packets: 6 Bytes: 389 ] 604.Ed 605.Pp 606Similarly, it is possible to view global information about the tables 607by using the 608.Fl v 609modifier twice and the 610.Fl s 611.Cm Tables 612command. 613This will display the number of addresses on each table, 614the number of rules which reference the table, and the global 615packet statistics for the whole table: 616.Bd -literal -offset indent 617# pfctl -vvsTables 618--a-r-C test 619 Addresses: 1 620 Cleared: Fri Jun 28 11:17:37 2013 621 References: [ Anchors: 0 Rules: 4 ] 622 Evaluations: [ NoMatch: 35 Match: 8 ] 623 In/Block: [ Packets: 0 Bytes: 0 ] 624 In/Match: [ Packets: 54 Bytes: 10028 ] 625 In/Pass: [ Packets: 5 Bytes: 1949 ] 626 In/XPass: [ Packets: 0 Bytes: 0 ] 627 Out/Block: [ Packets: 0 Bytes: 0 ] 628 Out/Match: [ Packets: 65 Bytes: 12684 ] 629 Out/Pass: [ Packets: 6 Bytes: 389 ] 630 Out/XPass: [ Packets: 0 Bytes: 0 ] 631.Ed 632.Pp 633Only packets creating state are matched in the Evaluations line, 634but all packets passing as a result of the state are correctly accounted for. 635Reloading the table(s) or ruleset will not affect packet accounting in any way. 636The two 637.Dq XPass 638counters are incremented instead of the 639.Dq Pass 640counters when a 641.Dq stateful 642packet is passed but doesn't match the table anymore. 643This will happen in our example if someone flushes the table while the 644.Xr ping 8 645command is running. 646.Pp 647When used with a single 648.Fl v , 649.Nm 650will only display the first line containing the table flags and name. 651The flags are defined as follows: 652.Pp 653.Bl -tag -width XXX -compact 654.It c 655For constant tables, which cannot be altered outside 656.Xr pf.conf 5 . 657.It p 658For persistent tables, which don't get automatically killed when no rules 659refer to them. 660.It a 661For tables which are part of the 662.Em active 663tableset. 664Tables without this flag do not really exist, cannot contain addresses, and are 665only listed if the 666.Fl g 667flag is given. 668.It i 669For tables which are part of the 670.Em inactive 671tableset. 672This flag can only be witnessed briefly during the loading of 673.Xr pf.conf 5 . 674.It r 675For tables which are referenced (used) by rules. 676.It h 677This flag is set when a table in the main ruleset is hidden by one or more 678tables of the same name from anchors attached below it. 679.It C 680This flag is set when per-address counters are enabled on the table. 681.El 682.It Fl V Ar rdomain 683Select the routing domain to be used to kill states by host or by label. 684The rdomain of a state is displayed in parentheses before the host by 685.Fl s Cm states . 686.It Fl v 687Produce more verbose output. 688A second use of 689.Fl v 690will produce even more verbose output including ruleset warnings. 691See the previous section for its effect on table commands. 692.It Fl x Ar level 693Set the debug 694.Ar level , 695which limits the severity of log messages printed by 696.Xr pf 4 . 697This should be a keyword from the following ordered list 698(highest to lowest): 699.Cm emerg , 700.Cm alert , 701.Cm crit , 702.Cm err , 703.Cm warning , 704.Cm notice , 705.Cm info , 706and 707.Cm debug . 708These keywords correspond to the similar (LOG_) values specified to the 709.Xr syslog 3 710library routine, 711and may be abbreviated on the command line. 712.It Fl z 713Clear per-rule statistics. 714.El 715.Sh FILES 716.Bl -tag -width "/etc/pf.conf" -compact 717.It Pa /etc/pf.conf 718Packet filter rules file. 719.It Pa /etc/pf.os 720Passive operating system fingerprint database. 721.El 722.Sh SEE ALSO 723.Xr pf 4 , 724.Xr pf.conf 5 , 725.Xr pf.os 5 , 726.Xr sysctl.conf 5 , 727.Xr authpf 8 , 728.Xr ftp-proxy 8 , 729.Xr rc 8 , 730.Xr rc.conf 8 , 731.Xr sysctl 8 732.Sh HISTORY 733The 734.Nm 735program and the 736.Xr pf 4 737filter mechanism first appeared in 738.Ox 3.0 . 739