Some cleanup in the pf manual pages.
[dragonfly.git] / usr.sbin / pfctl / pfctl.8
CommitLineData
70224baa 1.\" $OpenBSD: pfctl.8,v 1.128 2007/01/30 21:01:56 jmc Exp $
95cc27f0
JS
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
b31f0f40 34.Nm
95cc27f0 35.Bk -words
70224baa
JL
36.Op Fl AdeghmNnOqRrvz
37.Op Fl a Ar anchor
38.Oo Fl D Ar macro Ns =
39.Ar value Oc
95cc27f0
JS
40.Op Fl F Ar modifier
41.Op Fl f Ar file
42.Op Fl i Ar interface
70224baa
JL
43.Op Fl K Ar host | network
44.Op Fl k Ar host | network
45.Op Fl o Op Ar level
95cc27f0
JS
46.Op Fl p Ar device
47.Op Fl s Ar modifier
70224baa
JL
48.Oo
49.Fl t Ar table
50.Fl T Ar command
51.Op Ar address ...
52.Oc
95cc27f0
JS
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
b42a1823 81When the variable
70224baa
JL
82.Va pf
83is set to
84.Dv YES
85in
b31f0f40 86.Xr rc.conf 5 ,
b42a1823
SW
87the rule file specified with the variable
88.Va pf_rules
95cc27f0
JS
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
70224baa 97.Em net.inet.ip.forwarding
95cc27f0 98and/or
70224baa 99.Em net.inet6.ip6.forwarding
95cc27f0
JS
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.
70224baa 112.It Fl a Ar anchor
95cc27f0
JS
113Apply flags
114.Fl f ,
70224baa 115.Fl F ,
95cc27f0
JS
116and
117.Fl s
118only to the rules in the specified
70224baa 119.Ar anchor .
95cc27f0
JS
120In addition to the main ruleset,
121.Nm
70224baa
JL
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
95cc27f0
JS
133Evaluation of
134.Ar anchor
135rules from the main ruleset is described in
136.Xr pf.conf 5 .
70224baa
JL
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:
95cc27f0 147.Bd -literal -offset indent
70224baa 148# pfctl -a "authpf/smith(1234)" -s rules
95cc27f0
JS
149.Ed
150.Pp
70224baa 151Private tables can also be put inside anchors, either by having table
95cc27f0
JS
152statements in the
153.Xr pf.conf 5
70224baa 154file that is loaded in the anchor, or by using regular table commands, as in:
95cc27f0 155.Bd -literal -offset indent
70224baa 156# pfctl -a foo/bar -t mytable -T add 1.2.3.4 5.6.7.8
95cc27f0
JS
157.Ed
158.Pp
159When a rule referring to a table is loaded in an anchor, the rule will use the
70224baa 160private table if one is defined, and then fall back to the table defined in the
95cc27f0 161main ruleset, if there is one.
70224baa 162This is similar to C rules for variable scope.
95cc27f0
JS
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.
70224baa
JL
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
95cc27f0
JS
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
70224baa 206.It Fl F Cm nat
95cc27f0 207Flush the NAT rules.
70224baa 208.It Fl F Cm queue
95cc27f0 209Flush the queue rules.
70224baa 210.It Fl F Cm rules
95cc27f0 211Flush the filter rules.
70224baa 212.It Fl F Cm state
95cc27f0 213Flush the state table (NAT and filter).
70224baa 214.It Fl F Cm Sources
95cc27f0 215Flush the source tracking table.
70224baa 216.It Fl F Cm info
95cc27f0 217Flush the filter information (statistics that are not bound to rules).
70224baa 218.It Fl F Cm Tables
95cc27f0 219Flush the tables.
70224baa 220.It Fl F Cm osfp
95cc27f0 221Flush the passive operating system fingerprints.
70224baa 222.It Fl F Cm all
95cc27f0
JS
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 .
70224baa
JL
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
95cc27f0 253Kill all of the state entries originating from the specified
70224baa
JL
254.Ar host
255or
256.Ar network .
95cc27f0
JS
257A second
258.Fl k Ar host
70224baa
JL
259or
260.Fl k Ar network
95cc27f0 261option may be specified, which will kill all the state entries
70224baa 262from the first host/network to the second.
95cc27f0 263For example, to kill all of the state entries originating from
70224baa
JL
264.Dq host :
265.Pp
266.Dl # pfctl -k host
95cc27f0
JS
267.Pp
268To kill all of the state entries from
70224baa 269.Dq host1
95cc27f0 270to
70224baa
JL
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:
95cc27f0 288.Bd -literal -offset indent
70224baa 289# echo "set loginterface fxp0" | pfctl -mf -
95cc27f0
JS
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.
70224baa
JL
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.
95cc27f0
JS
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
70224baa 369.It Fl s Cm nat
95cc27f0 370Show the currently loaded NAT rules.
70224baa 371.It Fl s Cm queue
95cc27f0
JS
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.
70224baa 381.It Fl s Cm rules
95cc27f0
JS
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.
70224baa
JL
387Note that the
388.Dq skip step
389optimization done automatically by the kernel
95cc27f0
JS
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).
70224baa
JL
394.It Fl s Cm Anchors
395Show the currently loaded anchors directly attached to the main ruleset.
95cc27f0
JS
396If
397.Fl a Ar anchor
70224baa
JL
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
95cc27f0 406Show the contents of the state table.
70224baa 407.It Fl s Cm Sources
95cc27f0 408Show the contents of the source tracking table.
70224baa 409.It Fl s Cm info
95cc27f0
JS
410Show filter information (statistics and counters).
411When used together with
412.Fl v ,
413source tracking statistics are also shown.
70224baa
JL
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
95cc27f0 417filter rules with labels, useful for accounting.
70224baa 418.It Fl s Cm timeouts
95cc27f0 419Show the current global timeouts.
70224baa 420.It Fl s Cm memory
95cc27f0 421Show the current pool memory hard limits.
70224baa 422.It Fl s Cm Tables
95cc27f0 423Show the list of tables.
70224baa 424.It Fl s Cm osfp
95cc27f0 425Show the list of operating system fingerprints.
70224baa 426.It Fl s Cm Interfaces
95cc27f0 427Show the list of interfaces and interface drivers available to PF.
70224baa 428When used together with
95cc27f0 429.Fl v ,
70224baa
JL
430it additionally lists which interfaces have skip rules activated.
431When used together with
432.Fl vv ,
95cc27f0
JS
433interface statistics are also shown.
434.Fl i
435can be used to select an interface or a group of interfaces.
70224baa 436.It Fl s Cm all
95cc27f0
JS
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
70224baa 447.It Fl T Cm kill
95cc27f0 448Kill a table.
70224baa 449.It Fl T Cm flush
95cc27f0 450Flush all addresses of a table.
70224baa 451.It Fl T Cm add
95cc27f0
JS
452Add one or more addresses in a table.
453Automatically create a nonexisting table.
70224baa 454.It Fl T Cm delete
95cc27f0 455Delete one or more addresses from a table.
70224baa
JL
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
95cc27f0
JS
464Replace the addresses of the table.
465Automatically create a nonexisting table.
70224baa 466.It Fl T Cm show
95cc27f0 467Show the content (addresses) of a table.
70224baa 468.It Fl T Cm test
95cc27f0 469Test if the given addresses match a table.
70224baa 470.It Fl T Cm zero
95cc27f0 471Clear all the statistics of a table.
70224baa 472.It Fl T Cm load
95cc27f0
JS
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
70224baa
JL
484.Cm add ,
485.Cm delete ,
486.Cm replace ,
95cc27f0 487and
70224baa 488.Cm test
95cc27f0
JS
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.
70224baa
JL
493Comments starting with a
494.Sq #
495are allowed in the text file.
95cc27f0
JS
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
70224baa
JL
512The address matches
513.Po
514.Cm test
515operation only
516.Pc .
95cc27f0
JS
517.It X
518The address/network is duplicated and therefore ignored.
519.It Y
70224baa
JL
520The address/network cannot be added/deleted due to conflicting
521.Sq \&!
522attributes.
95cc27f0
JS
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
70224baa
JL
534FTP server.
535The following commands configure the firewall and send 10 pings to the FTP
95cc27f0
JS
536server:
537.Bd -literal -offset indent
538# printf "table <test> { ftp.openbsd.org }\en \e
70224baa 539 pass out to <test>\en" | pfctl -f-
95cc27f0
JS
540# ping -qc10 ftp.openbsd.org
541.Ed
542.Pp
543We can now use the table
70224baa 544.Cm show
95cc27f0
JS
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
70224baa 548.Dq Cleared
95cc27f0
JS
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
70224baa
JL
564.Fl s
565.Cm Tables
95cc27f0
JS
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
70224baa 586table, but all packets passing as the result of the state are correctly
95cc27f0
JS
587accounted for.
588Reloading the table(s) or ruleset will not affect packet accounting in any way.
589The two
70224baa 590.Dq XPass
95cc27f0 591counters are incremented instead of the
70224baa
JL
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
95cc27f0
JS
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
70224baa 611For persistent tables, which don't get automatically killed when no rules
95cc27f0
JS
612refer to them.
613.It a
614For tables which are part of the
70224baa 615.Em active
95cc27f0
JS
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
70224baa 623.Em inactive
95cc27f0
JS
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
70224baa 631tables of the same name from anchors attached below it.
95cc27f0
JS
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.
70224baa 640See the previous section for its effect on table commands.
95cc27f0
JS
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
70224baa 647.It Fl x Cm none
95cc27f0 648Don't generate debug messages.
70224baa 649.It Fl x Cm urgent
95cc27f0 650Generate debug messages only for serious errors.
70224baa 651.It Fl x Cm misc
95cc27f0 652Generate debug messages for various errors.
70224baa 653.It Fl x Cm loud
95cc27f0
JS
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.
70224baa
JL
663.It Pa /etc/pf.os
664Passive operating system fingerprint database.
95cc27f0
JS
665.El
666.Sh SEE ALSO
667.Xr pf 4 ,
668.Xr pf.conf 5 ,
669.Xr pf.os 5 ,
b31f0f40 670.Xr rc.conf 5 ,
95cc27f0 671.Xr sysctl.conf 5 ,
70224baa 672.Xr authpf 8 ,
95cc27f0
JS
673.Xr ftp-proxy 8 ,
674.Xr rc 8 ,
95cc27f0
JS
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 .