OPNsense: Automatic Recovery When WAN Fails

Please visit the following updated tutorial.
Turns out opnsense overwrites the cron entry so we need to take some extra steps.
The following guide is for OPNsense 25.7.7_4

Introduction

Firewalls and routers are supposed to be “set and forget.” But what happens when your internet connection drops — and doesn’t recover until you manually reboot your OPNsense box?

This exact situation happened to me. After some digging, I realized that OPNsense lacks a built-in way to recover from WAN outages, like:

• WAN gateway unreachable
• Stuck DHCP lease
• Internet down even though link is up

The worst part? There’s no built-in watchdog or action that restarts services or reboots the box automatically. So I built one.

This post walks through:

• The symptom
• The cause
• And a simple, reliable solution to automatically recover from WAN loss — with optional reboot fallback.

Symptom

Here’s what I observed:

• Internet access stopped working on all devices
• WAN interface (ix1 in my case) showed as up, but no traffic passed
• OPNsense logs showed gateway pings failing or dhclient errors
• Internet only came back after a manual reboot of the firewall

Logs like this appeared:

dhclient: send_packet: Network is down
/usr/local/etc/rc.newwanip: IP renewal starting...

But no recovery happened until I rebooted OPNsense.

What I Expected

I expected OPNsense to:

• Detect WAN gateway is unreachable
• Attempt to renew DHCP, restart services like unbound
• If all else fails, reboot to recover connectivity

But none of that happens automatically.

Solution: DIY WAN Watchdog Script

Since OPNsense doesn’t offer this natively, I built a lightweight shell script that:

1. Pings a reliable host (like 1.1.1.1)
2. If unreachable: Releases and renews the WAN DHCP lease, and Re-checks connectivity
3. If still down: Reboots the system to force full recovery

Script:/root/gw_watchdog.sh

#!/bin/sh

WAN_IF="ix1"
GW_HOST="1.1.1.1"
LOGFILE="/var/log/gw_watchdog.log"

log() {
  echo "$(date '+%Y-%m-%d %H:%M:%S') $1" >> $LOGFILE
}

ping -c 3 -W 2 $GW_HOST > /dev/null 2>&1
if [ $? -ne 0 ]; then
  log "⚠️  Gateway $GW_HOST unreachable. Trying DHCP renew on $WAN_IF..."
  /sbin/dhclient -r $WAN_IF
  /sbin/dhclient $WAN_IF
  sleep 20

  ping -c 3 -W 2 $GW_HOST > /dev/null 2>&1
  if [ $? -ne 0 ]; then
    log "❌ Still no connectivity. Triggering reboot."
    /sbin/shutdown -r now
  else
    log "✅ Internet restored after DHCP renew."
  fi
else
  log "✔️  Gateway $GW_HOST is reachable."
fi

Make it executable:

chmod +x /root/gw_watchdog.sh

Add It to Cron (Manual Method)

Since the OPNsense GUI doesn’t allow user-defined cron jobs for scripts, you’ll need to add it manually:

crontab -e

Add this line to run every 5 minutes:

*/5 * * * * /root/gw_watchdog.sh

Save and exit.

Check it’s registered with:

crontab -l

Where It Logs

The script logs to:

/var/log/gw_watchdog.log

You can watch it live with:

tail -f /var/log/gw_watchdog.log

Final Thoughts

While OPNsense is powerful and flexible, it’s surprising that a basic auto-recovery mechanism for WAN failure is missing. Until they offer a proper plugin or built-in watchdog, this script can serve as a reliable safety net.

Feel free to use and adapt it to your setup — and let me know if you improve on it.