1 .\" $OpenBSD: pfctl.8,v 1.110 2004/03/20 09:31:42 david Exp $
2 .\" $DragonFly: src/usr.sbin/pfctl/pfctl.8,v 1.1 2004/09/21 21:25:28 joerg Exp $
4 .\" Copyright (c) 2001 Kjell Wooding. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. The name of the author may not be used to endorse or promote products
15 .\" derived from this software without specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 .Nd "control the packet filter (PF) and network address translation (NAT) device"
38 .Op Fl a Ar anchor Ns Op Ar :ruleset
39 .Op Fl D Ar macro=value
46 .Op Fl T Ar command Op Ar address ...
53 utility communicates with the packet filter device using the
54 ioctl interface described in
56 It allows ruleset and parameter configuration and retrieval of status
57 information from the packet filter.
59 Packet filtering restricts the types of packets that pass through
60 network interfaces entering or leaving the host based on filter
63 The packet filter can also replace addresses and ports of packets.
64 Replacing source addresses and ports of outgoing packets is called
65 NAT (Network Address Translation) and is used to connect an internal
66 network (usually reserved address space) to an external one (the
67 Internet) by making all connections to external hosts appear to
68 come from the gateway.
69 Replacing destination addresses and ports of incoming packets
70 is used to redirect connections to different hosts and/or ports.
71 A combination of both translations, bidirectional NAT, is also
73 Translation rules are described in
76 When the variable pf is set to YES in
78 the rule file specified with the variable pf_rules
79 is loaded automatically by the
81 scripts and the packet filter is enabled.
83 The packet filter does not itself forward packets between interfaces.
84 Forwarding can be enabled by setting the
87 .Em net.inet.ip.forwarding
89 .Em net.inet6.ip6.forwarding ,
91 Set them permanently in
96 utility provides several commands.
97 The options are as follows:
100 Load only the queue rules present in the rule file.
101 Other rules and options are ignored.
102 .It Fl a Ar anchor Ns Op Ar :ruleset
108 only to the rules in the specified
110 and optional named ruleset
112 In addition to the main ruleset,
114 can load and manipulate additional rulesets by name.
115 Named rulesets are attached at
117 points, which are also referenced by name.
120 rules from the main ruleset is described in
122 For example, to show all filter rules inside anchor
124 .Bd -literal -offset indent
125 # pfctl -a foo -s rules
128 Private tables can also be put inside subrulesets, either by having table
131 file that is loaded in the anchor, or by using regular table commands as in:
132 .Bd -literal -offset indent
133 # pfctl -a foo:bar -t mytable -T add 1.2.3.4 5.6.7.8
136 When a rule referring to a table is loaded in an anchor, the rule will use the
137 private table if one is defined, and then fallback to the table defined in the
138 main ruleset, if there is one.
139 This is similar to C rules for variables.
140 It is possible to create distinct tables with the same name in the global
141 ruleset and in an anchor, but this is often bad design and a warning will be
143 .It Fl D Ar macro=value
149 Overrides the definition of
153 Disable the packet filter.
155 Enable the packet filter.
157 Flush the filter parameters specified by
159 (may be abbreviated):
161 .Bl -tag -width xxxxxxxxxxxx -compact
165 Flush the queue rules.
167 Flush the filter rules.
169 Flush the state table (NAT and filter).
171 Flush the source tracking table.
173 Flush the filter information (statistics that are not bound to rules).
177 Flush the passive operating system fingerprints.
179 Flush all of the above.
182 Load the rules contained in
186 may contain macros, tables, options, and normalization, queueing,
187 translation, and filtering rules.
188 With the exception of macros and tables, the statements must appear in that
191 Include output helpful for debugging.
194 .It Fl i Ar interface
195 Restrict the operation to the given
198 Kill all of the state entries originating from the specified
202 option may be specified, which will kill all the state entries
207 For example, to kill all of the state entries originating from
209 .Bd -literal -offset indent
213 To kill all of the state entries from
217 .Bd -literal -offset indent
218 # pfctl -k host1 -k host2
221 Load only the NAT rules present in the rule file.
222 Other rules and options are ignored.
224 Do not actually load rules, just parse them.
226 Load only the options present in the rule file.
227 Other rules and options are ignored.
231 instead of the default
234 Only print errors and warnings.
236 Load only the filter rules present in the rule file.
237 Other rules and options are ignored.
239 Perform reverse DNS lookups on states when displaying them.
241 Show the filter parameters specified by
243 (may be abbreviated):
245 .Bl -tag -width xxxxxxxxxxxxx -compact
247 Show the currently loaded NAT rules.
249 Show the currently loaded queue rules.
250 When used together with
252 per-queue statistics are also shown.
253 When used together with
256 will loop and show updated queue statistics every five seconds, including
257 measured bandwidth and packets per second.
259 Show the currently loaded filter rules.
260 When used together with
262 the per-rule statistics (number of evaluations,
263 packets and bytes) are also shown.
264 Note that the 'skip step' optimization done automatically by the kernel
265 will skip evaluation of rules where possible.
266 Packets passed statefully are counted in the rule that created the state
267 (even though the rule isn't evaluated more than once for the entire
270 Show the currently loaded anchors.
273 is specified as well, the named rulesets currently loaded in the specified
274 anchor are shown instead.
276 Show the contents of the state table.
278 Show the contents of the source tracking table.
280 Show filter information (statistics and counters).
281 When used together with
283 source tracking statistics are also shown.
285 Show per-rule statistics (label, evaluations, packets, bytes) of
286 filter rules with labels, useful for accounting.
288 Show the current global timeouts.
290 Show the current pool memory hard limits.
292 Show the list of tables.
294 Show the list of operating system fingerprints.
295 .It Fl s Ar Interfaces
296 Show the list of interfaces and interface drivers available to PF.
297 When used together with a double
299 interface statistics are also shown.
301 can be used to select an interface or a group of interfaces.
303 Show all of the above, except for the lists of interfaces and operating
306 .It Fl T Ar command Op Ar address ...
309 (may be abbreviated) to apply to the table.
312 .Bl -tag -width xxxxxxxxxxxx -compact
316 Flush all addresses of a table.
318 Add one or more addresses in a table.
319 Automatically create a nonexisting table.
321 Delete one or more addresses from a table.
323 Replace the addresses of the table.
324 Automatically create a nonexisting table.
326 Show the content (addresses) of a table.
328 Test if the given addresses match a table.
330 Clear all the statistics of a table.
332 Load only the table definitions from
334 This is used in conjunction with the
337 .Bd -literal -offset indent
338 # pfctl -Tl -f pf.conf
348 commands, the list of addresses can be specified either directly on the command
349 line and/or in an unformatted text file, using the
352 Comments starting with a "#" are allowed in the text file.
353 With these commands, the
355 flag can also be used once or twice, in which case
358 detailed result of the operation for each individual address, prefixed by
359 one of the following letters:
361 .Bl -tag -width XXX -compact
363 The address/network has been added.
365 The address/network has been changed (negated).
367 The address/network has been deleted.
369 The address matches (test operation only).
371 The address/network is duplicated and therefore ignored.
373 The address/network cannot be added/deleted due to conflicting "!" attribute.
375 The address/network has been cleared (statistics).
378 Each table maintains a set of counters that can be retrieved using the
382 For example, the following commands define a wide open firewall which will keep
383 track of packets going to or coming from the
386 The following commands configure the firewall and send 10 pings to the ftp
388 .Bd -literal -offset indent
389 # printf "table <test> { ftp.openbsd.org }\en \e
390 pass out to <test> keep state\en" | pfctl -f-
391 # ping -qc10 ftp.openbsd.org
394 We can now use the table
396 command to output, for each address and packet direction, the number of packets
397 and bytes that are being passed or blocked by rules referencing the table.
398 The time at which the current accounting started is also shown with the
401 .Bd -literal -offset indent
402 # pfctl -t test -vTshow
404 Cleared: Thu Feb 13 18:55:18 2003
405 In/Block: [ Packets: 0 Bytes: 0 ]
406 In/Pass: [ Packets: 10 Bytes: 840 ]
407 Out/Block: [ Packets: 0 Bytes: 0 ]
408 Out/Pass: [ Packets: 10 Bytes: 840 ]
411 Similarly, it is possible to view global information about the tables
414 modifier twice and the
417 This will display the number of addresses on each table,
418 the number of rules which reference the table, and the global
419 packet statistics for the whole table:
420 .Bd -literal -offset indent
424 Cleared: Thu Feb 13 18:55:18 2003
425 References: [ Anchors: 0 Rules: 1 ]
426 Evaluations: [ NoMatch: 3496 Match: 1 ]
427 In/Block: [ Packets: 0 Bytes: 0 ]
428 In/Pass: [ Packets: 10 Bytes: 840 ]
429 In/XPass: [ Packets: 0 Bytes: 0 ]
430 Out/Block: [ Packets: 0 Bytes: 0 ]
431 Out/Pass: [ Packets: 10 Bytes: 840 ]
432 Out/XPass: [ Packets: 0 Bytes: 0 ]
435 As we can see here, only one packet \- the initial ping request \- matched the
436 table; but all packets passing as the result of the state are correctly
438 Reloading the table(s) or ruleset will not affect packet accounting in any way.
441 counters are incremented instead of the
443 counters when a "stateful" packet is passed but doesn't match the table
445 This will happen in our example if someone flushes the table while the ping
448 When used with a single
451 will only display the first line containing the table flags and name.
452 The flags are defined as follows:
454 .Bl -tag -width XXX -compact
456 For constant tables, which cannot be altered outside
459 For persistent tables, which don't get automatically flushed when no rules
462 For tables which are part of the
465 Tables without this flag do not really exist, cannot contain addresses, and are
470 For tables which are part of the
473 This flag can only be witnessed briefly during the loading of
476 For tables which are referenced (used) by rules.
478 This flag is set when a table in the main ruleset is hidden by one or more
479 tables of the same name in sub-rulesets (anchors).
482 Specify the name of the table.
484 Produce more verbose output.
487 will produce even more verbose output including ruleset warnings.
488 See previous section for its effect on table commands.
492 (may be abbreviated) to one of the following:
494 .Bl -tag -width xxxxxxxxxxxx -compact
496 Don't generate debug messages.
498 Generate debug messages only for serious errors.
500 Generate debug messages for various errors.
502 Generate debug messages for common conditions.
505 Clear per-rule statistics.
508 .Bl -tag -width "/etc/pf.conf" -compact
510 Packet filter rules file.
526 filter mechanism first appeared in