527 lines
15 KiB
Groff
527 lines
15 KiB
Groff
.\" $OpenBSD: pfctl.8,v 1.110 2004/03/20 09:31:42 david Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 Kjell Wooding. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd November 20, 2002
|
|
.Dt PFCTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pfctl
|
|
.Nd "control the packet filter (PF) and network address translation (NAT) device"
|
|
.Sh SYNOPSIS
|
|
.Nm pfctl
|
|
.Bk -words
|
|
.Op Fl AdeghNnOqRrvz
|
|
.Op Fl a Ar anchor Ns Op Ar :ruleset
|
|
.Op Fl D Ar macro=value
|
|
.Op Fl F Ar modifier
|
|
.Op Fl f Ar file
|
|
.Op Fl i Ar interface
|
|
.Op Fl k Ar host
|
|
.Op Fl p Ar device
|
|
.Op Fl s Ar modifier
|
|
.Op Fl T Ar command Op Ar address ...
|
|
.Op Fl t Ar table
|
|
.Op Fl x Ar level
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility communicates with the packet filter device using the
|
|
ioctl interface described in
|
|
.Xr pf 4 .
|
|
It allows ruleset and parameter configuration and retrieval of status
|
|
information from the packet filter.
|
|
.Pp
|
|
Packet filtering restricts the types of packets that pass through
|
|
network interfaces entering or leaving the host based on filter
|
|
rules as described in
|
|
.Xr pf.conf 5 .
|
|
The packet filter can also replace addresses and ports of packets.
|
|
Replacing source addresses and ports of outgoing packets is called
|
|
NAT (Network Address Translation) and is used to connect an internal
|
|
network (usually reserved address space) to an external one (the
|
|
Internet) by making all connections to external hosts appear to
|
|
come from the gateway.
|
|
Replacing destination addresses and ports of incoming packets
|
|
is used to redirect connections to different hosts and/or ports.
|
|
A combination of both translations, bidirectional NAT, is also
|
|
supported.
|
|
Translation rules are described in
|
|
.Xr pf.conf 5 .
|
|
.Pp
|
|
When the variable pf is set to YES in
|
|
.Xr rc.conf 8 ,
|
|
the rule file specified with the variable pf_rules
|
|
is loaded automatically by the
|
|
.Xr rc 8
|
|
scripts and the packet filter is enabled.
|
|
.Pp
|
|
The packet filter does not itself forward packets between interfaces.
|
|
Forwarding can be enabled by setting the
|
|
.Xr sysctl 8
|
|
variables
|
|
.Em net.inet.ip.forwarding
|
|
and/or
|
|
.Em net.inet6.ip6.forwarding ,
|
|
to 1.
|
|
Set them permanently in
|
|
.Xr sysctl.conf 5 .
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility provides several commands.
|
|
The options are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl A
|
|
Load only the queue rules present in the rule file.
|
|
Other rules and options are ignored.
|
|
.It Fl a Ar anchor Ns Op Ar :ruleset
|
|
Apply flags
|
|
.Fl f ,
|
|
.Fl F
|
|
and
|
|
.Fl s
|
|
only to the rules in the specified
|
|
.Ar anchor
|
|
and optional named ruleset
|
|
.Ar ruleset .
|
|
In addition to the main ruleset,
|
|
.Nm
|
|
can load and manipulate additional rulesets by name.
|
|
Named rulesets are attached at
|
|
.Ar anchor
|
|
points, which are also referenced by name.
|
|
Evaluation of
|
|
.Ar anchor
|
|
rules from the main ruleset is described in
|
|
.Xr pf.conf 5 .
|
|
For example, to show all filter rules inside anchor
|
|
.Li foo :
|
|
.Bd -literal -offset indent
|
|
# pfctl -a foo -s rules
|
|
.Ed
|
|
.Pp
|
|
Private tables can also be put inside subrulesets, either by having table
|
|
statements in the
|
|
.Xr pf.conf 5
|
|
file that is loaded in the anchor, or by using regular table commands as in:
|
|
.Bd -literal -offset indent
|
|
# pfctl -a foo:bar -t mytable -T add 1.2.3.4 5.6.7.8
|
|
.Ed
|
|
.Pp
|
|
When a rule referring to a table is loaded in an anchor, the rule will use the
|
|
private table if one is defined, and then fallback to the table defined in the
|
|
main ruleset, if there is one.
|
|
This is similar to C rules for variables.
|
|
It is possible to create distinct tables with the same name in the global
|
|
ruleset and in an anchor, but this is often bad design and a warning will be
|
|
issued in that case.
|
|
.It Fl D Ar macro=value
|
|
Define
|
|
.Ar macro
|
|
to be set to
|
|
.Ar value
|
|
on the command line.
|
|
Overrides the definition of
|
|
.Ar macro
|
|
in the ruleset.
|
|
.It Fl d
|
|
Disable the packet filter.
|
|
.It Fl e
|
|
Enable the packet filter.
|
|
.It Fl F Ar modifier
|
|
Flush the filter parameters specified by
|
|
.Ar modifier
|
|
(may be abbreviated):
|
|
.Pp
|
|
.Bl -tag -width xxxxxxxxxxxx -compact
|
|
.It Fl F Ar nat
|
|
Flush the NAT rules.
|
|
.It Fl F Ar queue
|
|
Flush the queue rules.
|
|
.It Fl F Ar rules
|
|
Flush the filter rules.
|
|
.It Fl F Ar state
|
|
Flush the state table (NAT and filter).
|
|
.It Fl F Ar Sources
|
|
Flush the source tracking table.
|
|
.It Fl F Ar info
|
|
Flush the filter information (statistics that are not bound to rules).
|
|
.It Fl F Ar Tables
|
|
Flush the tables.
|
|
.It Fl F Ar osfp
|
|
Flush the passive operating system fingerprints.
|
|
.It Fl F Ar all
|
|
Flush all of the above.
|
|
.El
|
|
.It Fl f Ar file
|
|
Load the rules contained in
|
|
.Ar file .
|
|
This
|
|
.Ar file
|
|
may contain macros, tables, options, and normalization, queueing,
|
|
translation, and filtering rules.
|
|
With the exception of macros and tables, the statements must appear in that
|
|
order.
|
|
.It Fl g
|
|
Include output helpful for debugging.
|
|
.It Fl h
|
|
Help.
|
|
.It Fl i Ar interface
|
|
Restrict the operation to the given
|
|
.Ar interface .
|
|
.It Fl k Ar host
|
|
Kill all of the state entries originating from the specified
|
|
.Ar host .
|
|
A second
|
|
.Fl k Ar host
|
|
option may be specified, which will kill all the state entries
|
|
from the first
|
|
.Ar host
|
|
to the second
|
|
.Ar host .
|
|
For example, to kill all of the state entries originating from
|
|
.Li host :
|
|
.Bd -literal -offset indent
|
|
# pfctl -k host
|
|
.Ed
|
|
.Pp
|
|
To kill all of the state entries from
|
|
.Li host1
|
|
to
|
|
.Li host2 :
|
|
.Bd -literal -offset indent
|
|
# pfctl -k host1 -k host2
|
|
.Ed
|
|
.It Fl N
|
|
Load only the NAT rules present in the rule file.
|
|
Other rules and options are ignored.
|
|
.It Fl n
|
|
Do not actually load rules, just parse them.
|
|
.It Fl O
|
|
Load only the options present in the rule file.
|
|
Other rules and options are ignored.
|
|
.It Fl p Ar device
|
|
Use the device file
|
|
.Ar device
|
|
instead of the default
|
|
.Pa /dev/pf .
|
|
.It Fl q
|
|
Only print errors and warnings.
|
|
.It Fl R
|
|
Load only the filter rules present in the rule file.
|
|
Other rules and options are ignored.
|
|
.It Fl r
|
|
Perform reverse DNS lookups on states when displaying them.
|
|
.It Fl s Ar modifier
|
|
Show the filter parameters specified by
|
|
.Ar modifier
|
|
(may be abbreviated):
|
|
.Pp
|
|
.Bl -tag -width xxxxxxxxxxxxx -compact
|
|
.It Fl s Ar nat
|
|
Show the currently loaded NAT rules.
|
|
.It Fl s Ar queue
|
|
Show the currently loaded queue rules.
|
|
When used together with
|
|
.Fl v ,
|
|
per-queue statistics are also shown.
|
|
When used together with
|
|
.Fl v v ,
|
|
.Nm
|
|
will loop and show updated queue statistics every five seconds, including
|
|
measured bandwidth and packets per second.
|
|
.It Fl s Ar rules
|
|
Show the currently loaded filter rules.
|
|
When used together with
|
|
.Fl v ,
|
|
the per-rule statistics (number of evaluations,
|
|
packets and bytes) are also shown.
|
|
Note that the 'skip step' optimization done automatically by the kernel
|
|
will skip evaluation of rules where possible.
|
|
Packets passed statefully are counted in the rule that created the state
|
|
(even though the rule isn't evaluated more than once for the entire
|
|
connection).
|
|
.It Fl s Ar Anchors
|
|
Show the currently loaded anchors.
|
|
If
|
|
.Fl a Ar anchor
|
|
is specified as well, the named rulesets currently loaded in the specified
|
|
anchor are shown instead.
|
|
.It Fl s Ar state
|
|
Show the contents of the state table.
|
|
.It Fl s Ar Sources
|
|
Show the contents of the source tracking table.
|
|
.It Fl s Ar info
|
|
Show filter information (statistics and counters).
|
|
When used together with
|
|
.Fl v ,
|
|
source tracking statistics are also shown.
|
|
.It Fl s Ar labels
|
|
Show per-rule statistics (label, evaluations, packets, bytes) of
|
|
filter rules with labels, useful for accounting.
|
|
.It Fl s Ar timeouts
|
|
Show the current global timeouts.
|
|
.It Fl s Ar memory
|
|
Show the current pool memory hard limits.
|
|
.It Fl s Ar Tables
|
|
Show the list of tables.
|
|
.It Fl s Ar osfp
|
|
Show the list of operating system fingerprints.
|
|
.It Fl s Ar Interfaces
|
|
Show the list of interfaces and interface drivers available to PF.
|
|
When used together with a double
|
|
.Fl v ,
|
|
interface statistics are also shown.
|
|
.Fl i
|
|
can be used to select an interface or a group of interfaces.
|
|
.It Fl s Ar all
|
|
Show all of the above, except for the lists of interfaces and operating
|
|
system fingerprints.
|
|
.El
|
|
.It Fl T Ar command Op Ar address ...
|
|
Specify the
|
|
.Ar command
|
|
(may be abbreviated) to apply to the table.
|
|
Commands include:
|
|
.Pp
|
|
.Bl -tag -width xxxxxxxxxxxx -compact
|
|
.It Fl T Ar kill
|
|
Kill a table.
|
|
.It Fl T Ar flush
|
|
Flush all addresses of a table.
|
|
.It Fl T Ar add
|
|
Add one or more addresses in a table.
|
|
Automatically create a nonexisting table.
|
|
.It Fl T Ar delete
|
|
Delete one or more addresses from a table.
|
|
.It Fl T Ar replace
|
|
Replace the addresses of the table.
|
|
Automatically create a nonexisting table.
|
|
.It Fl T Ar show
|
|
Show the content (addresses) of a table.
|
|
.It Fl T Ar test
|
|
Test if the given addresses match a table.
|
|
.It Fl T Ar zero
|
|
Clear all the statistics of a table.
|
|
.It Fl T Ar load
|
|
Load only the table definitions from
|
|
.Xr pf.conf 5 .
|
|
This is used in conjunction with the
|
|
.Fl f
|
|
flag, as in:
|
|
.Bd -literal -offset indent
|
|
# pfctl -Tl -f pf.conf
|
|
.Ed
|
|
.El
|
|
.Pp
|
|
For the
|
|
.Ar add ,
|
|
.Ar delete ,
|
|
.Ar replace
|
|
and
|
|
.Ar test
|
|
commands, the list of addresses can be specified either directly on the command
|
|
line and/or in an unformatted text file, using the
|
|
.Fl f
|
|
flag.
|
|
Comments starting with a "#" are allowed in the text file.
|
|
With these commands, the
|
|
.Fl v
|
|
flag can also be used once or twice, in which case
|
|
.Nm
|
|
will print the
|
|
detailed result of the operation for each individual address, prefixed by
|
|
one of the following letters:
|
|
.Pp
|
|
.Bl -tag -width XXX -compact
|
|
.It A
|
|
The address/network has been added.
|
|
.It C
|
|
The address/network has been changed (negated).
|
|
.It D
|
|
The address/network has been deleted.
|
|
.It M
|
|
The address matches (test operation only).
|
|
.It X
|
|
The address/network is duplicated and therefore ignored.
|
|
.It Y
|
|
The address/network cannot be added/deleted due to conflicting "!" attribute.
|
|
.It Z
|
|
The address/network has been cleared (statistics).
|
|
.El
|
|
.Pp
|
|
Each table maintains a set of counters that can be retrieved using the
|
|
.Fl v
|
|
flag of
|
|
.Nm .
|
|
For example, the following commands define a wide open firewall which will keep
|
|
track of packets going to or coming from the
|
|
.Ox
|
|
ftp server.
|
|
The following commands configure the firewall and send 10 pings to the ftp
|
|
server:
|
|
.Bd -literal -offset indent
|
|
# printf "table <test> { ftp.openbsd.org }\en \e
|
|
pass out to <test> keep state\en" | pfctl -f-
|
|
# ping -qc10 ftp.openbsd.org
|
|
.Ed
|
|
.Pp
|
|
We can now use the table
|
|
.Ar show
|
|
command to output, for each address and packet direction, the number of packets
|
|
and bytes that are being passed or blocked by rules referencing the table.
|
|
The time at which the current accounting started is also shown with the
|
|
.Ar Cleared
|
|
line.
|
|
.Bd -literal -offset indent
|
|
# pfctl -t test -vTshow
|
|
129.128.5.191
|
|
Cleared: Thu Feb 13 18:55:18 2003
|
|
In/Block: [ Packets: 0 Bytes: 0 ]
|
|
In/Pass: [ Packets: 10 Bytes: 840 ]
|
|
Out/Block: [ Packets: 0 Bytes: 0 ]
|
|
Out/Pass: [ Packets: 10 Bytes: 840 ]
|
|
.Ed
|
|
.Pp
|
|
Similarly, it is possible to view global information about the tables
|
|
by using the
|
|
.Fl v
|
|
modifier twice and the
|
|
.Ar show Tables
|
|
command.
|
|
This will display the number of addresses on each table,
|
|
the number of rules which reference the table, and the global
|
|
packet statistics for the whole table:
|
|
.Bd -literal -offset indent
|
|
# pfctl -vvsTables
|
|
--a-r- test
|
|
Addresses: 1
|
|
Cleared: Thu Feb 13 18:55:18 2003
|
|
References: [ Anchors: 0 Rules: 1 ]
|
|
Evaluations: [ NoMatch: 3496 Match: 1 ]
|
|
In/Block: [ Packets: 0 Bytes: 0 ]
|
|
In/Pass: [ Packets: 10 Bytes: 840 ]
|
|
In/XPass: [ Packets: 0 Bytes: 0 ]
|
|
Out/Block: [ Packets: 0 Bytes: 0 ]
|
|
Out/Pass: [ Packets: 10 Bytes: 840 ]
|
|
Out/XPass: [ Packets: 0 Bytes: 0 ]
|
|
.Ed
|
|
.Pp
|
|
As we can see here, only one packet \- the initial ping request \- matched the
|
|
table; but all packets passing as the result of the state are correctly
|
|
accounted for.
|
|
Reloading the table(s) or ruleset will not affect packet accounting in any way.
|
|
The two
|
|
.Ar XPass
|
|
counters are incremented instead of the
|
|
.Ar Pass
|
|
counters when a "stateful" packet is passed but doesn't match the table
|
|
anymore.
|
|
This will happen in our example if someone flushes the table while the ping
|
|
command is running.
|
|
.Pp
|
|
When used with a single
|
|
.Fl v ,
|
|
.Nm
|
|
will only display the first line containing the table flags and name.
|
|
The flags are defined as follows:
|
|
.Pp
|
|
.Bl -tag -width XXX -compact
|
|
.It c
|
|
For constant tables, which cannot be altered outside
|
|
.Xr pf.conf 5 .
|
|
.It p
|
|
For persistent tables, which don't get automatically flushed when no rules
|
|
refer to them.
|
|
.It a
|
|
For tables which are part of the
|
|
.Ar active
|
|
tableset.
|
|
Tables without this flag do not really exist, cannot contain addresses, and are
|
|
only listed if the
|
|
.Fl g
|
|
flag is given.
|
|
.It i
|
|
For tables which are part of the
|
|
.Ar inactive
|
|
tableset.
|
|
This flag can only be witnessed briefly during the loading of
|
|
.Xr pf.conf 5 .
|
|
.It r
|
|
For tables which are referenced (used) by rules.
|
|
.It h
|
|
This flag is set when a table in the main ruleset is hidden by one or more
|
|
tables of the same name in sub-rulesets (anchors).
|
|
.El
|
|
.It Fl t Ar table
|
|
Specify the name of the table.
|
|
.It Fl v
|
|
Produce more verbose output.
|
|
A second use of
|
|
.Fl v
|
|
will produce even more verbose output including ruleset warnings.
|
|
See previous section for its effect on table commands.
|
|
.It Fl x Ar level
|
|
Set the debug
|
|
.Ar level
|
|
(may be abbreviated) to one of the following:
|
|
.Pp
|
|
.Bl -tag -width xxxxxxxxxxxx -compact
|
|
.It Fl x Ar none
|
|
Don't generate debug messages.
|
|
.It Fl x Ar urgent
|
|
Generate debug messages only for serious errors.
|
|
.It Fl x Ar misc
|
|
Generate debug messages for various errors.
|
|
.It Fl x Ar loud
|
|
Generate debug messages for common conditions.
|
|
.El
|
|
.It Fl z
|
|
Clear per-rule statistics.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/etc/pf.conf" -compact
|
|
.It Pa /etc/pf.conf
|
|
Packet filter rules file.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr pf 4 ,
|
|
.Xr pf.conf 5 ,
|
|
.Xr pf.os 5 ,
|
|
.Xr sysctl.conf 5 ,
|
|
.Xr ftp-proxy 8 ,
|
|
.Xr rc 8 ,
|
|
.Xr rc.conf 8 ,
|
|
.Xr sysctl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
program and the
|
|
.Xr pf 4
|
|
filter mechanism first appeared in
|
|
.Ox 3.0 .
|