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