OPNsense WAN DHCP failure after a MAC address or ISP lease change

Symptoms

The OPNsense WAN interface no longer receives the expected ISP DHCP lease. The firewall may show no WAN address, a stale lease, repeated DHCPDISCOVER attempts, no default route, or a private modem/gateway address when the site expects a public or provider-routed address.

Environment

OPNsense running on physical hardware or as a VM on Proxmox, VMware, Hyper-V, or another hypervisor, with WAN DHCP provided by an ISP modem, ONT, gateway, bridge-mode device, passthrough device, or upstream access network that may bind service to a client MAC address.

Most Likely Causes

WAN DHCP failures in this scenario commonly come from ISP MAC binding, a changed virtual NIC MAC, a stale upstream lease, a modem or ONT that has not accepted the new client identity, the wrong OPNsense interface assigned as WAN, missing VLAN tagging, a hypervisor bridge or port group change, cable/ONT provisioning behavior, or ISP gateway bridge/passthrough mode. Treat this as a WAN path, MAC identity, VLAN, and DHCP evidence problem before rebuilding firewall or NAT rules.

What to Check First

1. Record OPNsense version, WAN interface name, MAC address, link state, IPv4 mode, current WAN address, gateway status, and default route.
2. Confirm WAN is configured for DHCP and not PPPoE, static, LTE/cellular, or an ISP-specific managed handoff.
3. Compare the OPNsense WAN MAC with the hypervisor virtual NIC MAC and any MAC registered with or previously seen by the ISP.
4. Check whether a VM migration, restore, clone, NIC model change, hypervisor upgrade, or network adapter replacement changed the vNIC MAC.
5. Check OPNsense DHCP client logs for discover, offer, request, ack, nak, timeout, or lease rejection evidence.
6. Check interface link state, speed/duplex where visible, error counters, VLAN tag configuration, hypervisor bridge or port group mapping, and physical uplink state before assuming MAC lock.
7. Confirm whether the modem, ONT, or ISP gateway is in bridge, router, passthrough, or CGNAT mode and whether it requires a power cycle or ISP provisioning reset after a MAC change.
8. Verify LAN clients still have local connectivity so you do not confuse LAN DHCP with WAN DHCP.
9. Check for CARP/HA, multi-WAN, gateway monitoring, policy routing, or virtual MAC behavior before interpreting a MAC mismatch as a fault.

Fix Steps

1. Confirm prerequisites and export the configuration before remediation

   This is the pre-change checkpoint. Do this before any MAC clone, DHCP renewal, interface reassignment, modem/ONT power cycle, or hypervisor NIC modification. The backup step creates a configuration export but should not change firewall behavior. The OPNsense backup UI path should be human-reviewed for the supported OPNsense versions in your environment.

   Example pattern only. Adjust for your environment before running.

   OPNsense UI, human-review path: System > Configuration > Backups
   Download or Export the current configuration backup
   Record: OPNsense version, WAN interface name, WAN MAC, hypervisor vNIC MAC, VLAN tag, current WAN IP, default gateway, and ISP circuit/account reference

   Expected output:

   You have a downloaded OPNsense configuration file, a timestamped incident note, and the original WAN identity values. Example evidence row: timestamp=2026-05-09T21:00:00Z, opnsense_version=<version>, wan_if=<wan_interface>, wan_mac=aa:bb:cc:dd:ee:ff, hv_vnic_mac=aa:bb:cc:dd:ee:ff, vlan=<none-or-id>, wan_ip=<none-or-current-ip>, gateway=<gateway-or-none>, approval=<ticket/change-id>.

   Rollback or backout:

   No network behavior should be changed by exporting the configuration. If you cannot obtain a backup, original MAC values, approval, and console access, stop before remediation.

