Netgate is offering COVID-19 aid for pfSense software users, learn more.
What to do when locked out of the WebGUI¶
Under certain circumstances an administrator can be locked out of the pfSense® WebGUI. Don’t be afraid if this happens; there are a number of ways to regain control. Some methods are a little tricky, but it is nearly always possible to recover access. The worst-case scenarios require physical access, as anyone with physical access can bypass security measures.
Let the tactics in this section be a lesson. Physical security of a firewall is critical, especially in environments where the firewall is physically located in a common area accessible to people other than authorized administrators.
Before taking any of these steps, try the default credentials:
The firewall administrator password can easily be reset using the firewall
console if it has been lost. Access the physical console (Serial or
Keyboard/Monitor) and use option
3 to reset the WebGUI password. This option
can also reset the admin account if it has been disabled or expired.
After resetting the password, the
admin user can login with the default
Forgotten Password with a Locked Console¶
If the console is password protected, all is not lost. It takes two reboots to accomplish, but the password can be reset with physical access to the console:
Reboot the pfSense firewall
Choose the Boot Single User option (
2) from the loader menu (the one with the ASCII pfSense logo)
enterwhen prompted to start
Remount all partitions as rewritable:
# /sbin/mount -a -t ufs
Run the built-in password reset command:
Follow the prompts to reset the password
When the firewall reboots, the
admin user can login with the default
HTTP vs HTTPS Confusion¶
Ensure the client is connecting with the proper protocol, either HTTP or HTTPS. If one doesn’t work, try the other. If the GUI has not been configured correctly, the firewall may be running the GUI on an unexpected port and protocol combination, such as:
To reset this from the console, reset the LAN interface IP Address, enter the same IP address, and the script will prompt to reset the WebGUI back to HTTP.
Blocked Access with Firewall Rules¶
If a remote administrator loses access to the WebGUI due to a firewall rule change, then access can still be obtained from the LAN side. The LAN rules cannot prevent access to the GUI unless the anti- lockout rule is disabled. The anti-lockout rule ensures that hosts on the LAN are able to access the WebGUI at all times, no matter what the other rules on the LAN interface block.
Having to walk someone on-site through fixing the rule from the LAN is better than losing everything or having to make a trip to the firewall location!
Remotely Circumvent Firewall Lockout with Rules¶
There are a few ways to manipulate the firewall behavior at the shell to regain access to the firewall GUI. The following tactics are listed in order of how easy they are and how much impact they have on the running system.
Add a rule with EasyRule¶
The easiest way, assuming the administrator knows the IP address of a remote
client PC that needs access, is to use the
easyrule shell script to add a
new firewall rule. In the following example, the
easyrule script will allow
access on the WAN interface, from
x.x.x.x (the client IP address) to
y.y.y.y (presumably the WAN IP address) on TCP port
# easyrule pass wan tcp x.x.x.x y.y.y.y 443
easyrule script adds the rule, the client will be able to access
the GUI from the specified source address.
Add an allow all WAN rule from the shell¶
Another tactic is to temporarily activate an “allow all” rule on the WAN to let a client in.
An “allow all” style rule is dangerous to have on an Internet-connected WAN interface. Do not forget to remove the rule added by this script
To add an “allow all” rule to the WAN interface, run the following command at a shell prompt:
# pfSsh.php playback enableallowallwan
Once the administrator regains access and fixes the original issue preventing them from reaching the GUI, remove the “allow all rule” on WAN.
Disable the Firewall¶
An administrator can (very temporarily) disable firewall rules by using the physical console or SSH.
This completely disables
pf which disables firewall rules and
NAT. If the network run by this firewall relies on NAT to function, which
most do, then running this command will disrupt connectivity from the LAN to
To disable the firewall, connect to the physical console or ssh and use option
8 to start a shell, and then type:
# pfctl -d
That command will disable the firewall, including all NAT functions. Access to the WebGUI is now possible from anywhere, at least for a few minutes or until a process on the firewall causes the ruleset to be reloaded (which is almost every page save or Apply Changes action). Once the administrator has adjusted the rules and regained the necessary access, turn the firewall back on by typing:
# pfctl -e
Manual Ruleset Editing¶
The loaded ruleset is retained in
/tmp/rules.debug. If the administrator is
familiar with PF ruleset syntax, they can edit that file to fix the connectivity
issue and reload those rules:
# pfctl -f /tmp/rules.debug
After getting back into the WebGUI with that temporary fix, the administrator
must perform whatever work is required in the WebGUI to make the fix permanent.
When the rules are saved in the WebGUI, the temporary edit to
/tmp/rules.debug will be overwritten.
Remotely Circumvent Firewall Lockout with SSH Tunneling¶
If remote access to the WebGUI is blocked by the firewall, but SSH access is allowed, then there is a relatively easy way to get in: SSH Tunneling.
If the WebGUI is on port 80, set the SSH client to forward local port
4443, or another port) to remote port
localhost:443. If the firewall
WebGUI is on another port, use that as the target instead. Then point the
https://localhost. Add the port to the end of the URL if it
differs from the default 443, for example
https://localhost:4443. If the
GUI is using HTTP, change the protocol on the URL to
Fill out the options as shown in Figure Setting Up a Port 80 SSH Tunnel in PuTTY, then click Add.
Once the client connects and authenticates, the WebGUI is accessible from the redirected local port.
Locked Out Due to Squid Configuration Error¶
If a firewall administrator accidentally configures Squid to use the same port as the WebGUI, it can cause a race condition for control of the port, depending on which service (re)starts at a particular time. If Squid manages to get control of the port that the WebGUI wants, then the WebGUI will not be accessible to fix the configuration.
The following procedure may help to regain control.
Connect to the pfSense firewall console with SSH or physical access
Start a shell, option
8from the console.
Terminate the squid process:
# /usr/local/etc/rc.d/squid.sh stop
If that doesn’t work, try this command instead:
# killall -9 squid
# squid -k shutdown
Once the squid process is fully terminated, use console menu option
restart the WebGUI process, and then attempt to access the WebGUI again.
Work quickly or repeat the shutdown command, as squid may be automatically restarted by its internal monitoring scripts depending on the method used to stop the process.