1.\" $OpenBSD: pfctl.8,v 1.138 2008/06/10 20:55:02 mcbride 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 May 9, 2025 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 AdeghMmNnOPqRrvz 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 | gateway | nat 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_enable 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 107At least one option must be specified. 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 ethernet 212Flush the Ethernet filter 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 | key | gateway | nat 258.Xc 259Kill all of the state entries matching the specified 260.Ar host , 261.Ar network , 262.Ar label , 263.Ar id , 264.Ar key , 265.Ar gateway, 266or 267.Ar nat. 268.Pp 269For example, to kill all of the state entries originating from 270.Dq host : 271.Pp 272.Dl # pfctl -k host 273.Pp 274A second 275.Fl k Ar host 276or 277.Fl k Ar network 278option may be specified, which will kill all the state entries 279from the first host/network to the second. 280To kill all of the state entries from 281.Dq host1 282to 283.Dq host2 : 284.Pp 285.Dl # pfctl -k host1 -k host2 286.Pp 287To kill all states originating from 192.168.1.0/24 to 172.16.0.0/16: 288.Pp 289.Dl # pfctl -k 192.168.1.0/24 -k 172.16.0.0/16 290.Pp 291A network prefix length of 0 can be used as a wildcard. 292To kill all states with the target 293.Dq host2 : 294.Pp 295.Dl # pfctl -k 0.0.0.0/0 -k host2 296.Pp 297It is also possible to kill states by rule label, state key or state ID. 298In this mode the first 299.Fl k 300argument is used to specify the type 301of the second argument. 302The following command would kill all states that have been created 303from rules carrying the label 304.Dq foobar : 305.Pp 306.Dl # pfctl -k label -k foobar 307.Pp 308To kill one specific state by its key 309(protocol, host1, port1, direction, host2 and port2 in the same format 310of pfctl -s state), 311use the 312.Ar key 313modifier and as a second argument the state key. 314To kill a state whose protocol is TCP and originating from 31510.0.0.101:32123 to 10.0.0.1:80 use: 316.Pp 317.Dl # pfctl -k key -k 'tcp 10.0.0.1:80 <- 10.0.0.101:32123' 318.Pp 319To kill one specific state by its unique state ID 320(as shown by pfctl -s state -vv), 321use the 322.Ar id 323modifier and as a second argument the state ID and optional creator ID. 324To kill a state with ID 4823e84500000003 use: 325.Pp 326.Dl # pfctl -k id -k 4823e84500000003 327.Pp 328To kill a state with ID 4823e84500000018 created from a backup 329firewall with hostid 00000002 use: 330.Pp 331.Dl # pfctl -k id -k 4823e84500000018/2 332.Pp 333It is also possible to kill states created from a rule with the route-to/reply-to 334parameter set to route the connection through a particular gateway. 335Note that rules routing via the default routing table (not via a route-to 336rule) will have their rt_addr set as 0.0.0.0 or ::. 337To kill all states using a gateway of 192.168.0.1 use: 338.Pp 339.Dl # pfctl -k gateway -k 192.168.0.1 340.Pp 341A network prefix length can also be specified. 342To kill all states using a gateway in 192.168.0.0/24: 343.Pp 344.Dl # pfctl -k gateway -k 192.168.0.0/24 345.Pp 346States can also be killed based on their pre-NAT address: 347.Pp 348.Dl # pfctl -k nat -k 192.168.0.1 349.Pp 350.It Fl M 351Kill matching states in the opposite direction (on other interfaces) when 352killing states. 353This applies to states killed using the -k option and also will apply to the 354flush command when flushing states. 355This is useful when an interface is specified when flushing states. 356Example: 357.Pp 358.Dl # pfctl -M -i interface -Fs 359.Pp 360.It Fl m 361Merge in explicitly given options without resetting those 362which are omitted. 363Allows single options to be modified without disturbing the others: 364.Bd -literal -offset indent 365# echo "set loginterface fxp0" | pfctl -mf - 366.Ed 367.It Fl N 368Load only the NAT rules present in the rule file. 369Other rules and options are ignored. 370.It Fl n 371Do not actually load rules, just parse them. 372.It Fl O 373Load only the options present in the rule file. 374Other rules and options are ignored. 375.It Fl o Ar level 376Control the ruleset optimizer, overriding any rule file settings. 377.Pp 378.Bl -tag -width xxxxxxxxxxxx -compact 379.It Fl o Cm none 380Disable the ruleset optimizer. 381.It Fl o Cm basic 382Enable basic ruleset optimizations. 383This is the default behaviour. 384.It Fl o Cm profile 385Enable basic ruleset optimizations with profiling. 386.El 387For further information on the ruleset optimizer, see 388.Xr pf.conf 5 . 389.It Fl P 390Do not perform service name lookup for port specific rules, 391instead display the ports numerically. 392.It Fl p Ar device 393Use the device file 394.Ar device 395instead of the default 396.Pa /dev/pf . 397.It Fl q 398Only print errors and warnings. 399.It Fl R 400Load only the filter rules present in the rule file. 401Other rules and options are ignored. 402.It Fl r 403Perform reverse DNS lookups on states when displaying them. 404.It Fl s Ar modifier 405Show the filter parameters specified by 406.Ar modifier 407(may be abbreviated): 408.Pp 409.Bl -tag -width xxxxxxxxxxxxx -compact 410.It Fl s Cm nat 411Show the currently loaded NAT rules. 412.It Fl s Cm queue 413Show the currently loaded queue rules. 414When used together with 415.Fl v , 416per-queue statistics are also shown. 417When used together with 418.Fl v v , 419.Nm 420will loop and show updated queue statistics every five seconds, including 421measured bandwidth and packets per second. 422.It Fl s Cm ether 423Show the currently loaded Ethernet rules. 424When used together with 425.Fl v , 426the per-rule statistics (number of evaluations, 427packets, and bytes) are also shown. 428.It Fl s Cm rules 429Show the currently loaded filter rules. 430When used together with 431.Fl v , 432the per-rule statistics (number of evaluations, 433packets, and bytes) are also shown. 434Note that the 435.Dq skip step 436optimization done automatically by the kernel 437will skip evaluation of rules where possible. 438Packets passed statefully are counted in the rule that created the state 439(even though the rule is not evaluated more than once for the entire 440connection). 441.It Fl s Cm Anchors 442Show the currently loaded anchors directly attached to the main ruleset. 443If 444.Fl a Ar anchor 445is specified as well, the anchors loaded directly below the given 446.Ar anchor 447are shown instead. 448If 449.Fl v 450is specified, all anchors attached under the target anchor will be 451displayed recursively. 452.It Fl s Cm states 453Show the contents of the state table. 454.It Fl s Cm Sources 455Show the contents of the source tracking table. 456.It Fl s Cm info 457Show filter information (statistics and counters). 458When used together with 459.Fl v , 460source tracking statistics are also shown. 461.It Fl s Cm Running 462Show the running status and provide a non-zero exit status when disabled. 463.It Fl s Cm labels 464Show per-rule statistics (label, evaluations, packets total, bytes total, 465packets in, bytes in, packets out, bytes out, state creations) of 466filter rules with labels, useful for accounting. 467.It Fl s Cm timeouts 468Show the current global timeouts. 469.It Fl s Cm memory 470Show the current pool memory hard limits. 471.It Fl s Cm Tables 472Show the list of tables. 473.It Fl s Cm osfp 474Show the list of operating system fingerprints. 475.It Fl s Cm Interfaces 476Show the list of interfaces and interface drivers available to PF. 477When used together with 478.Fl v , 479it additionally lists which interfaces have skip rules activated. 480When used together with 481.Fl vv , 482interface statistics are also shown. 483.Fl i 484can be used to select an interface or a group of interfaces. 485.It Fl s Cm all 486Show all of the above, except for the lists of interfaces and operating 487system fingerprints. 488.El 489.Pp 490Counters shown with 491.Fl s Cm info 492are: 493.Pp 494.Bl -tag -width xxxxxxxxxxxxxx -compact 495.It match 496explicit rule match 497.It bad-offset 498currently unused 499.It fragment 500invalid fragments dropped 501.It short 502short packets dropped 503.It normalize 504dropped by normalizer: illegal packets 505.It memory 506memory could not be allocated 507.It bad-timestamp 508bad TCP timestamp; RFC 1323 509.It congestion 510network interface queue congested 511.It ip-option 512bad IP/IPv6 options 513.It proto-cksum 514invalid protocol checksum 515.It state-mismatch 516packet was associated with a state entry, but sequence numbers did not match 517.It state-insert 518state insertion failure 519.It state-limit 520configured state limit was reached 521.It src-limit 522source node/connection limit 523.It synproxy 524dropped by synproxy 525.It map-failed 526address mapping failed 527.It translate 528no free ports in translation port range 529.El 530.It Fl T Ar command Op Ar address ... 531Specify the 532.Ar command 533(may be abbreviated) to apply to the table. 534Commands include: 535.Pp 536.Bl -tag -width xxxxxxxxxxxx -compact 537.It Fl T Cm kill 538Kill a table. 539.It Fl T Cm flush 540Flush all addresses of a table. 541.It Fl T Cm add 542Add one or more addresses in a table. 543Automatically create a nonexisting table. 544.It Fl T Cm delete 545Delete one or more addresses from a table. 546.It Fl T Cm expire Ar number 547Delete addresses which had their statistics cleared more than 548.Ar number 549seconds ago. 550For entries which have never had their statistics cleared, 551.Ar number 552refers to the time they were added to the table. 553.It Fl T Cm replace 554Replace the addresses of the table. 555Automatically create a nonexisting table. 556.It Fl T Cm show 557Show the content (addresses) of a table. 558.It Fl T Cm test 559Test if the given addresses match a table. 560.It Fl T Cm zero Op Ar address ... 561Clear all the statistics of a table, or only for specified addresses. 562.It Fl T Cm reset 563Clear statistics only for addresses with non-zero statistics. Addresses 564with counter values at zero and their 565.Dq Cleared 566timestamp are left untouched. 567.It Fl T Cm load 568Load only the table definitions from 569.Xr pf.conf 5 . 570This is used in conjunction with the 571.Fl f 572flag, as in: 573.Bd -literal -offset indent 574# pfctl -Tl -f pf.conf 575.Ed 576.El 577.Pp 578For the 579.Cm add , 580.Cm delete , 581.Cm replace , 582and 583.Cm test 584commands, the list of addresses can be specified either directly on the command 585line and/or in an unformatted text file, using the 586.Fl f 587flag. 588Comments starting with a 589.Sq # 590or 591.Sq \; 592are allowed in the text file. 593With these commands, the 594.Fl v 595flag can also be used once or twice, in which case 596.Nm 597will print the 598detailed result of the operation for each individual address, prefixed by 599one of the following letters: 600.Pp 601.Bl -tag -width XXX -compact 602.It A 603The address/network has been added. 604.It C 605The address/network has been changed (negated). 606.It D 607The address/network has been deleted. 608.It M 609The address matches 610.Po 611.Cm test 612operation only 613.Pc . 614.It X 615The address/network is duplicated and therefore ignored. 616.It Y 617The address/network cannot be added/deleted due to conflicting 618.Sq \&! 619attributes. 620.It Z 621The address/network has been cleared (statistics). 622.El 623.Pp 624Each table can maintain a set of counters that can be retrieved using the 625.Fl v 626flag of 627.Nm . 628For example, the following commands define a wide open firewall which will keep 629track of packets going to or coming from the 630.Ox 631FTP server. 632The following commands configure the firewall and send 10 pings to the FTP 633server: 634.Bd -literal -offset indent 635# printf "table <test> counters { ftp.openbsd.org }\en \e 636 pass out to <test>\en" | pfctl -f- 637# ping -qc10 ftp.openbsd.org 638.Ed 639.Pp 640We can now use the table 641.Cm show 642command to output, for each address and packet direction, the number of packets 643and bytes that are being passed or blocked by rules referencing the table. 644The time at which the current accounting started is also shown with the 645.Dq Cleared 646line. 647.Bd -literal -offset indent 648# pfctl -t test -vTshow 649 129.128.5.191 650 Cleared: Thu Feb 13 18:55:18 2003 651 In/Block: [ Packets: 0 Bytes: 0 ] 652 In/Pass: [ Packets: 10 Bytes: 840 ] 653 Out/Block: [ Packets: 0 Bytes: 0 ] 654 Out/Pass: [ Packets: 10 Bytes: 840 ] 655.Ed 656.Pp 657Similarly, it is possible to view global information about the tables 658by using the 659.Fl v 660modifier twice and the 661.Fl s 662.Cm Tables 663command. 664This will display the number of addresses on each table, 665the number of rules which reference the table, and the global 666packet statistics for the whole table: 667.Bd -literal -offset indent 668# pfctl -vvsTables 669--a-r-C test 670 Addresses: 1 671 Cleared: Thu Feb 13 18:55:18 2003 672 References: [ Anchors: 0 Rules: 1 ] 673 Evaluations: [ NoMatch: 3496 Match: 1 ] 674 In/Block: [ Packets: 0 Bytes: 0 ] 675 In/Pass: [ Packets: 10 Bytes: 840 ] 676 In/XPass: [ Packets: 0 Bytes: 0 ] 677 Out/Block: [ Packets: 0 Bytes: 0 ] 678 Out/Pass: [ Packets: 10 Bytes: 840 ] 679 Out/XPass: [ Packets: 0 Bytes: 0 ] 680.Ed 681.Pp 682As we can see here, only one packet \- the initial ping request \- matched the 683table, but all packets passing as the result of the state are correctly 684accounted for. 685Reloading the table(s) or ruleset will not affect packet accounting in any way. 686The two 687.Dq XPass 688counters are incremented instead of the 689.Dq Pass 690counters when a 691.Dq stateful 692packet is passed but does not match the table anymore. 693This will happen in our example if someone flushes the table while the 694.Xr ping 8 695command is running. 696.Pp 697When used with a single 698.Fl v , 699.Nm 700will only display the first line containing the table flags and name. 701The flags are defined as follows: 702.Pp 703.Bl -tag -width XXX -compact 704.It c 705For constant tables, which cannot be altered outside 706.Xr pf.conf 5 . 707.It p 708For persistent tables, which do not get automatically killed when no rules 709refer to them. 710.It a 711For tables which are part of the 712.Em active 713tableset. 714Tables without this flag do not really exist, cannot contain addresses, and are 715only listed if the 716.Fl g 717flag is given. 718.It i 719For tables which are part of the 720.Em inactive 721tableset. 722This flag can only be witnessed briefly during the loading of 723.Xr pf.conf 5 . 724.It r 725For tables which are referenced (used) by rules. 726.It h 727This flag is set when a table in the main ruleset is hidden by one or more 728tables of the same name from anchors attached below it. 729.It C 730This flag is set when per-address counters are enabled on the table. 731.El 732.It Fl t Ar table 733Specify the name of the table. 734.It Fl v 735Produce more verbose output. 736A second use of 737.Fl v 738will produce even more verbose output including ruleset warnings. 739See the previous section for its effect on table commands. 740.It Fl x Ar level 741Set the debug 742.Ar level 743(may be abbreviated) to one of the following: 744.Pp 745.Bl -tag -width xxxxxxxxxxxx -compact 746.It Fl x Cm none 747Do not generate debug messages. 748.It Fl x Cm urgent 749Generate debug messages only for serious errors. 750.It Fl x Cm misc 751Generate debug messages for various errors. 752.It Fl x Cm loud 753Generate debug messages for common conditions. 754.El 755.It Fl z 756Clear per-rule statistics. 757.El 758.Sh FILES 759.Bl -tag -width "/etc/pf.conf" -compact 760.It Pa /etc/pf.conf 761Packet filter rules file. 762.It Pa /etc/pf.os 763Passive operating system fingerprint database. 764.El 765.Sh SEE ALSO 766.Xr pf 4 , 767.Xr pf.conf 5 , 768.Xr pf.os 5 , 769.Xr rc.conf 5 , 770.Xr services 5 , 771.Xr sysctl.conf 5 , 772.Xr authpf 8 , 773.Xr ftp-proxy 8 , 774.Xr rc 8 , 775.Xr sysctl 8 776.Sh HISTORY 777The 778.Nm 779program and the 780.Xr pf 4 781filter mechanism appeared in 782.Ox 3.0 . 783They first appeared in 784.Fx 5.3 785ported from the version in 786.Ox 3.5 787