Runbook: Deploy a New OPNsense Firewall

Purpose

This runbook deploys a new OPNsense firewall end-to-end, from the installer media to a verified baseline on the network. It covers the first-boot console assignment, the GUI setup wizard, baseline hardening, and a config backup that becomes the recovery point for every subsequent change.

When to use this runbook

Use this runbook when a brand-new OPNsense host is being installed at a network edge, branch office, lab boundary, or DMZ choke point where no prior config exists. It is the starting point for every downstream runbook in this set: do not skip the backup step at the end, because rollback procedures elsewhere assume a known baseline.

Pre-checks

• Confirm host hardware is on the OPNsense HCL or is a supported VM configuration (NIC, CPU, storage controller).
• Verify the installer checksum against the signed release on opnsense.org; do not deploy an unverified image to a production role.
• Confirm the WAN medium is up: modem/ONT link lights, patch lead is in the documented port, ISP hand-off is active.
• Document the planned LAN IP, CIDR, management admin password, and timezone in the change record before starting.
• Capture the prior state of any device being replaced: existing gateway IP, MAC table, and any client static routes.

Procedure

1. Boot from installer media. Attach the USB stick or attach the ISO to a VM, boot, and at the loader menu pick Install (ZFS) on capable hardware (mirrored pair preferred) or Install (UFS) for simpler single-disk installs. Choose guided partitioning for production hosts.
2. Complete the installer. Accept the license, set keyboard layout, hostname (e.g. fw-edge-01), domain (e.g. corp.example.com), and a strong root password. The installer will write the bootloader and prompt for a reboot.
3. Assign WAN and LAN at the console. After reboot, log in as root and pick option 1 (Assign interfaces). Note the detected NIC list; pick the WAN interface first, the LAN second. OPNsense generates an anti-lockout rule on the LAN only when LAN is assigned — never skip this step.
4. Set LAN addressing at the console. Choose option 2 to set the LAN IP and mask (e.g. 192.0.2.1/24). Decline IPv6 track interface unless you have a concrete plan for IPv6 on this segment.
5. Set WAN addressing at the console. Choose option 2 for the WAN interface and pick DHCP, static, or PPPoE. Confirm with ifconfig <wan_if> that an address is present and netstat -rn shows a default route via the WAN gateway.
6. Reach the GUI from a trusted management host. Plug a laptop directly into the LAN port with a static address in the LAN subnet, browse to https://<lan_ip>, accept the self-signed cert, and log in as root with the console password.
7. Run the setup wizard. Set timezone (correct this before NTP matters), change the admin password (rotate off the installer root), pick Unbound in resolver mode unless split-horizon is required, and enable the default block-private-networks and block-bogon rules on WAN.
8. Patch to current. Open System > Firmware > Status, click Check for updates, apply patches, and reboot if the kernel changed. Re-verify the GUI is reachable after any kernel reboot.
9. Disable noise. Turn off cron mail on misconfig (System > Settings > Cron), leave Intrusion Detection off until tuned, and leave Unbound DNS on but restrict access to LAN and the management alias (Services > Unbound > Access Lists).
10. Tighten the GUI. System > Settings > Administration: restrict the WebGUI source to a mgmt_hosts alias, set session timeout to a small value (e.g. 20 minutes), enable HTTPS-only, and consider changing the listen port off 443 if exposure scanners are noisy.
11. Capture the baseline backup. System > Configuration > Backups: download an encrypted backup named fw-edge-01-baseline-<date>.xml. Record the installer version, uname -a output, pkg info output, and the change record number in the same directory as the backup.

Verification

• From a LAN host, ping -c 3 8.8.8.8 returns 0% loss.
• At the OPNsense shell, pfctl -sr | head shows the default LAN anti-lockout rule, the default block on WAN, and your management allow rule.
• The Web GUI is reachable only from the management alias; an attempted login from an unmanged LAN host is rejected at the rule layer, not the GUI.
• Firmware status page shows “up to date” and matches the last_verified version in the frontmatter.
• The encrypted config backup file is present in the change record and decodes with the documented passphrase.

Rollback

• Reboot to the installer media and select Restore previous install if you enabled ZFS boot environments; otherwise, re-image from the baseline ISO.
• Restore the captured previous device (or its gateway IP) to the segment so downstream hosts are not stranded without a default route.
• If WAN or LAN cabling was re-patched, return patch panel ports to the documented baseline.
• Open a rollback incident and attach the failed config backup; do not delete evidence until the post-mortem closes.

Escalation

• If the installer does not detect a NIC, escalate to the platform team: OPNsense 25.x ships a small set of FreeBSD 14 drivers; unsupported NICs require an add-in card from the supported list.
• If WAN never obtains an address after 5 minutes on DHCP, involve the ISP: confirm the modem is in bridge mode, check PPPoE credentials if applicable, and request a line-side check.
• If the GUI is unreachable after anti-lockout, use the console menu option Reset web GUI access and re-establish a temporary laptop connection directly to the LAN port.
• If a critical CVE is active for the released version, escalate to the security team before proceeding; do not deploy an unpatched image to a perimeter role.