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