stv
is a State Table Viewer for pfSense. It's meant to be used at the commandline (console or ssh). stv leverages pfctl
and awk
to generate its output.
Troubleshooting firewall rules can be tricky. There are some good tools included to help, like pfTop, trafshow, iftop, tcpdump and others.
Still, I found myself struggling to get the output I wanted: a list of states where everything was reasonably structured, and every state occupied just a single line (so it can be further piped to grep, awk etc)
stv achieves this.
- connect to your pfSense instance using ssh or via the console.
- select option 8.
- paste the commands below to download stv and prepare it for execution:
mkdir /root/bin
fetch -o /root/bin/stv https://github.com/luckman212/stv/releases/download/1.2.0/stv
chmod +x /root/bin/stv
rehash
Using stv is easy. Just drop to a shell and type:
stv
You should see a list of states, with the following columns of information:
- protocol (
tcp, udp, icmp
...) - direction (in/out)
- interface that the state was generated on
- rule associated with the state (id & first few chars of description)
- state/creator ID (uniquely identifies a state—you can then kill it with
pfctl -k id -k <id>
) - state description (
ESTABLISHED
,FIN_WAIT
etc) - "talkers" - the IPs and ports of the hosts involved
- gateway (shown only if it's not the default)
stv works best on a wide (>170 columns or more) terminal.
stv has a built in helper function to search your pf-generated ruleset and output the rule id along with whatever you've entered in pfSense as a description. This can help identify what rule is triggering a state when debugging.
Use stv --rule <regex>
to use this function. Example:
# stv --rule ^110
110 let out anything from firewall host itself
# stv --rule block
134 block SIP ! whitelisted
135 block SIP ! whitelisted
stv accepts an optional parameter which can be used to filter the results to those matching a particular interface, rule ID, state type, IP address etc. The argument is a regex (regular expression).
- run
stv -h
for usage help - Pad the search string with
%
's to make it explicit, otherwise it will be treated as a substring match. - When entering expressions with special characters like
[]
or.*
enclose them in single quotes to avoid shell interpretation. - To search for a literal
[
or]
, use\\[
and\\]
stv '%267%'
to output states associated with rule 267 (trypfctl -vvsr
to list all rules along with the internal pf ruleIDs)stv ESTAB
to only print active (established) statesstv ':4443 '
port 4443stv '%igc[0-2]%'
show states related to interfaces igc0, igc1 and igc2
Since all output is standardized and each state is printed on a single line, output from stv is well-suited to piping into other tools such as grep or awk.
stv will print the total number of matching states at the bottom of the output.
Here's a sample screenshot showing NFS port 2049:
To have a "live" updating display, you can use cmdwatch
. This is the recommended method.
- install
pkg add https://pkg.freebsd.org/FreeBSD:12:amd64/latest/All/cmdwatch-0.2.0_2.txz
- run
cmdwatch --interval=2 'stv :5201 '
If you prefer not to install any additional packages, you can use a simple shell loop instead:
while :; do clear; stv '%icmp.*tun_wg1%'; sleep 2; done
Press ⌃ctrl+c to stop the loop.