2. Capture current WAN identity and routing evidence without changing state

   Use the UI first, then shell commands only if shell access is already approved. This pass establishes whether the issue is link, addressing, or routing. The shell commands are common FreeBSD-style diagnostics but remain command-review-needed for your supported OPNsense versions.

   Example pattern only. Adjust for your environment before running.

   OPNsense UI: Interfaces > Overview
   OPNsense UI: Interfaces > Assignments
   OPNsense UI: Interfaces > WAN
   Shell, read-only, human-review-needed: ifconfig
   Shell, read-only, human-review-needed: netstat -rn

   Expected output:

   Healthy examples: WAN UI shows link up, IPv4 Configuration Type DHCP, MAC aa:bb:cc:dd:ee:ff, IPv4 address 198.51.100.25/24 or another expected ISP address. ifconfig example fields: <wan_interface>: flags=...<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST>..., ether aa:bb:cc:dd:ee:ff, inet 198.51.100.25 netmask 0xffffff00 broadcast 198.51.100.255, status: active. Route example from netstat -rn: default 198.51.100.1 UGS <wan_interface>. Unhealthy examples: status no carrier, no inet address on WAN, default route missing, default route pointing to the wrong interface, or WAN address in an unexpected modem/private range such as 192.168.100.x or 192.168.1.x when bridge mode/public handoff is required.

   Rollback or backout:

   No change is made in this step. If the WAN link is down, stop DHCP remediation and fix link, VLAN, bridge, port group, or cabling evidence first.

3. Review DHCP client and system logs without starting packet capture

   This step is only for viewing existing logs. Do not restart DHCP, renew a lease, or start packet capture here. The shell log path and process names are plausible but must be human-reviewed against your OPNsense version; use the UI log view as the primary source until validated.

   Example pattern only. Adjust for your environment before running.

   OPNsense UI, human-review path: System > Log Files > General
   OPNsense UI, human-review path: Interfaces or System log views filtered for DHCP client messages
   Shell, read-only, human-review-needed: grep -iE 'dhclient|dhcp|DHCPOFFER|DHCPACK|DHCPNAK|DHCPDISCOVER|DHCPREQUEST' /var/log/system/latest.log

   Expected output:

   Healthy DHCP sequence examples may look like: DHCPDISCOVER on <wan_interface> to 255.255.255.255 port 67 interval <n>; DHCPOFFER from 198.51.100.1; DHCPREQUEST on <wan_interface> to 255.255.255.255 port 67; DHCPACK from 198.51.100.1; bound to 198.51.100.25 -- renewal in <seconds>. Unhealthy examples include repeated DHCPDISCOVER with no DHCPOFFER, DHCPNAK from upstream, no log entries for the expected WAN interface, or messages suggesting the wrong interface is running DHCP. Exact wording varies by OPNsense version and DHCP client implementation.

   Rollback or backout:

   No change is made in this step. If logs show offers are arriving but OPNsense rejects or ignores them, stop MAC-change attempts and escalate with log excerpts.

4. Compare broken state with a known-good firewall, previous backup, or similar site

   Use this when only one firewall, tenant, VM, ISP circuit, or site is affected. The goal is to identify the first difference, not to copy settings blindly between environments.

   Example pattern only. Adjust for your environment before running.

   Compare previous OPNsense configuration backup values for WAN interface, MAC override, VLAN tag, gateway, and DHCP mode
   Compare hypervisor VM hardware settings for vNIC MAC, adapter type, bridge, port group, VLAN, and connected uplink
   Compare ISP modem/ONT/gateway mode: bridge, router, passthrough, CGNAT, or managed handoff
   Compare current route table and WAN lease with a working site or earlier incident evidence

   Expected output:

   Expected comparison fields: OPNsense WAN interface, OPNsense WAN MAC override, hypervisor vNIC MAC, VLAN tag, bridge or port group name, physical uplink, modem/ONT mode, WAN lease address, default gateway, DHCP log sequence, gateway monitor state, and ISP case/account reference. A useful finding is a single difference such as old vNIC MAC 00:50:56:11:22:33 versus new vNIC MAC 00:50:56:aa:bb:cc, VLAN 201 missing on the new port group, or modem now in router mode instead of bridge mode.

   Rollback or backout:

   No change is made in this step. Do not apply settings from another site unless they are confirmed appropriate for this circuit and change-approved.

5. Run a limited WAN DHCP packet capture only with approval

   Packet capture is not purely read-only operationally. It can create files, consume CPU/disk, and expose MAC addresses, public IPs, DHCP options, hostnames, provider identifiers, and topology. Use a narrow DHCP-only filter, a small packet count or short duration, and secure handling. Human-review the packet capture UI path and controls for your OPNsense version.

   Example pattern only. Adjust for your environment before running.

   OPNsense UI, human-review path: Interfaces > Diagnostics > Packet Capture
   Capture interface: <WAN_INTERFACE>
   Capture filter: udp and (port 67 or port 68)
   Packet count or duration limit: 20 packets or 60 seconds
   Start capture only during an approved test window, then stop capture immediately after the DHCP attempt
   If exporting a pcap, store it as sensitive incident evidence and delete unneeded local copies according to policy

   Expected output:

   Healthy packet sequence: DHCPDISCOVER from client MAC aa:bb:cc:dd:ee:ff to broadcast, DHCPOFFER from upstream DHCP server, DHCPREQUEST from client, DHCPACK from upstream server. Broken examples: only repeated DHCPDISCOVER and no DHCPOFFER, DHCPOFFER visible but no DHCPREQUEST, DHCPNAK from upstream, DHCP frames on the wrong VLAN/interface, or no DHCP frames at all despite a lease renewal attempt.

   Rollback or backout:

   Stop the capture, download only if needed, protect the pcap as sensitive data, and remove unnecessary capture files per local policy. If the capture impacts firewall performance or includes unexpected traffic, stop immediately and escalate.

