pfSense commands

Console menu numbers and shell commands for pfSense Plus 26.07 and pfSense CE 2.9.0, from Netgate's documentation plus the FreeBSD pfctl(8) manual. Menu rows are numbers typed at the console prompt; the rest run in the shell that 8 opens, or inside the PHP shell. Words in capitals are placeholders. GUI pages and package tools are left out, and pfctl -d or edits to the loaded ruleset last only until the next filter reload.

134 commands in 13 sections. Checked row by row against Netgate pfSense documentation (latest: Plus 26.07 / CE 2.9.0) on . Edited by Jay.

Console menu 17

The menu can differ slightly between versions and platforms, so check the number on screen; Netgate’s own reboot steps give option 5 only as an example.

On pfSense Plus 24.03 and later, the first console or SSH login after installation or a factory reset asks for a new admin password; press Ctrl + C to skip it if the password was already changed in the GUI.

CommandWhat it does
0Log out of SSHListed only when the menu was reached over SSH, not on the local or serial console.
1Assign interfacesReruns interface assignment; it can also create VLAN interfaces and assign newly added network cards.
2Set interface IP addressCan also turn DHCP on or off for that interface, switch the GUI back to HTTP and restore the LAN anti-lockout rule.
3Reset admin passwordRe-creates or re-enables the admin account if needed, can return logins to the local database, then asks for a new password.
4Reset to factory defaultsAlso tries to remove installed packages; the GUI offers the same reset under Diagnostics > Factory Defaults.
5Reboot the firewallThen asks for a reboot method, for example a normal reboot or the faster reroot.
6Halt the firewallShuts down cleanly, then halts or powers off as the hardware allows; the safe step before cutting power.
7Ping a hostSends three echo requests to the address you type, switching to ping6 for IPv6 targets.
8Open a shellStarts tcsh; sh is the only other shell installed, and many FreeBSD commands are missing.
9Open pfTopLive view of firewall states and the data each has moved, for spotting sessions that use the most bandwidth.
10Follow the raw filter logStreams firewall log entries as they arrive, with more fields per line than the GUI log view.
11Restart the GUIRestarts the nginx web server process; if the GUI still fails, use option 16 next.
12Open the PHP shellRuns PHP code inside the live system and gives access to the playback scripts.
13Upgrade from the consoleRuns pfSense-upgrade, the same process as a GUI upgrade, so the update server must be reachable.
14Toggle the SSH daemonTurns sshd on or off, exactly like the SSH setting in the GUI.
15Restore a recent configurationLists recent config history entries with time, user and change description, then restores the one you pick.
16Restart PHP-FPMFor a GUI whose web server runs but cannot execute PHP pages; pair it with option 11.

PHP shell 10

CommandWhat it does
pfSsh.phpPHP shellStarts the developer shell from a root prompt; the same shell as console option 12.
helpShow PHP shell helpPrints sample commands, such as printing a config section or saving with write_config().
execRun the entered linesLines typed before it are collected and run together as one set.
! COMMANDQueue a system shell commandMixes shell commands with PHP lines in the set that exec runs.
exitLeave the PHP shellExit after each playback script, since one session is not built to run several.
record NAMEStart recording a sessionSaves the commands that follow under that name, to replay later like a built-in script.
stoprecordingStop recordingCloses the recording that record started.
showrecordingsList recorded sessions
playback SCRIPTNAMERun a script inside the shellStart a fresh PHP shell for every further script, or later ones may fail.
pfSsh.php playback SCRIPTNAMERun 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.

CommandWhat it does
changepasswordChange a user's passwordAlso offers to reset the account properties when it is disabled or expired.
disablecarpDisable CARPDeactivates CARP virtual IPs until the next reboot; maintenance mode is the lasting option.
enablecarpEnable CARPBrings CARP high availability and its virtual IP addresses back.
enablecarpmaintEnter CARP maintenance modeKeeps CARP running but demotes this node so the peer takes over; it persists across reboots.
disablecarpmaintLeave CARP maintenance modeEnds the demotion that enablecarpmaint set on this node.
disabledhcpdRemove all DHCP server settingsDeletes the whole DHCP configuration rather than just stopping the service.
disablereferercheckTurn off the referer checkHelps when a browser session keeps tripping the GUI HTTP_REFERER protection.
enablesshdEnable the SSH daemonSame result as the console menu entry or the GUI setting.
externalconfiglocatorLoad config.xml from USBChecks external media like a USB stick and puts the file it finds in place.
gatewaystatusShow gateway statusPrints each gateway with its addresses and monitoring statistics.
gatewaystatus briefShow gateway status, short formOnly gateway names and their status, without addresses or statistics.
gitsyncSync scripts from GitHubFor CE development snapshots only, not Plus; run without parameters it prints its help.
installpkgInstall a packageWorks like the GUI package manager; mostly used to debug package problems.
listpkgList installed packagesUseful for comparing config.xml entries with the package database.
uninstallpkgRemove a packageBehaves like removal in the GUI package manager.
pfSsh.php playback pfanchordrillPrint rules in all anchorsReveals NAT and filter rules from UPnP, Captive Portal or packages that the GUI never shows.
pftabledrillPrint all PF tablesIncludes alias tables and system tables such as bogons and the GUI/SSH lockout list.
removepkgconfigRemove package settingsClears every package entry from the running config.xml when a package left it inconsistent.
removeshaperRemove traffic shaper settingsDeletes the ALTQ shaper configuration when it stops the rules from loading.
resetwebguiReset GUI preferencesReturns dashboard widgets, columns and the theme to defaults when the dashboard misbehaves.
restartallwanRestart all WAN interfacesTakes each WAN-type interface down and up again to reapply its settings.
restartdhcpdRestart the DHCP daemon
restartipsecReload IPsecWrites the strongSwan configuration again and loads it.
pfSsh.php playback svc stop miniupnpdStop a serviceNames come from Status > Services; quote a name that contains spaces.
pfSsh.php playback svc restart openvpn client 2Restart an OpenVPN clientThe extra arguments pick one instance, here the OpenVPN client with ID 2.
pfSsh.php playback svc start captiveportal MyZoneStart a Captive Portal zoneThe zone name selects which portal instance starts.

