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