6. Verify upstream access mode, VLAN, and virtualization path before changing MAC identity

   Many cases that look like ISP MAC lock are actually access-mode or virtualization-path issues. Confirm the WAN circuit still expects plain DHCP and that frames from the OPNsense WAN interface can reach the correct physical uplink with the correct VLAN behavior.

   Example pattern only. Adjust for your environment before running.

   Check ISP order, portal, or support notes for WAN type: DHCP, DHCP over VLAN, static IP, PPPoE, passthrough, bridge mode, CGNAT, or managed gateway
   Check OPNsense WAN VLAN assignment if the ISP requires a tagged VLAN
   Proxmox: check VM NIC bridge, VLAN tag, VLAN-aware bridge setting, physical uplink membership, and whether the VM NIC model changed
   VMware: check port group, VLAN ID/trunking, connected uplink, MAC Address Changes and Forged Transmits policies where MAC override/cloning is in use
   Hyper-V: check virtual switch, VLAN ID, static/dynamic MAC setting, and MAC spoofing setting where MAC override/cloning is in use

   Expected output:

   Expected result is a consistent path: OPNsense WAN interface maps to the intended vNIC, vNIC maps to the intended bridge/port group/vSwitch, VLAN behavior matches the ISP handoff, and the physical uplink reaches the modem/ONT. A mismatch such as wrong bridge, missing VLAN tag, disconnected vNIC, blocked forged transmits, disabled MAC spoofing, or changed VM NIC model can prevent DHCP even when OPNsense is configured correctly.

   Rollback or backout:

   No change is made in this step. If a hypervisor setting must be changed, create a separate change with hypervisor-owner approval and a VM console recovery plan.

7. Clone or restore the known-good WAN MAC only after approval

   Use this only when evidence indicates the ISP or modem/ONT is bound to a previous client MAC and you are authorized to use that MAC. This changes WAN layer-2 identity and can interrupt internet access, affect provider authorization, and create duplicate MAC problems if the old device is still connected.

   Example pattern only. Adjust for your environment before running.

   OPNsense UI, human-review path: Interfaces > WAN > MAC address
   Set MAC address to <KNOWN_GOOD_AUTHORIZED_MAC>
   Save
   Apply Changes

   Expected output:

   After applying and renewing DHCP in the next approved step, WAN should receive the expected ISP-provided address and install a default route through WAN. Example expected state: WAN IPv4 198.51.100.25/24, gateway 198.51.100.1, default route default 198.51.100.1 UGS <wan_interface>, gateway monitor online if configured. If the MAC is wrong or not authorized, the expected output may remain repeated DHCPDISCOVER with no DHCPOFFER or a DHCPNAK/no lease condition.

   Rollback or backout:

   Re-enter the original WAN MAC recorded in the prerequisite step, save, apply changes, and renew DHCP only during the approved window. Stop after one approved rollback attempt if DHCP does not recover. If remote access depends on WAN and console access is not working, do not proceed.

8. Power-cycle the modem or ONT and renew the WAN DHCP lease during the approved window

   This interrupts the site internet path. Some providers accept a new client identity only after the modem/ONT/gateway reboots or after provider-side provisioning clears. Use the provider-recommended interval when known; otherwise do not invent timing guarantees. Renewing DHCP can change the public IP and disrupt inbound NAT, VPN peers, allowlists, DNS records, and monitoring.

   Example pattern only. Adjust for your environment before running.

   Power off the modem, ONT, or ISP gateway for the provider-recommended interval
   Power it back on and wait for upstream sync/online indicators
   OPNsense UI, human-review path: Interfaces > Overview > WAN > Renew DHCP lease

   Expected output:

   Expected healthy result: WAN obtains the expected ISP-provided lease, default route points out WAN, gateway monitoring is online if configured, DNS resolution from OPNsense succeeds, and a LAN client reaches the internet through OPNsense. DHCP evidence should show discover/offer/request/ack rather than repeated discover/no-offer.

   Rollback or backout:

   If the approved MAC clone does not recover DHCP, restore the original MAC, save/apply, and renew DHCP or power-cycle again only if the maintenance window and ISP guidance allow it. Stop changing MACs after the approved rollback attempt and escalate to the ISP with logs and packet capture evidence.

