Runbook: Add an Interface

Purpose

This runbook brings a new interface online — physical, VLAN, or LAG — with a sane IP, a small initial firewall ruleset, and a tested rollback path. It is the runbook to reach for whenever a new zone needs to exist on the firewall: server segment, DMZ, guest, management, OT, etc.

When to use this runbook

Use this runbook when you need to add a new network segment to an OPNsense firewall and have already decided the IP plan, zone name, and trust level. It does not cover creating a VLAN on the parent interface (see opnsense-rb-add-vlan) or configuring Multi-WAN (see opnsense-rb-configure-multiw); use those runbooks for those specific changes.

Pre-checks

• Confirm the new interface is physically present and the link LED is on; ifconfig at the shell should show status: active on the new interface.
• Confirm there is no IP overlap with existing subnets configured on the OPNsense host.
• Confirm the planned zone name is unique and matches the firewall rule naming convention used elsewhere in the org.
• Capture a fresh encrypted config backup before any change; name it with the host, date, and intent (e.g. fw-edge-01-pre-add-opt2-2026-08-14.xml).

Procedure

1. Identify the interface name. From the console menu, option 1 lists interfaces with their OS names (e.g. igc1, vtnet2). You can also run ifconfig from the shell or via Diagnostics > Command Prompt.
2. Assign the interface. In the GUI, go to Interfaces > Assignments, pick the new interface from the Available network ports dropdown, click +, and Save. OPNsense renames it to OPT1 (or the next free OPT) automatically.
3. Enable and configure the new OPT interface. Click the new OPT entry to open its edit page. Check Enable interface. Leave Block private networks and Block bogons checked for WAN-side interfaces; uncheck only when the design requires routable addresses on a private segment.
4. Set the IPv4 address. Change IPv4 configuration type to Static IPv4 and enter the address and CIDR (e.g. 10.20.30.1/24). Leave IPv6 configuration type at None unless there is a concrete IPv6 plan.
5. Set the MTU. Keep 1500 for ordinary L2 segments. Lower it to 1492 for PPPoE uplinks, 1420 for WireGuard, or whatever the LAG/tunnel design specifies.
6. Apply. Click Save and then Apply changes. The interface is now administratively up; you should see it in the dashboard widgets.
7. Add a management allow rule first. Navigate to Firewall > Rules > [new interface] and add a pass rule from your mgmt_hosts alias to this firewall. This guarantees GUI access if subsequent ruleset work goes wrong.
8. Add the zone-appropriate baseline. If this is a trusted LAN-type zone, add a pass rule from lan_subnet to any (or to specific destinations). If it is a DMZ, add a default deny plus a narrow allow list referencing the upstream and downstream subnets only.
9. Add DHCP if needed. If clients need addresses on this segment, install the ISC DHCP server plugin and create a scope under Services > ISC DHCPv4 > [interface]. Set DNS to point at the OPNsense Unbound resolver.
10. Verify with pfctl. From Diagnostics > Command Prompt, run pfctl -sr | grep -A1 <opt_if_name>. You should see the ruleset you just added compiled into the PF table without errors.

Verification

• A host on the new subnet can ping the OPT interface IP and reach the OPNsense DNS resolver.
• ifconfig <opt_if> at the shell shows the configured address and status: active.
• A management host retains GUI access through the management allow rule.
• The Live View log (Firewall > Log Files > Live View, filter on the new interface) shows the expected pass/block decisions matching the rules you wrote.

Rollback

• Disable the interface (Interfaces > [OPT] > uncheck Enable) and apply; clients lose connectivity immediately but the rest of the firewall is unaffected.
• Remove the interface assignment (Interfaces > Assignments, click the X next to the OPT entry) and apply; the OPT slot is freed.
• Restore the pre-change encrypted config backup if anything beyond assignment was changed.
• Re-patch the switch port back to its prior VLAN or untagged access state if you changed upstream infrastructure.

Escalation

• Escalate to the platform team if the interface is not detected: the NIC driver may be missing, the NIC may be disabled in firmware, or the cable may be on the wrong physical port.
• Escalate to the network team if link is up but no traffic flows: suspect a switch port config mismatch (trunk vs access), an MTU mismatch, or spanning-tree blocking the port.
• Escalate to security if the planned zone was previously air-gapped and the new ruleset widens exposure beyond what was approved in the change record.