OPNsense Edge Build Runbook

Related pages

Overlaps with the CLI/API-oriented OPNsense setup runbook and the OPNsense reference.

A step-by-step guide to building the corporate edge OPNsense HA pair in the OPNsense GUI. It implements the design in net-design/OPNSENSE.md and net-design/DESIGN.md §6 — this document is the how, those are the why. Section references like "§3", "§5c" point at OPNSENSE.md unless prefixed DESIGN.

This is the corporate pair only

The guest OPNsense (DESIGN §8) is a separate box with its own config domain. Nothing here applies to it.

What you're building

Two identical OPNsense nodes (FW-01, FW-02) in a CARP HA pair at the colo:

• Dual core — each node eBGP to both colo CCRs over routed /31s (ECMP).
• Dual WAN — each node eBGP to both upstream border routers over routed /31s.
• CARP-gated FRR — only the CARP master speaks BGP; the backup's FRR is stopped, so routing is symmetric with no prepend hacks (§3).
• Server-room zone firewall — every routed server VLAN gateways here; east-west crosses a stateful, logged firewall (zero-trust, DESIGN §7.2).
• Stateful HA — pfSync over a redundant 1G bond; XMLRPC config sync master→backup.
• Services — outbound NAT, DHCP for server VLANs, ACME GUI cert, Zabbix + SNMP monitoring over OOB, Suricata inline IPS on WAN/DMZ feeding Wazuh.

graph TD
    subgraph Upstream["WAN business (AS 204258)"]
      B1[border bdr-1]
      B2[border bdr-2]
    end
    subgraph Core["Colo core (AS 65500)"]
      C1[CR-COLO-01]
      C2[CR-COLO-02]
    end
    subgraph Pair["OPNsense pair (AS 65510, CARP)"]
      F1[FW-01 primary]
      F2[FW-02 secondary]
    end
    VM[VM CRS326 MLAG pair]
    OOB[OOB switch]
    B1 & B2 --- F1 & F2
    C1 & C2 --- F1 & F2
    F1 === VM
    F2 === VM
    F1 -. pfSync 2×1G RJ45 direct .- F2
    F1 & F2 --- OOB

Build order

Follow the pages in order. Each is a self-contained checklist; later pages assume the earlier ones are done.

#	Page	Node(s)	Outcome
1	Prerequisites	—	Cabling, images, addresses decided
2	Base install & assignment	both	OS installed, interfaces assigned + addressed
3	Interfaces, VLANs & VIPs	both	LAGG, VLANs, CARP VIPs
4	HA (CARP + pfSync)	both	State + config sync working
5	Routing — FRR / BGP	primary¹	Core + WAN sessions, CARP-gated
6	NAT	primary¹	Outbound PAT, 1:1, reflection
7	Firewall & zones	primary¹	Zone rules
8	OOB management	both	22/443 in, no transit
9	Services	both/primary	DHCP, ACME, Zabbix, IDS
10	Tunables	both	Performance baseline
11	Verification & cutover	—	Prove it, then go live

¹ After HA config sync is on (page 4), configure the primary only — XMLRPC replicates to the backup. Per-node items (addressing, OOB, tunables) are done on both because sync does not carry them. Each page states which.

Conventions used throughout

• <PLACEHOLDER> — a value you must fill from your own plan. All of them are collected in Site values — decide them once there, then substitute as you go.
• GUI paths are written as Menu ▸ Submenu ▸ Field.
• Save vs Apply — OPNsense stages most changes on Save and only commits them on a separate Apply. Where a wrong Apply can lock you out, the step says so and tells you to take a savepoint first.

Take a savepoint before firewall/interface Applies

OPNsense can revert config automatically if you get locked out. Before applying interface or firewall changes remotely, use System ▸ Configuration ▸ Backups to snapshot, and keep a BMC/KVM session open as break-glass. This is the firewall equivalent of RouterOS safe-mode.