9. Validate WAN, routing, DNS, and client connectivity after recovery

   Do not declare the incident resolved based only on a WAN address. Confirm route installation, gateway health, DNS, outbound connectivity, and that no unnecessary firewall/NAT changes were made.

   Example pattern only. Adjust for your environment before running.

   OPNsense UI: Interfaces > Overview
   OPNsense UI: System > Gateways or gateway status view, human-review path
   OPNsense UI: Diagnostics > DNS Lookup, human-review path
   OPNsense UI: Diagnostics > Ping, human-review path
   Shell, read-only, human-review-needed: netstat -rn
   From a LAN client: test DNS resolution and HTTPS access through OPNsense

   Expected output:

   WAN has the expected lease, the default route points to the WAN gateway, gateway monitor is online if used, DNS lookup succeeds, OPNsense can ping or otherwise reach an approved external target, and a LAN client can browse or connect through the firewall. Confirm NAT and firewall policy were not changed as a workaround unless a separate approved change exists.

   Rollback or backout:

   No change is made in this validation step. If validation fails after DHCP succeeds, stop MAC changes and troubleshoot routing, DNS, gateway monitoring, NAT, or ISP reachability as a separate problem.

Validation

• The WAN interface receives the expected public, routed, CGNAT, or provider-defined DHCP address for this circuit.
• The route table contains a default route through the WAN gateway, for example: default 198.51.100.1 UGS <wan_interface>.
• Gateway monitoring is online where configured, or any offline state is understood and documented.
• OPNsense can resolve DNS using the configured resolver/forwarder path.
• OPNsense can reach an approved external target from diagnostics.
• A LAN client can resolve DNS and reach the internet through OPNsense without bypassing the firewall.
• Inbound dependencies affected by public IP changes are checked: VPN peers, NAT forwards, DNS records, SaaS allowlists, monitoring allowlists, and remote management.
• A DHCP renew or reboot validation test is performed only when safe and approved; otherwise document that persistence validation is deferred.
• No firewall or NAT rules were rebuilt or changed unless separately approved and evidenced.

Logs to Check

• OPNsense System > Log Files > General or the current supported UI log path for DHCP client messages; human-review the exact path for your version.
• OPNsense DHCP-related logs for DHCPDISCOVER, DHCPOFFER, DHCPREQUEST, DHCPACK, DHCPNAK, timeout, and interface mismatch messages.
• OPNsense Interfaces > Overview for WAN address, MAC, gateway, and link status.
• OPNsense gateway monitoring/status logs if WAN obtains a lease but connectivity still fails.
• OPNsense interface/link logs for link flaps, driver messages, or NIC errors where available.
• OPNsense Interfaces > Diagnostics > Packet Capture only when approved, limited to WAN DHCP traffic with filter udp and (port 67 or port 68).
• Proxmox task logs, VM hardware configuration, bridge configuration, VLAN-aware bridge settings, VM NIC model, VM NIC MAC, and physical uplink mapping.
• VMware vCenter/ESXi task and event logs, VM hardware changes, port group VLAN settings, port group security policy, and uplink mapping.
• Hyper-V host events, VM network adapter settings, virtual switch configuration, VLAN ID, static/dynamic MAC, and MAC spoofing setting when MAC override is used.
• ISP modem/ONT/gateway event logs if available, especially provisioning, bridge mode, DHCP relay/server, MAC limit, link, or registration events.
• ISP ticket notes or portal records for registered customer equipment MAC and provisioning resets.

Rollback and Escalation

• Keep the exported OPNsense configuration available before and during remediation.
• Keep the original OPNsense WAN MAC and hypervisor vNIC MAC in the incident notes.
• If a cloned MAC does not produce a DHCP offer or lease after one approved attempt and the modem/ONT has been handled according to the provider guidance, restore the original MAC and stop changing identity values.
• If remote access is at risk and console or out-of-band access is not confirmed working, stop before applying WAN MAC, lease, or interface changes.
• If DHCP offers are visible but OPNsense rejects or fails to complete the lease, stop MAC cycling and escalate with packet capture and log evidence.
• If restoring the original MAC does not recover service, use console access to verify WAN assignment, VLAN, hypervisor connection, and backup restore options.
• If a public IP changes, roll back or update dependent VPN, NAT, DNS, monitoring, and allowlist configuration according to separate approved procedures.
• Treat packet captures as sensitive evidence; remove unneeded copies according to retention policy.

