Run dhcpcd with a CARP virtual MAC so a single dynamic ISP lease survives OPNsense HA failover.
Many ISPs (notably cable modems) lock a DHCP lease to a single MAC and only hand out one IPv4 address. OPNsense's default dhclient coupled with CARP does not handle this well — the backup firewall either cannot obtain a lease or the modem refuses to re-issue one after a failover.
This project runs dhcpcd on the CARP virtual MAC address and keeps OPNsense's virtual IP, gateway, firewall alias, and NPTv6 rules in sync with the current lease.
| Requirement | Note |
|---|---|
| OPNsense 26.7 | Only version currently tested. Other versions may work but are untested. |
| HA pair (optional but expected) | System > High Availability with Synchronize Peer IP and pfsync interface configured. Single-node works; peer sync is skipped. |
| Clone location | Repository must live at /root/opnsense-tweaks — hooks use absolute paths (/root/opnsense-tweaks/src/dhcpcarp-*.php). |
| Ports tree | opnsense-code ports tools must succeed. |
The hooks discover what to manage by description. Create these objects before installing:
| Object | Location | Description must be |
|---|---|---|
| CARP virtual IP (IPv4) | Interfaces > Virtual IPs (Type: CARP) |
<ifname> DHCP (e.g. wan DHCP) |
| IP Alias (IPv6) | Interfaces > Virtual IPs (Type: IP Alias) |
<ifname> DHCPv6 |
| Gateway | System > Gateways |
<ifname> DHCP / <ifname> DHCPv6 |
| Firewall Alias | Firewall > Aliases (Type: Host) |
<ifname> DHCP / <ifname> DHCPv6 |
| NPTv6 Rules | Firewall > NAT > NPTv6 |
<ifname> DHCPv6 prefix 1, prefix 2, ... — one per delegated prefix you use |
IPv6 CARP virtual IPs are not supported; IPv6 state is carried by IP Alias (avoids split-brain).
Firewall aliases are to be used for outbound NAT/port-forward rules so they follow the dynamic IP without manual edits.
The shipped dhcpcd.conf contains interface vtnet1 with ia_na and ia_pd 1-5. If needed, edit this before installing — replace vtnet1 with your real WAN interface name (igb0, vtnet0, em0, etc.). Use ifconfig or Interfaces > Assignments to find it. Add or remove ia_pd lines to match the number of delegated prefixes your ISP provides.
Then, run as root on the primary firewall:
# clone to the expected path
git clone https://github.com/abraha2d/opnsense-tweaks.git /root/opnsense-tweaks
cd /root/opnsense-tweaks
# edit the interface name to match your WAN, if needed
vi usr/local/etc/dhcpcd.conf # change `interface vtnet1`
sh install.shRe-run sh install.sh after pulling updates — it will re-sync the peer to the same commit.
php /root/opnsense-tweaks/src/dhcpcarp-renew.php <ifname> [--renew|--reset]--renew(default) — gentle rebind:dhcpcd -n <iface>--reset— cold reset:kill -9 dhcpcd, clean*.lease, (re)set MAC address, thendhcpcd -r <address_request>
Refuses to run if the interface's CARP state is BACKUP.
- Logs — All actions log to both
STDERRand the system log. CheckSystem > Log Files > Generalorclog /var/log/system.log | grep dhcpcarp. - CARP hold/release failed — The hook logs
failed to hold CARP on peer/failed to release. Manual release:ssh root@<peer_ip> 'sysctl net.inet.carp.allow=1'. - no eligible virtual IPs found — No CARP virtual IP with description
<ifname> DHCPexists, or mode is notcarp. - did not find VIP/gateway/alias/NPT for <descr> — Description mismatch; see Pre-configuration.
- Peer unreachable — Hook proceeds without hold/sync and logs
peer <ip> unreachable. Verify mutual SSH key trust, host key acceptance, and that.dhcpcarp_peercontains the correct IP. SSH keys are generated with an empty passphrase (ssh-keygen -N '') sossh -o BatchMode=yescan run non-interactively. - Lease not updating — Confirm
dhcpcdis running:cat /var/run/dhcpcd/<interface>.pidandps aux | grep dhcpcd. Usesrc/dhcpcarp-renew.php wan --resetto force a cold restart.
sh /root/opnsense-tweaks/uninstall.shRemove the CARP virtual IP / gateway / firewall alias / NPTv6 rules manually if no longer needed.
/usr/local/etc/rc.syshook.d/carp/10-wandhcp delegates to src/dhcpcarp-carp-hook.php (/root/opnsense-tweaks/src/dhcpcarp-carp-hook.php):
MASTER— sets the WAN interface MAC to00:00:5e:00:01:{vhid:02x}and startsdhcpcd. If a previous lease address is known, it is passed via-rto encourage the server to re-issue the same IP.BACKUP— stopsdhcpcdand restores the originalhwaddr.
Interface eligibility is determined by scanning CARP virtual IPs whose description ends with DHCP.
/usr/local/libexec/dhcpcd-hooks/10-wancarp delegates to src/dhcpcarp-dhcp-hook.php (/root/opnsense-tweaks/src/dhcpcarp-dhcp-hook.php). It handles:
BOUND/REBOOT— IPv4 lease (new_ip_address,new_subnet_cidr,new_routers)BOUND6/REBOOT6— DHCPv6 address (new_dhcp6_ia_na1_ia_addr1)ROUTERADVERT— SLAAC / RA prefix length and router (nd1_prefix_information1_length,nd1_from)- Delegated prefixes (
new_dhcp6_ia_pd1_prefix{1..N})
Updates are idempotent — if the lease matches the stored virtual IP / gateway / firewall alias / NPTv6 rules, the hook exits early.
When a change is required:
- Hold CARP on the HA peer (
sysctl net.inet.carp.allow=0) if reachable. - Bring the local virtual IP down (
interface_vip_bring_down). - Update the OPNsense MVC models, then apply the configuration (
write_config/system_routing_configure/plugins_configure('monitor')/filter_configure). - Re-configure the virtual IP (
interface_carp_configure/interface_ipalias_configure). - Sync to peer — selective JSON sync via
php src/dhcpcarp-config.php(/root/opnsense-tweaks/src/dhcpcarp-config.php) over SSH if this node is the HA backup, otherwiseconfigd_run('filter sync'). - Release the peer CARP hold (
net.inet.carp.allow=1).
-
Stable DUID/MAC — The CARP virtual MAC
00:00:5e:00:01:{vhid}is programmed withifconfig etherbeforedhcpcdstarts.dhcpcd.confpinsduid 00:03:00:01:00:00:5e:00:01:01(type 3, link-layer +00:00:5e:00:01:01) andxidhwaddrso the client identifier and transaction ID are tied to the virtual MAC, not the physical NIC. This avoids the race where multiple WANs generate competing DUIDs at boot (commit592563a). -
xidhwaddr+persistent—xidhwaddrforces the DHCP transaction ID to be derived from the hardware address, making retransmits recognizable to the server after a failover.persistentkeeps the interface configured whendhcpcdexits so CARP virtual IP bring-down/up is controlled explicitly by the hook rather thandhcpcd. -
Prefix delegation —
ia_pd 1-5indhcpcd.confrequest up to five/56or/60prefixes. The hook readsnew_dhcp6_ia_pd1_prefix{1..N}env vars and updates matching NPTv6 rules. Earlier iterations relied on hardware-address-based DUID generation; the current approach hard-codes the DUID to avoid per-interface divergence.