Runbook: Respond to Lockout
1 · Prerequisites
Confirm every item is in place before any state change.
- Console or IPMI access to the firewall (this is the single most important prerequisite)
- A second trusted management path if the GUI is on the locked-out interface
- Knowledge of the management IP and the management interface
2 · Pre-checks
Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.
- · Confirm the lockout is on the GUI and not on a downstream service
- · Capture the management IP and the management interface from the local console
- · Identify the rule that caused the lockout (typically a recent rule change on the management interface)
- · If the appliance is in an HA pair, confirm the peer appliance is still reachable on the management network
3 · Procedure
Execute each step in order. Verify the expected output of a step before moving to the next.
- 1Connect to the firewall via the console or IPMI and log in as the local administrator
- 2From the shell, run
pfctl -sr | grep -i <interface>to identify the rule that is blocking the GUI traffic - 3If the lockout is on the management interface, add a temporary pass rule on the management interface via the shell with
pfctl -f /tmp/permit-gui.conf - 4If the lockout is on a downstream interface, disable the offending rule from the console using
configctl filter rule disable <id> - 5If the lockout is on the WAN interface, reset the WAN rules to the default by restoring the previous configuration from System > Configuration > Backups
- 6After the GUI is reachable from the trusted management network, edit the rule that caused the lockout and save the corrected version
- 7If the appliance is in an HA pair, confirm the corrected configuration is replicated to the peer
- 8Audit the recent rule changes for any other rules that could cause a similar lockout
- 9Update the change record with the lockout cause, the recovery steps, and the operator name
4 · Verification
Confirm the procedure actually fixed the problem.
- ✓The GUI is reachable from the trusted management network
- ✓The firewall log shows the GUI traffic being permitted on the management interface
- ✓The peer appliance in an HA pair reflects the corrected configuration
- ✓No new lockout risk is introduced by the corrected rule
5 · Rollback
If verification fails, undo the procedure in reverse order.
- ↶If the temporary pass rule becomes a permanent rule, remove it after the lockout is resolved
- ↶If the configuration restore causes a regression, restore the previous backup
- ↶If the appliance is unreachable, rebuild the configuration from the console
6 · Escalation
When the runbook isn't enough, contact:
- · Engage the platform team if the console access is also unavailable (this is a critical situation)
- · Engage the security team if the lockout was caused by a suspected compromise
- · Engage the on-call engineer if the lockout extends to the peer appliance and the HA pair is in a split-brain
Purpose
Recover from a configuration change that has locked the operator out of the OPNsense GUI, then identify and fix the rule that caused the lockout.
When to use this runbook
Use this runbook when a recent rule change has blocked the GUI from the trusted management network, when a password reset has failed, or when the WAN interface has been locked out by a rule change.
Pre-checks
Before starting the procedure, confirm the prerequisites and pre-checks are met. The structured lists are rendered from the frontmatter by the page layout.
Procedure
Follow the steps from the frontmatter procedure steps. The page layout renders the steps as a checklist with copy-to-clipboard affordances.
Verification
After the procedure, the structured verification items from the frontmatter are rendered as a checklist.
Rollback
If the procedure fails or makes things worse, follow the structured rollback steps from the frontmatter.
Escalation
The structured escalation path is rendered from the frontmatter. Use it if the operator cannot complete the procedure safely.