FreeBSD 15: pf ruleset lockout after remote firewall change

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

SSH access drops immediately after pf reload, causing production outage and emergency console dependency.

Environment & Reproduction

Happens when rule ordering, interface macros, or state handling changes during live firewall edits.

Root Cause Analysis

A deny rule or incorrect anchor placement overrides management allow rules and blocks return traffic.

Quick Triage

Use out-of-band console, check active rules and states, and confirm interface names in the loaded ruleset.

Step-by-Step Diagnosis

Compare intended and active pf rules, inspect logs, and identify the first rule dropping management traffic.

Solution – Primary Fix

Load a tested fallback ruleset with explicit management allow rules before applying stricter filters.

Solution – Alternative Approaches

Use pf anchors with staged activation or deploy rule changes through automatic timeout-based rollback.

Verification & Acceptance Criteria

Remote management remains stable, expected service ports pass, and blocked traffic matches policy intent.

Rollback Plan

Restore prior pf.conf and reload firewall from console if any critical path becomes unreachable.

Prevention & Hardening

Adopt pre-deployment rule linting, canary rollout, and mandatory break-glass access validation.

Related Errors & Cross-Refs

Often appears with CARP failover misrules, NAT regressions, and interface rename changes.

Related tutorial: View the step-by-step tutorial for freebsd-15.

View all freebsd-15 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

pf.conf man page, FreeBSD firewall handbook chapter, and operational runbooks for remote changes.