PHP shell 10
| Command | What it does |
|---|---|
pfSsh.php | PHP shellStarts the developer shell from a root prompt; the same shell as console option 12. |
help | Show PHP shell helpPrints sample commands, such as printing a config section or saving with write_config(). |
exec | Run the entered linesLines typed before it are collected and run together as one set. |
! COMMAND | Queue a system shell commandMixes shell commands with PHP lines in the set that exec runs. |
exit | Leave the PHP shellExit after each playback script, since one session is not built to run several. |
record NAME | Start recording a sessionSaves the commands that follow under that name, to replay later like a built-in script. |
stoprecording | Stop recordingCloses the recording that record started. |
showrecordings | List recorded sessions |
playback SCRIPTNAME | Run a script inside the shellStart a fresh PHP shell for every further script, or later ones may fail. |
pfSsh.php playback SCRIPTNAME | Run a script from the promptWorks over SSH or at the console only, never through the GUI command prompt. |
Playback scripts 26
A row that shows only a script name runs as pfSsh.php playback NAME from a shell, or as playback NAME inside the PHP shell; start a new PHP shell for each script.
| Command | What it does |
|---|---|
changepassword | Change a user's passwordAlso offers to reset the account properties when it is disabled or expired. |
disablecarp | Disable CARPDeactivates CARP virtual IPs until the next reboot; maintenance mode is the lasting option. |
enablecarp | Enable CARPBrings CARP high availability and its virtual IP addresses back. |
enablecarpmaint | Enter CARP maintenance modeKeeps CARP running but demotes this node so the peer takes over; it persists across reboots. |
disablecarpmaint | Leave CARP maintenance modeEnds the demotion that enablecarpmaint set on this node. |
disabledhcpd | Remove all DHCP server settingsDeletes the whole DHCP configuration rather than just stopping the service. |
disablereferercheck | Turn off the referer checkHelps when a browser session keeps tripping the GUI HTTP_REFERER protection. |
enablesshd | Enable the SSH daemonSame result as the console menu entry or the GUI setting. |
externalconfiglocator | Load config.xml from USBChecks external media like a USB stick and puts the file it finds in place. |
gatewaystatus | Show gateway statusPrints each gateway with its addresses and monitoring statistics. |
gatewaystatus brief | Show gateway status, short formOnly gateway names and their status, without addresses or statistics. |
gitsync | Sync scripts from GitHubFor CE development snapshots only, not Plus; run without parameters it prints its help. |
installpkg | Install a packageWorks like the GUI package manager; mostly used to debug package problems. |
listpkg | List installed packagesUseful for comparing config.xml entries with the package database. |
uninstallpkg | Remove a packageBehaves like removal in the GUI package manager. |
pfSsh.php playback pfanchordrill | Print rules in all anchorsReveals NAT and filter rules from UPnP, Captive Portal or packages that the GUI never shows. |
pftabledrill | Print all PF tablesIncludes alias tables and system tables such as bogons and the GUI/SSH lockout list. |
removepkgconfig | Remove package settingsClears every package entry from the running config.xml when a package left it inconsistent. |
removeshaper | Remove traffic shaper settingsDeletes the ALTQ shaper configuration when it stops the rules from loading. |
resetwebgui | Reset GUI preferencesReturns dashboard widgets, columns and the theme to defaults when the dashboard misbehaves. |
restartallwan | Restart all WAN interfacesTakes each WAN-type interface down and up again to reapply its settings. |
restartdhcpd | Restart the DHCP daemon |
restartipsec | Reload IPsecWrites the strongSwan configuration again and loads it. |
pfSsh.php playback svc stop miniupnpd | Stop a serviceNames come from Status > Services; quote a name that contains spaces. |
pfSsh.php playback svc restart openvpn client 2 | Restart an OpenVPN clientThe extra arguments pick one instance, here the OpenVPN client with ID 2. |
pfSsh.php playback svc start captiveportal MyZone | Start a Captive Portal zoneThe zone name selects which portal instance starts. |
Inspecting rules and states 10
| Command | What it does |
|---|---|
pfctl -sr | Show rulesPrints the filter rules as PF interpreted them, which can differ slightly from what the GUI generated. |
pfctl -sn | Show NAT rulesLists the translation rules exactly as PF loaded them. |
pfctl -sa | Show everythingOne long listing with rules, NAT, states, tables and counters together. |
pfctl -vvsr | Show rules with countersAdds rule numbers, tracking IDs and per-rule counters to the listing. |
pfctl -vvsr | grep 1000000103 | Find a rule by tracking IDTake the ID from a raw firewall log entry; 1000000103 here is the default IPv4 deny rule. |
pfctl -a '*' -sr | Show rules in every anchorPrints the main ruleset with all anchors expanded recursively. |
pfctl -s state | Show the state tableEach tracked connection appears with protocol, both addresses and ports, and direction. |
pfctl -s state -vv | Show states with their IDsThe detailed form includes the unique state ID that pfctl -k id expects. |
pfctl -s info | Show filter statisticsCounters include state mismatches, state-limit hits and dropped fragments. |
pfctl -vvsTables | Show tables with statisticsLists each table with its address count, rule references and pass or block counters. |
Controlling the packet filter 7
| Command | What it does |
|---|---|
pfctl -d | Disable firewallSwitches off all rules and NAT until the next ruleset reload, which almost any GUI save triggers. |
pfctl -e | Enable firewallTurns filtering back on once access has been restored after pfctl -d. |
pfctl -f /tmp/rules.debug | Reload rulesLoads the ruleset pfSense generated and prints any error, the quick test when rules fail to load. |
pfctl -k HOST | Kill states from a hostDrops every state that originates from the given host or network. |
pfctl -k HOST1 -k HOST2 | Kill states between two hostsNetworks work too, and 0.0.0.0/0 as the first value matches any source. |
pfctl -k label -k LABEL | Kill states by rule labelRemoves the states created by rules that carry that label. |
pfctl -k gateway -k GATEWAY | Kill states via a gatewayMatches states that route-to or reply-to send through that gateway; a network prefix also works. |
Firewall rules from the shell 5
| Command | What it does |
|---|---|
easyrule | Show EasyRule syntax |
easyrule pass INTERFACE PROTOCOL SOURCE DESTINATION [PORT] | Add a precise pass ruleThe port is needed only for TCP and UDP, and both addresses must be the same family. |
easyrule block INTERFACE SOURCE | Block a source addressAdds the address to an EasyRule alias that is blocked on that interface. |
easyrule showblock INTERFACE | List blocked addressesShows only the entries that EasyRule itself added on that interface. |
easyrule unblock INTERFACE SOURCE | Remove a blockWorks only on addresses EasyRule blocked; other block rules stay untouched. |
Regaining access 11
| Command | What it does |
|---|---|
pfSsh.php playback generateguicert | Make a new GUI certificateCreates a self-signed certificate, activates it and restarts the GUI web server. |
pfSsh.php playback enableallowallwan | Allow all traffic on WANA temporary way in when the LAN is unusable; remove the added rules once access is fixed. |
pfctl -T flush -t sshguard | Clear the login lockout tableUnblocks every address locked out after repeated failed GUI or SSH logins. |
/etc/rc.initial.password | Run the admin reset scriptThe way to reset the admin password from single user mode when the console is password protected. |
/sbin/reboot | Reboot from the shellLast step of the single user mode password reset. |
sockstat | grep nginx | Check the GUI web serverShows the running nginx processes and their ports when the GUI answers with a connection reset. |
/etc/rc.php-fpm_restart; /etc/rc.restart_webgui | Restart PHP-FPM and the GUIRestarts PHP-FPM, then the web GUI, for example after adding a PHP extension. |
usermgrwhoami | Show the current userPrints the User Manager details of the account you are logged in as. |
usermgrpasswd | Change a User Manager passwordWithout parameters it changes the password of the current user, admin. |
usermgrpasswd -c | Check for weak passwordsFlags known problem values such as the default password or one equal to the username. |
usermgrpasswd -u NAME | Pick the account to changeNames the user to check or change instead of the current one; works with -c too. |
Configuration file 6
| Command | What it does |
|---|---|
viconfig | Edit config.xml in viEdits the running configuration and clears the cache file after you save and exit. |
rm /tmp/config.cache | Clear the configuration cacheNeeded after editing /conf/config.xml with another editor; then reboot or reload the affected part. |
pfSsh.php playback cryptconfig encrypt INPUT OUTPUT | Encrypt a config backupAsks for a passphrase and uses the same method as encrypted GUI backups. |
pfSsh.php playback cryptconfig decrypt INPUT OUTPUT | Decrypt a config backupThe passphrase must match the one used for encryption exactly. |
pfSsh.php playback upgradeconfig | Rerun the config upgradeForces the running configuration through the upgrade steps again. |
pfSsh.php playback upgradeconfig /root/oldconfig.xml /root/newconfig.xml | Upgrade another config fileWrites the upgraded copy to the second file; afterwards check that the running configuration was not replaced. |
Logs 7
| Command | What it does |
|---|---|
cat /var/log/filter.log | View the firewall logLogs are plain text since Plus 21.02 and CE 2.5.0, so ordinary tools read them. |
grep -i "error" /var/log/system.log | Search the system logCase-insensitive match; change the pattern or pick another file under /var/log. |
tail -F /var/log/filter.log | Follow a log liveThe capital -F keeps following after the log rotates to a new file. |
bzcat /var/log/filter.log.0.bz2 | Read a rotated logRotated logs are bzip2 files by default; gzip, xz and zstd logs have their own tools. |
bzgrep -i "error" /var/log/system.log.0.bz2 | Search a rotated logSearches inside the compressed copy; zgrep, xzgrep and zstdgrep cover the other formats. |
tail -F /var/log/filter.log | filterparser.php | Follow the firewall log, simplifiedA low-detail live view, lighter to read than console option 10. |
cat /var/log/filter.log | filterparser.php | Print the firewall log, simplifiedOne line per entry: time, action, interface, protocol and both endpoints. |
Updates and packages 18
| Command | What it does |
|---|---|
pfSense-upgrade | Upgrade from a root shellSame as console option 13; the firewall reboots by itself when the update is done. |
pkg install screen | Install GNU screenUseful for watching an upgrade over an unstable SSH connection. |
rehash | Rescan the command path |
screen pfSense-upgrade | Upgrade inside screenNetgate's suggestion for upgrades over SSH when the link may drop. |
pfSense-upgrade -d -c | Check for updatesPrints whether a newer version exists and its number, or the errors that stop the check. |
pfSense-upgrade -4 | Upgrade over IPv4 onlyAvoids timeouts when the firewall would otherwise try a broken IPv6 path first. |
pkg-static update -f | Refresh package metadataErrors such as No address record or No route to host point to DNS or routing trouble. |
pkg-static -d update | Update metadata with debug outputShows each fetch attempt when the plain update gives no clear error. |
certctl rehash | Rebuild trusted certificatesFixes pkg failing to trust the package servers, until the next reboot. |
pkg-static bootstrap -f | Bootstrap pkg againFixes repository metadata version errors; it is interactive, so not for Diagnostics > Command. |
env ASSUME_ALWAYS_YES=yes pkg-static bootstrap -f | Bootstrap pkg without promptsThe variant for when only the GUI command prompt is available. |
pkg-static info -x pfSense-upgrade | Show the upgrade script versionConfirms that the newest pfSense-upgrade package has arrived before retrying an upgrade. |
pkg-static clean -ay; pkg-static install -fy pkg; pkg-static install -xfy pfSense-repo pfSense-upgrade | Reinstall pkg and the upgrade scriptCleans the repository, then reinstalls pkg, the repository data and pfSense-upgrade when no upgrade is offered. |
pkg-static upgrade -f | Reinstall every packageReview the list, confirm with y, then reboot the firewall by hand. |
/usr/local/sbin/pkg-static install -yf pkg pfSense pfSense-kernel-pfSense | Reinstall the CE base and kernelPart of repairing a corrupted pkg database on a typical CE installation. |
/etc/rc.php_ini_setup | Rebuild php.iniRefreshes php.ini and related files so the right PHP modules load. |
pkg search php | Search for PHP packagesFinds optional PHP extensions such as mysqli or pgsql that the base system leaves out. |
php -m | List enabled PHP modules |
Network diagnostics 7
| Command | What it does |
|---|---|
route -n get 8.8.8.8 | Show the route to an addressPrints the gateway and interface the system would use for that destination. |
netstat -rWn | Show the routing tablePrints the whole routing table; Netgate's example shows an OpenVPN tunnel's routes in it. |
tcpdump -ni igb1 -c 5 | Capture a few packetsStops after five packets; -n skips reverse DNS and -i takes a FreeBSD interface name. |
tcpdump -ni igb1 -e -c 5 | Capture with MAC addressesThe -e flag adds source and destination MAC addresses and any 802.1q VLAN tag. |
tcpdump -ni igb1 host 192.168.1.100 | Capture one host's trafficWrite src host or dst host instead to match a single direction. |
tcpdump -ni igb1 tcp port 80 | Capture one TCP portPort filters combine with host filters through and, or and not. |
tcpdump -ni enc0 | Capture IPsec tunnel trafficAll IPsec tunnels share the enc0 interface, so this shows what enters or leaves them. |
DNS Resolver cache 5
The -c option is required because Unbound on pfSense does not keep its configuration file in the default location.
| Command | What it does |
|---|---|
unbound-control -c /var/unbound/unbound.conf flush NAME | Flush a name from the cacheRemoves every record type for that name, from A and AAAA to MX, PTR and SRV. |
unbound-control -c /var/unbound/unbound.conf flush_type NAME TYPE | Flush one record typeLeaves the other record types of that name cached. |
unbound-control -c /var/unbound/unbound.conf flush_zone NAME | Flush a whole zoneSlow, since the entire cache is inspected; .com would drop every name below it. |
unbound-control -c /var/unbound/unbound.conf reload | Reload and empty the cacheReloads Unbound and empties the whole cache, unlike the targeted flush commands. |
unbound-control -c /var/unbound/unbound.conf lookup NAME | Show the servers for a zoneLists the name servers Unbound would query to resolve that zone. |
pfTop on the console 5
| Command | What it does |
|---|---|
pftop | Start pfTop from a shellThe output widens with the terminal, so a wider window shows extra columns. |
| h | Show pfTop helpExplains each key and view available while pfTop runs. |
0 ... 8 | Switch pfTop viewThe views are those described for the GUI, such as rules, size, speed and long-lived states. |
| Space | Force an immediate update |
| q | Quit pfTop |
No row on this page matches that filter.
Notes
The console menu
The numbered menu appears on the console after boot and after an SSH login. 1 assigns interfaces — the first step on new hardware, and the fix when a NIC change leaves WAN and LAN swapped — and 2 sets an interface's IP address and can enable DHCP on the LAN, which is how you regain web access after locking yourself out with a bad address. 5 reboots and 8 drops to a FreeBSD shell where pfctl and the rest live.
Reading the filter
pfctl -sr prints the active rule set as pf sees it, which is what to compare against the UI when a rule "should" match. pfctl -sn shows NAT rules and pfctl -s state the state table — every tracked connection — and pfctl -s info prints filter statistics and counters. Rules that packages, UPnP or Captive Portal add sit in anchors; pfSsh.php playback pfanchordrill prints them. pfctl -k HOST kills the states for a host, which forces existing connections to be re-evaluated after a rule change without restarting anything.
Disabling and reloading
pfctl -d disables packet filtering entirely — no rules and no NAT — which opens the GUI to any address but cuts off LAN clients that depend on NAT. It is a short recovery step, never a state to leave a machine in, and almost any GUI save reloads the ruleset and ends it. pfctl -e re-enables filtering. pfctl -f /tmp/rules.debug reloads the ruleset pfSense generated; hand edits to that file are overwritten at the next filter reload, so make persistent changes in the UI or through pfSsh.php, the PHP shell that changes the configuration directly.
Questions
Where are the rules that pfSense loads into pf?
In /tmp/rules.debug, which pfSense writes from its configuration. pfctl -f /tmp/rules.debug loads the file and prints any error; edits to it are lost at the next filter reload, so lasting changes belong in the GUI.
How do I get back into the GUI after a lockout?
At the console, 2 re-enables the LAN anti-lockout rule and can switch the GUI back to HTTP, and 3 resets the admin password. From a shell, pfctl -T flush -t sshguard clears addresses blocked after failed logins, and easyrule pass INTERFACE PROTOCOL SOURCE DESTINATION [PORT] lets one remote address in.
How do I run a playback script such as pftabledrill?
From a shell type pfSsh.php playback SCRIPTNAME, for example pfSsh.php playback pftabledrill; inside the PHP shell the same script is playback SCRIPTNAME. Run one script per PHP shell session, and never through Diagnostics > Command Prompt.
Why does pkg fail to fetch updates?
Run pkg-static update -f: errors such as No address record or No route to host point to DNS or a missing default route. If pkg does not trust the package servers, certctl rehash helps until the next reboot.
Sources and checks
- Netgate pfSense documentation (latest: Plus 26.07 / CE 2.9.0) — Console Menu Basics Console menu entries 0 to 16, the first-login password prompt and the filter log one-liner
- Netgate pfSense documentation — Using the PHP Shell pfSsh.php, PHP shell commands, playback scripts and their arguments
- Netgate pfSense documentation — Viewing the Firewall Rules Generated by pfSense pfctl rule, NAT and anchor listings
- Netgate pfSense documentation — Troubleshooting Firewall Rules Testing the generated ruleset with pfctl -f
- Netgate pfSense documentation — Troubleshooting Access when Locked Out of the Firewall Lockout recovery: pfctl -d and -e, the sshguard table, EasyRule, allow-all WAN rule, GUI certificate, single user password reset
- Netgate pfSense documentation — Firewall Logs filterparser.php and finding a rule by its tracking ID
15 more source pages
- Netgate pfSense documentation — Working with Log Files Reading, following and searching plain and rotated log files
- Netgate pfSense documentation — XML Configuration File viconfig and the configuration cache
- Netgate pfSense documentation — Upgrading using the Console pfSense-upgrade and running it inside screen
- Netgate pfSense documentation — Troubleshooting Upgrades pkg-static repair commands, update checks and certctl
- Netgate pfSense documentation — Troubleshooting a Broken pkg Database Reinstalling the CE base packages and php.ini setup
- Netgate pfSense documentation — Additional PHP Modules pkg search, php -m and restarting PHP-FPM and the GUI from the shell
- Netgate pfSense documentation — Troubleshooting GUI Access Checking the nginx GUI processes with sockstat
- Netgate pfSense documentation — Troubleshooting Routes route and netstat
- Netgate pfSense documentation — DNS Resolver CLI Commands unbound-control commands
- Netgate pfSense documentation — User Manager Shell Commands usermgrwhoami and usermgrpasswd
- Netgate pfSense documentation — EasyRule easyrule actions
- Netgate pfSense documentation — Using tcpdump on the command line tcpdump examples
- Netgate pfSense documentation — pfTop pfTop on the console and its keys
- Netgate pfSense documentation — Rebooting the Firewall Table note on console menu numbers
- FreeBSD Manual Pages — pfctl(8), FreeBSD 16.0-CURRENT (the base of pfSense Plus 26.07 and CE 2.9.0) pfctl state listings, state killing, anchors, statistics and tables, which the Netgate pages do not print
Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.