Runbook: Create a Firewall Rule

Purpose

This runbook walks through authoring and placing a single PF firewall rule on the right interface, in the right order, with verification you can trust and a rollback you can actually run. It applies to everyday allow/deny changes that do not deserve a full Multi-WAN or port-forward runbook.

When to use this runbook

Use this runbook when you need to add a single allow or block rule between two specific sources/destinations, on an existing OPNsense interface, and you already know the protocol and port. It does not cover port-forwarding (see opnsense-rb-troubleshoot-port-forward), outbound NAT policy (see opnsense-rb-troubleshoot-outbound-nat), or floating rules with advanced matchers.

Pre-checks

• Confirm the change is approved and recorded in the change management system.
• Confirm the source and destination addresses/aliases are correct and routable from OPNsense.
• Capture a fresh encrypted config backup before any change; name it with intent (e.g. fw-edge-01-pre-allow-jenkins-2026-08-14.xml).
• Open Firewall > Log Files > Live View so you can see new traffic in real time during validation.

Procedure

1. Pick the right interface. Inbound traffic is matched against the rules on the interface the traffic arrives on. Open Firewall > Rules and select that interface. There is no need to add rules on outbound interfaces for traffic destined to networks behind them.
2. Add the rule. Click the + icon in the top-right. Leave Action as Pass unless you intentionally want Block (silent drop) or Reject (ICMP unreachable back to source).
3. Decide Quick vs not. Keep Apply immediately (default) for normal rules. Uncheck Quick only when you deliberately want a later rule above to override this one — this is rare and surprising; document it in the change record when you do.
4. Confirm Interface and Direction. Set Interface to the correct one; pick any only when you intend this to apply on every interface (use a floating rule instead if you need matchers Quick cannot express). Set Direction to in for traffic entering OPNsense, out for traffic generated by OPNsense itself.
5. Pick the IP family and protocol. Choose TCP/IP Version (IPv4, IPv6, or IPv4+IPv6); avoid IPv4+IPv6 unless your IPv6 design matches. Pick Protocol (TCP, UDP, TCP/UDP, ICMP, any); be specific — any is almost never correct.
6. Set Source and Destination. Use Single host or network for ad-hoc values and Alias for any group you reuse elsewhere. Set Destination port range explicitly (e.g. 443, or 8000 to 8100); for non-port protocols (ICMP, OSPF, etc.), leave the port fields blank.
7. Enable logging while validating. Set Log to Enable while you test. Disable it later once traffic behaves as expected — high-volume logged traffic is dropped at very high volumes and slows the log subsystem.
8. Save and Apply. Click Save then Apply changes. Saved-but-not-applied rules are not active.
9. Place the rule correctly. PF evaluates rules top-down on the matching interface; the first match wins. If a broader rule above catches the same traffic, this new rule will never match. Drag it above the broader rule, or scope it tighter so it does not collide.
10. Trigger the traffic. From a host matching the source, run the actual flow (curl, nc, ping, browser). In Live View, set the filter to your destination port and watch the action. A pass appears green; a block appears red.
11. Toggle-disable to confirm. The strongest single check is to temporarily click Disable on your rule, apply, run the same flow, and see it stop working. Then re-enable and confirm it resumes. This catches a hidden broader rule above yours.

Verification

• Trigger traffic from the source to the destination and see the new rule match in Live View with the expected Pass action.
• At the shell, pfctl -sr | grep -B1 -A1 <destination_ip> shows the new rule in the expected position.
• Reverse-direction traffic (e.g. from destination back to source) is handled by the matching state (default) and is not silently blocked.
• The toggle-disable test confirms the rule is what is allowing the traffic, not a stale rule above it.

Rollback

• Disable the rule. Toggle the Disable checkbox on the rule and apply; traffic reverts to the prior default behavior within a second.
• Remove the rule. Click the trash icon on the rule and apply; the ruleset reverts to the prior compile state.
• Restore the prior ruleset. For a full ruleset regression, restore the pre-change encrypted config backup from System > Configuration > Backups.
• Document. Record the rollback in the change record so the audit trail reflects what was undone.

Escalation

• Escalate immediately if a Pass any/any rule was committed in error. This almost always warrants an immediate rollback and a post-mortem because it bypasses the entire ruleset.
• Escalate to the network team if the rule matches but traffic still fails: suspect asymmetric routing, missing route-to, or upstream filtering.
• Escalate to the application owner if a previously working application breaks after a new rule is placed above it; do not reorder or remove other teams’ rules without coordination.
• Open a security ticket if the new rule allows inbound traffic from the public internet to an internal service without the matching change record approval.