The userland tool for injecting and inspecting data in the Packet Filter is pfctl(8).
NAME
pfctl - control the packet filter (PF) device
DESCRIPTION
The pfctl utility communicates with the packet filter device using the
ioctl interface described in pf(4) . It allows ruleset and parameter
configuration and retrieval of status information from the packet filter.
Table of Contents
As your curiosity level with pf increases, (also known as “not knowing, what’s going on”) pfctl is the tool to use for inspecting how pf has viewed your ruleset (-s rules) and discover active details about the packet filter.
Work in Progress —
Below are the more common uses of pfctl in my context
Feeding the PF Engine is simplified using pfctl’s “-f” option for specifying a file with PF rules.
-f file Load the rules contained in file. This 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.
Common invocations using “-f” include:
-f /etc/pf.conf Load the pf.conf file -nf /etc/pf.conf Parse the file, but don't load it -Nf /etc/pf.conf Load only the NAT rules from the file -Rf /etc/pf.conf Load only the filter rules from the file
As such, my most common invocation is to ‘parse’ a modified ruleset using “pfctl -nf /etc/pf.conf” where the rules are not loaded but are checked for syntax and some logic.
Similarly, because of Unix’s piping capabilities, we can verify and inject a new PF directive from the command line such as:
# echo "pass on eth0 from any to any port 80" | pfctl -nf -
stdin:1: port only applies to tcp/udp stdin:1: skipping rule due to errors stdin:1: rule expands to no valid combination
The above shows pfctl parsing the console input, and finding errors, which can be corrected in the below update to the rule (read: add “proto tcp”).
# echo "pass on eth0 proto tcp from any to any port 80" | pfctl -nf -
Note: No output indicates success.
Warning: note that “-f” loads the ruleset to replace the existing ruleset. If you intend to use the command-line to “add rules”, consider something as the below:
(echo "block all"; pfctl -sr) | pfctl -f -# (pfctl -sr; echo "pass quick on lo0") | pfctl -f -Install the ’new’ ruleset for a set amount of time, and then re-install the ‘production’ ruleset.
# pfctl -vf /etc/pf.conf.new ; sleep 30; pfctl -f /etc/pf.confWe can view PF’s interpretation, by using the “-s rules”
-s modifier
Show the filter parameters specified by modifier (may be
abbreviated):
You create rules following the manual pages pf.conf and the FAQ, but you are still uncertain that you and the Packet Filter understand the same thing from manuals.
-s rules Show the currently loaded filter rules. When used
together with -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).
For an example, to use the default ruleset (/etc/pf.conf) as an example
set skip on lo pass # to establish keep-state block in on ! lo0 proto tcp to port 6000:6010
pfctl -s rules
pass all flags S/SA keep state block drop in on ! lo0 proto tcp from any to any port 6000:6010
The rules inside the PF engine is more specific than what is written in PF (a simplistic example) but provides a simple overview of how you can use pfctl to review your understanding, against how the PF engine is interpreting it.
-s nat Show the currently loaded NAT rules
-s queue Show the currently loaded queue rules
-s rules Show the currently loaded filter rules
-s Anchors Show the currently loaded anchors directly
attached to the main ruleset.
-s states Show the contents of the state table.
-s Sources Show the contents of the source tracking table.
-s info Show filter information (statistics and counters)
-s labels Show per-rule statistics.
-s timeouts Show the current global timeouts
-s memory Show the current pool memory hard limits
-s Tables Show the list of tables
-s osfp Show the list of operating system fingerprints
-s Interfaces Show the list of interfaces and interface drivers
available to PF.
-s all Show all of the above.
To get more detailed usage data for each show values option, pfctl can be invoked with the “-v” (verbose) option. The following example shows how to get detailed usage data for each firewall rule:
% sudo pfctl -v -s rules
scrub in all no-df fragment reassemble [ Evaluations: 373620187 Packets: 179290329 Bytes: 45895535624 States: 0 ] [ Inserted: uid 0 pid 24100 ] scrub out all no-df fragment reassemble [ Evaluations: 194329858 Packets: 194329858 Bytes: 58848165945 States: 0 ] [ Inserted: uid 0 pid 24100 ] block drop in log on ! lo0 inet from 127.0.0.0/8 to any [ Evaluations: 2934066 Packets: 0 Bytes: 0 States: 0 ] [ Inserted: uid 0 pid 24100 ]
To optimize ruleset evaluation, tables is an important tool in storing data for the PF Engine. pfctl provides some useful invocations to let you monitor and manage tables.
-s Tables Show Tables -T show -t table-name Display entries in table 'table-name' -T show -vt table-name Display table counters for 'table-name' -vs Tables Display global information -T add -t table-name ip-address Add an 'ip-address' to table 'table-name' -T delete -t table-name ip-address Delete an 'ip-address' from table 'table-name'
The general invocation of pfctl to reload the ruleset is
pfctl -f /etc/pf.conf
pfctl instructs the PF Engine to load a new ruleset from /etc/pf.conf and on completion switch from the existing ruleset to the newly loaded ruleset.
Noted practises use -F rules -f /etc/pf.conf which, noted by dhartmei’s article PF Firewall Management introduces a moment (between Flusing the rules, and the kernel loading the new rules) where no rules exist.
We can flush and remove other items from the PF Engine.
-F nat Flush the NAT rules
-F queue Flush the queue rules
-F rules Flush the filter rules
-F states Flush the state table (NAT and filter)
-F sources Flush the sources tracking table
-F info Flush the filter information
(statistics that are not bound to rules)
-F Tables Flush the tables
-F osfp Flush the passive operating system signatures
-F all Flush all of the above
As in the above table, when you’ve made changes to /etc/pf.conf and are reloading the ruleset, make sure you flush the appropriate rules (whether they’re changes you’ve made to nat or filter rules etc.)
Remember that you don’t want to flush without loading a new set of replacements.
[Ref: PF Firewall Management]
When refreshing firewall rules, you can kill state information by explicitly using the “-k | -K” pfctl option.
-K host | network
-k host | network | label | id
For example, to kill all of the state entries originating from
``host'':
# pfctl -k host
A second -k host or -k network option may be specified, which
will kill all the state entries from the first host/network to
the second. To kill all of the state entries from ``host1'' to
``host2'':
# pfctl -k host1 -k host2
A network prefix length of 0 can be used as a wildcard. To kill
all states with the target ``host2'':
# pfctl -k 0.0.0.0/0 -k host2
It is also possible to kill states by rule label or state ID. In
this mode the first -k argument is used to specify the type of
the second argument. The following command would kill all states
that have been created from rules carrying the label ``foobar'':
# pfctl -k label -k foobar
To kill one specific state by its unique state ID (as shown by
pfctl -s state -vv), use the id modifier and as a second argument
the state ID and optional creator ID. To kill a state with ID
4823e84500000003 use:
# pfctl -k id -k 4823e84500000003
To kill a state with ID 4823e84500000018 created from a backup
firewall with hostid 00000002 use:
# pfctl -k id -k 4823e84500000018/2
Obviously there are some cooler uses of pfctl, want to share?