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