Inspecting rules and states 10

CommandWhat it does
pfctl -srShow rulesPrints the filter rules as PF interpreted them, which can differ slightly from what the GUI generated.
pfctl -snShow NAT rulesLists the translation rules exactly as PF loaded them.
pfctl -saShow everythingOne long listing with rules, NAT, states, tables and counters together.
pfctl -vvsrShow rules with countersAdds rule numbers, tracking IDs and per-rule counters to the listing.
pfctl -vvsr | grep 1000000103Find a rule by tracking IDTake the ID from a raw firewall log entry; 1000000103 here is the default IPv4 deny rule.
pfctl -a '*' -srShow rules in every anchorPrints the main ruleset with all anchors expanded recursively.
pfctl -s stateShow the state tableEach tracked connection appears with protocol, both addresses and ports, and direction.
pfctl -s state -vvShow states with their IDsThe detailed form includes the unique state ID that pfctl -k id expects.
pfctl -s infoShow filter statisticsCounters include state mismatches, state-limit hits and dropped fragments.
pfctl -vvsTablesShow tables with statisticsLists each table with its address count, rule references and pass or block counters.

Controlling the packet filter 7

CommandWhat it does
pfctl -dDisable firewallSwitches off all rules and NAT until the next ruleset reload, which almost any GUI save triggers.
pfctl -eEnable firewallTurns filtering back on once access has been restored after pfctl -d.
pfctl -f /tmp/rules.debugReload rulesLoads the ruleset pfSense generated and prints any error, the quick test when rules fail to load.
pfctl -k HOSTKill states from a hostDrops every state that originates from the given host or network.
pfctl -k HOST1 -k HOST2Kill states between two hostsNetworks work too, and 0.0.0.0/0 as the first value matches any source.
pfctl -k label -k LABELKill states by rule labelRemoves the states created by rules that carry that label.
pfctl -k gateway -k GATEWAYKill 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

CommandWhat it does
easyruleShow 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 SOURCEBlock a source addressAdds the address to an EasyRule alias that is blocked on that interface.
easyrule showblock INTERFACEList blocked addressesShows only the entries that EasyRule itself added on that interface.
easyrule unblock INTERFACE SOURCERemove a blockWorks only on addresses EasyRule blocked; other block rules stay untouched.

Regaining access 11

CommandWhat it does
pfSsh.php playback generateguicertMake a new GUI certificateCreates a self-signed certificate, activates it and restarts the GUI web server.
pfSsh.php playback enableallowallwanAllow all traffic on WANA temporary way in when the LAN is unusable; remove the added rules once access is fixed.
pfctl -T flush -t sshguardClear the login lockout tableUnblocks every address locked out after repeated failed GUI or SSH logins.
/etc/rc.initial.passwordRun the admin reset scriptThe way to reset the admin password from single user mode when the console is password protected.
/sbin/rebootReboot from the shellLast step of the single user mode password reset.
sockstat | grep nginxCheck 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_webguiRestart PHP-FPM and the GUIRestarts PHP-FPM, then the web GUI, for example after adding a PHP extension.
usermgrwhoamiShow the current userPrints the User Manager details of the account you are logged in as.
usermgrpasswdChange a User Manager passwordWithout parameters it changes the password of the current user, admin.
usermgrpasswd -cCheck for weak passwordsFlags known problem values such as the default password or one equal to the username.
usermgrpasswd -u NAMEPick the account to changeNames the user to check or change instead of the current one; works with -c too.

Configuration file 6

