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