Escalate When

• Escalate to the ISP if DHCP offers never arrive after confirming link, VLAN, WAN interface, MAC identity, modem/ONT mode, and provider-recommended power cycle/provisioning steps.
• Escalate to the ISP if the circuit requires clearing or updating a registered MAC, bridge/passthrough configuration, ONT authentication, cable modem provisioning, or static/PPPoE settings outside firewall control.
• Escalate to the virtualization owner if the VM network adapter, bridge, port group, VLAN tag, virtual switch, physical uplink, MAC spoofing, forged transmit policy, or NIC model changed.
• Escalate to the firewall owner or vendor/community support if DHCPOFFER/DHCPACK is visible on WAN but OPNsense does not bind the lease.
• Escalate before changing interface assignments, HA/CARP configuration, or multi-WAN gateway policy on a production firewall.
• Stop and escalate if you cannot maintain console or out-of-band access during a WAN-impacting change.
• Stop and escalate after one approved MAC rollback attempt rather than trying multiple unverified MAC addresses.

Edge Cases

• Some ISPs bind to the first MAC seen after modem boot and require a provider-supported reset or power cycle before accepting a different device.
• Some providers do not permit customer MAC cloning or require support to clear a binding.
• A VM restore, clone, migration, NIC model change, or adapter replacement can silently create a new virtual NIC MAC even when the OPNsense configuration looks unchanged.
• A modem in router mode may hand out a private address even though OPNsense DHCP is working; that is a bridge/passthrough expectation issue, not necessarily an OPNsense DHCP client failure.
• A private WAN address may be expected under CGNAT. Confirm the service design before treating private addressing as a fault.
• If WAN uses DHCP over a VLAN, a missing or misplaced VLAN tag can look like MAC lock because no DHCPOFFER arrives.
• PPPoE and static IP handoffs may not use plain DHCP. Repeated DHCP failures on those circuits are expected because DHCP is the wrong access method.
• Cable modem provisioning and fiber ONT authentication are provider-specific; power cycling may not clear all bindings and may require ISP action.
• Renewing DHCP can replace a public IP and break inbound NAT, site-to-site VPNs, monitoring, DNS records, and partner allowlists.
• Cloning the wrong MAC can create duplicate MAC behavior if the old router, firewall, or VM is still attached to the same layer-2 domain.
• For Proxmox, check Linux bridge membership, VLAN-aware bridge configuration, VM NIC VLAN tag, physical uplink, firewall settings, and NIC model changes before blaming OPNsense.
• For VMware, port group VLAN settings and security policies such as MAC Address Changes and Forged Transmits can prevent a cloned MAC from working, depending on policy.
• For Hyper-V, static versus dynamic MAC behavior, virtual switch mapping, VLAN ID, and MAC spoofing settings can affect cloned MAC behavior.
• CARP/HA and multi-WAN deployments can use virtual MACs, gateway groups, and policy routes that change how WAN MAC and route evidence should be interpreted.

Notes from the Field

• Do not rebuild NAT or firewall rules until WAN DHCP evidence proves OPNsense has a valid lease and route. Firewall rules cannot fix an upstream DHCPOFFER that never arrives.
• Take screenshots or export text evidence before and after each approved change: WAN MAC, vNIC MAC, WAN lease, default route, DHCP log sequence, and gateway status.
• Use a small evidence table during the incident: timestamp, OPNsense version, WAN interface, WAN MAC, hypervisor MAC, VLAN, link state, DHCP status, WAN IP, gateway, route state, modem mode, action taken, rollback state, and ISP case number.
• A known-good previous router MAC is useful evidence, but it is not permission by itself. Confirm account authorization and disconnect the old device before cloning.
• Packet captures are often the fastest way to separate OPNsense behavior from upstream behavior, but capture only DHCP traffic and treat pcaps as sensitive.
• If you find the cause was hypervisor MAC drift, document the VM hardware setting and whether the MAC should be static to prevent recurrence.
• Keep a site note with ISP modem/ONT model, bridge/passthrough mode, required VLAN tag, account MAC-binding behavior, and provider support number.