CommandWhat it does
viconfigEdit config.xml in viEdits the running configuration and clears the cache file after you save and exit.
rm /tmp/config.cacheClear the configuration cacheNeeded after editing /conf/config.xml with another editor; then reboot or reload the affected part.
pfSsh.php playback cryptconfig encrypt INPUT OUTPUTEncrypt a config backupAsks for a passphrase and uses the same method as encrypted GUI backups.
pfSsh.php playback cryptconfig decrypt INPUT OUTPUTDecrypt a config backupThe passphrase must match the one used for encryption exactly.
pfSsh.php playback upgradeconfigRerun the config upgradeForces the running configuration through the upgrade steps again.
pfSsh.php playback upgradeconfig /root/oldconfig.xml /root/newconfig.xmlUpgrade another config fileWrites the upgraded copy to the second file; afterwards check that the running configuration was not replaced.

Logs 7

CommandWhat it does
cat /var/log/filter.logView 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.logSearch the system logCase-insensitive match; change the pattern or pick another file under /var/log.
tail -F /var/log/filter.logFollow a log liveThe capital -F keeps following after the log rotates to a new file.
bzcat /var/log/filter.log.0.bz2Read 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.bz2Search a rotated logSearches inside the compressed copy; zgrep, xzgrep and zstdgrep cover the other formats.
tail -F /var/log/filter.log | filterparser.phpFollow the firewall log, simplifiedA low-detail live view, lighter to read than console option 10.
cat /var/log/filter.log | filterparser.phpPrint the firewall log, simplifiedOne line per entry: time, action, interface, protocol and both endpoints.

Updates and packages 18

CommandWhat it does
pfSense-upgradeUpgrade from a root shellSame as console option 13; the firewall reboots by itself when the update is done.
pkg install screenInstall GNU screenUseful for watching an upgrade over an unstable SSH connection.
rehashRescan the command path
screen pfSense-upgradeUpgrade inside screenNetgate's suggestion for upgrades over SSH when the link may drop.
pfSense-upgrade -d -cCheck for updatesPrints whether a newer version exists and its number, or the errors that stop the check.
pfSense-upgrade -4Upgrade over IPv4 onlyAvoids timeouts when the firewall would otherwise try a broken IPv6 path first.
pkg-static update -fRefresh package metadataErrors such as No address record or No route to host point to DNS or routing trouble.
pkg-static -d updateUpdate metadata with debug outputShows each fetch attempt when the plain update gives no clear error.
certctl rehashRebuild trusted certificatesFixes pkg failing to trust the package servers, until the next reboot.
pkg-static bootstrap -fBootstrap pkg againFixes repository metadata version errors; it is interactive, so not for Diagnostics > Command.
env ASSUME_ALWAYS_YES=yes pkg-static bootstrap -fBootstrap pkg without promptsThe variant for when only the GUI command prompt is available.
pkg-static info -x pfSense-upgradeShow 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-upgradeReinstall pkg and the upgrade scriptCleans the repository, then reinstalls pkg, the repository data and pfSense-upgrade when no upgrade is offered.
pkg-static upgrade -fReinstall every packageReview the list, confirm with y, then reboot the firewall by hand.
/usr/local/sbin/pkg-static install -yf pkg pfSense pfSense-kernel-pfSenseReinstall the CE base and kernelPart of repairing a corrupted pkg database on a typical CE installation.
/etc/rc.php_ini_setupRebuild php.iniRefreshes php.ini and related files so the right PHP modules load.
pkg search phpSearch for PHP packagesFinds optional PHP extensions such as mysqli or pgsql that the base system leaves out.
php -mList enabled PHP modules

Network diagnostics 7

CommandWhat it does
route -n get 8.8.8.8Show the route to an addressPrints the gateway and interface the system would use for that destination.
netstat -rWnShow the routing tablePrints the whole routing table; Netgate's example shows an OpenVPN tunnel's routes in it.
tcpdump -ni igb1 -c 5Capture a few packetsStops after five packets; -n skips reverse DNS and -i takes a FreeBSD interface name.
tcpdump -ni igb1 -e -c 5Capture with MAC addressesThe -e flag adds source and destination MAC addresses and any 802.1q VLAN tag.
tcpdump -ni igb1 host 192.168.1.100Capture one host's trafficWrite src host or dst host instead to match a single direction.
tcpdump -ni igb1 tcp port 80Capture one TCP portPort filters combine with host filters through and, or and not.
tcpdump -ni enc0Capture 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.

CommandWhat it does
unbound-control -c /var/unbound/unbound.conf flush NAMEFlush 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 TYPEFlush one record typeLeaves the other record types of that name cached.
unbound-control -c /var/unbound/unbound.conf flush_zone NAMEFlush a whole zoneSlow, since the entire cache is inspected; .com would drop every name below it.
unbound-control -c /var/unbound/unbound.conf reloadReload and empty the cacheReloads Unbound and empties the whole cache, unlike the targeted flush commands.
unbound-control -c /var/unbound/unbound.conf lookup NAMEShow the servers for a zoneLists the name servers Unbound would query to resolve that zone.

pfTop on the console 5

CommandWhat it does
pftopStart pfTop from a shellThe output widens with the terminal, so a wider window shows extra columns.
hShow pfTop helpExplains each key and view available while pfTop runs.
0 ... 8Switch pfTop viewThe views are those described for the GUI, such as rules, size, speed and long-lived states.
SpaceForce an immediate update
qQuit pfTop

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

15 more source pages

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.