Skip to main content
RunBook Academy

← All break/fix scenarios in OPNsense

advancedIdentity / auth~30 min

Break/Fix: Locked Out of the Management Interface

Reported symptoms

  • ●Web UI stops responding on the management address
  • ●SSH connections to the management address are refused
  • ●You can no longer make changes through the documented access path

Evidence

  • · A recent rule change removed the source-allow rule for your management subnet
  • · A new TLS certificate replaced the one trusted by your browser
  • · lighttpd/sshd not bound to the management interface after a config change
Diagnosis and resolutionclick to reveal

Root cause

The most common cause is a firewall rule that blocks the management source after editing, followed by a TLS certificate change, then a service-binding change. OPNsense has built-in anti-lockout that prevents some of these on the LAN interface — but the anti-lockout is bypassed if you manage over a non-LAN interface or have moved it.

Remediation

1. Connect via physical console, IPMI/KVM, or serial console. 2. From the menu, choose option 8 (Shell). 3. Restore the rule by editing /conf/config.xml directly or via pfctl table restore. 4. Re-enable SSH or the listener. 5. Confirm from a known-good client before closing the console session. If certificate issue: regenerate the GUI cert from the console or restore the previous cert.

Verification

Web UI and SSH are reachable from the expected management source; the rule that triggered the lockout is corrected; the anti-lockout rule on LAN is left intact for future incidents.

Prevention

Never edit the management-source rule without a console session attached. Use a dedicated management VLAN with anti-lockout explicitly enabled. Test rule changes from a second source. Keep an out-of-band path (IPMI, serial, KVM) documented and verified. Snapshot config.xml before any access-list change.

Scenario

You are operating an OPNsense edge and a recent change has cut off your access. The following symptoms appear:

  • Web UI stops responding on the management address
  • SSH connections to the management address are refused
  • You can no longer make changes through the documented access path

Available evidence:

  • A recent rule change removed the source-allow rule for your management subnet
  • A new TLS certificate replaced the one trusted by your browser
  • lighttpd/sshd not bound to the management interface after a config change

Your task

Determine the cause, recover, document, and validate.

Investigation

The investigation follows the discipline taught in Part XXXIX:

  1. Form hypothesis, find evidence, test, validate.
  2. Use the available evidence above to bound the search.
  3. Reach one of the likely root causes.

Recovery procedure

(Do not reveal until you have reasoned through the problem.)

  1. Identify the failing component.
  2. Apply the remediation pathway.
  3. Validate with the verification step.
  4. Document the incident.

Remediation

  1. Connect via physical console, IPMI/KVM, or serial console. 2. From the menu, choose option 8 (Shell). 3. Restore the rule by editing /conf/config.xml directly or via pfctl table restore. 4. Re-enable SSH or the listener. 5. Confirm from a known-good client before closing the console session. If certificate issue: regenerate the GUI cert from the console or restore the previous cert.

Verification

Web UI and SSH are reachable from the expected management source; the rule that triggered the lockout is corrected; the anti-lockout rule on LAN is left intact for future incidents.

Rollback

If recovery makes things worse, restore /conf/backup/ from a known-good config.xml and reboot from console.

Prevention

Never edit the management-source rule without a console session attached. Use a dedicated management VLAN with anti-lockout explicitly enabled. Test rule changes from a second source. Keep an out-of-band path (IPMI, serial, KVM) documented and verified. Snapshot config.xml before any access-list change.