Uptime monitoring for OPNsense

OPNsense is a modern open-source firewall and routing platform forked from pfSense, built on HardenedBSD and designed with a clean web UI, a structured plugin API, and frequent security releases. It is deployed across enterprises, ISPs, and home labs as the network perimeter — handling routing, firewalling, VPN termination, intrusion detection, and traffic shaping. When OPNsense goes down or becomes unreachable, your entire network perimeter fails with it.

This tutorial covers production-grade uptime monitoring for OPNsense using Vigilmon. We will walk through:

• Monitoring the OPNsense web management UI (HTTPS availability)
• WAN uptime check via the /api/core/system/status REST endpoint
• SSL certificate alerts for the management UI certificate
• Heartbeat monitoring for scheduled configuration backups

Prerequisites

• OPNsense 23.x or later
• Access to the OPNsense web GUI and Shell (via SSH or console)
• A free account at vigilmon.online

Part 1: Confirm the management interface is reachable

OPNsense's web GUI listens on port 443 (HTTPS) by default, bound to the LAN interface. Vigilmon probes from multiple geographic regions, so you need to make the management UI accessible from the internet or configure a local relay.

Option A — Expose on a dedicated management IP (recommended for cloud-hosted OPNsense). Add a WAN firewall rule allowing Vigilmon's probe IPs to reach TCP port 443 on the firewall itself.

To add the rule in OPNsense:

1. Navigate to Firewall → Rules → WAN.
2. Click Add at the top of the ruleset.
3. Set:
   • Action: Pass
   • Interface: WAN
   • Protocol: TCP
   • Source: Vigilmon monitoring IP range (shown in your Vigilmon dashboard under Account → Probe IPs)
   • Destination: This firewall
   • Destination Port Range: HTTPS (443)
   • Description: Vigilmon management UI check
4. Click Save and Apply Changes.

Verify the GUI responds before adding the monitor:

curl -k -o /dev/null -w "%{http_code}" https://opnsense.example.com/

Expected: 200 or 302 redirect to the login page.

Option B — Use a LAN relay agent. For air-gapped management networks, deploy a lightweight agent on an internal host that periodically curls the OPNsense UI and hits a Vigilmon heartbeat URL on success. This approach is covered in Part 4.

Part 2: Monitor the OPNsense web management UI

With the GUI reachable, create the HTTP monitor:

1. Log in to vigilmon.online and click Add Monitor.
2. Choose HTTP(S) monitor.
3. Enter: https://opnsense.example.com/
4. Set the check interval to 1 minute.
5. Set expected status code to 200 or 302.
6. Add a keyword check: must contain OPNsense (present in the login page title and meta tags).
7. Add your alert channel (email, Slack, webhook).
8. Click Save.

The keyword check verifies you are reaching the actual OPNsense login page, not a cached error from an upstream proxy or a replaced appliance.

Part 3: Monitor the REST API status endpoint

OPNsense ships a REST API that is enabled by default. The /api/core/system/status endpoint returns real-time system health including uptime, CPU, memory, and disk — no complicated setup required.

First, create a read-only API key in OPNsense:

1. Navigate to System → Access → Users.
2. Create a dedicated user: vigilmon-probe.
3. Assign it to a group with read-only API access (or use the Lobby privilege set for status-only endpoints).
4. Click the + next to API keys and copy the key/secret pair.

Test the endpoint from an external machine:

curl -k -u "YOUR_API_KEY:YOUR_API_SECRET" \
  https://opnsense.example.com/api/core/system/status

Expected response:

{
  "status": "ok",
  "uptime": "5 days, 3:12:04"
}

Add the monitor in Vigilmon:

1. Click Add Monitor → HTTP(S) monitor.
2. Enter: https://opnsense.example.com/api/core/system/status
3. Set interval to 1 minute.
4. Under Authentication, set Basic Auth with your API key (key as username, secret as password).
5. Set expected status code to 200.
6. Add a keyword check: must contain "status":"ok" (or "status": "ok" depending on your OPNsense version).
7. Add your alert channel.
8. Click Save.

This monitor catches API daemon restarts and authentication failures — issues the UI check alone might miss if the web server is serving cached responses.

Part 4: WAN uptime check

Monitoring OPNsense from the LAN does not catch WAN link failures. Add a check from the internet to confirm the external interface is up and routing correctly.

The most reliable approach is to monitor a service you run behind OPNsense:

1. Click Add Monitor → TCP monitor.
2. Enter your public WAN IP or hostname and a port for a hosted service (e.g., 203.0.113.50:443 for a web server behind OPNsense).
3. Set interval to 1 minute.
4. Add your alert channel.
5. Click Save.

Pair this with the management UI check: if both go down simultaneously, the WAN link is the likely cause. If only the TCP service check fails, the OPNsense appliance itself is likely healthy.

For a direct WAN health check without exposing a backend service, OPNsense's built-in os-api-backup plugin or a simple NGINX vhost on the WAN interface can expose a /health path.

Part 5: Heartbeat monitoring for scheduled configuration backups

OPNsense configuration is stored in /conf/config.xml. Losing this file means manually reconfiguring every firewall rule, VPN peer, and interface — a multi-hour disaster. Schedule automated backups with a Vigilmon heartbeat to confirm they ran.

Create the backup script

Connect to OPNsense via SSH:

ssh root@opnsense.example.com

Create the backup script at /usr/local/bin/opnsense-backup.sh:

#!/usr/bin/env bash
# /usr/local/bin/opnsense-backup.sh

set -euo pipefail

BACKUP_DIR="/root/backups"
BACKUP_FILE="$BACKUP_DIR/config-$(date +%Y%m%d-%H%M%S).xml"
HEARTBEAT_URL="https://vigilmon.online/api/heartbeat/YOUR_TOKEN"

mkdir -p "$BACKUP_DIR"

# Copy current configuration
cp /conf/config.xml "$BACKUP_FILE"
gzip "$BACKUP_FILE"
echo "[$(date)] Config backed up: ${BACKUP_FILE}.gz"

# Optionally sync to off-site storage
# rsync -az "$BACKUP_DIR/" user@offsite-server:/backups/opnsense/

# Remove backups older than 30 days
find "$BACKUP_DIR" -name "config-*.xml.gz" -mtime +30 -delete
echo "[$(date)] Old backups pruned"

# Signal Vigilmon that the backup completed
curl -fsS --retry 3 "$HEARTBEAT_URL" > /dev/null
echo "[$(date)] Heartbeat sent"

Make it executable:

chmod +x /usr/local/bin/opnsense-backup.sh

Schedule with OPNsense cron

1. Navigate to System → Settings → Cron.
2. Click Add.
3. Set the schedule: 0 2 * * * (daily at 2:00 AM).
4. Set command: /usr/local/bin/opnsense-backup.sh >> /var/log/opnsense-backup.log 2>&1
5. Click Save.

Create the heartbeat monitor in Vigilmon

1. In Vigilmon, click Add Monitor → Heartbeat monitor.
2. Name it: OPNsense config backup.
3. Set expected interval to 24 hours.
4. Set grace period to 1 hour.
5. Copy the heartbeat URL shown and paste it into the HEARTBEAT_URL variable in the script.
6. Click Save.

If the backup script fails (disk full, config file missing, SSH not available), it exits before the curl ping. Vigilmon alerts you the following morning — before the missing backup becomes a recovery crisis.

Part 6: SSL certificate monitoring

OPNsense uses either its built-in self-signed certificate or one you import from Let's Encrypt via the os-acme plugin. Both expire, and expired certificates break management access to the firewall entirely — locking you out during a potential network emergency.

1. In Vigilmon, click Add Monitor → SSL monitor.
2. Enter your OPNsense hostname: opnsense.example.com.
3. Set alert threshold to 14 days before expiry.
4. Add your alert channel.
5. Click Save.

Check the current certificate expiry manually:

openssl s_client -connect opnsense.example.com:443 </dev/null 2>/dev/null \
  | openssl x509 -noout -dates

To install a valid certificate using the ACME plugin:

1. Install the plugin: System → Firmware → Plugins → search os-acme-client → install.
2. Navigate to Services → ACME Client → Accounts and create a Let's Encrypt account.
3. Under Certificates, create a new certificate for your OPNsense hostname.
4. Under Automations, configure the action: Restart Web GUI after renewal.
5. In System → Settings → Administration, select your new ACME certificate under SSL Certificate.

Let's Encrypt certificates renew every 60 days automatically. Vigilmon's 14-day alert catches ACME renewal failures before you lose management access at the worst possible time.

Part 7: Webhook integration for network operations

Route Vigilmon DOWN/UP events to your NOC or on-call channel:

// Webhook receiver for OPNsense monitoring events
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/vigilmon', (req, res) => {
  const { monitor_name, status, url, checked_at, response_time_ms } = req.body;

  if (status === 'down') {
    console.error('[VIGILMON] CRITICAL: OPNsense monitor DOWN', {
      monitor: monitor_name,
      url,
      at: checked_at,
    });
    // OPNsense down = potential full network outage — page immediately
    notifyOnCall({ service: 'OPNsense', monitor: monitor_name, severity: 'critical' });
  } else if (status === 'up') {
    console.info('[VIGILMON] OPNsense monitor recovered', {
      monitor: monitor_name,
      responseMs: response_time_ms,
    });
  }

  res.sendStatus(204);
});

app.listen(3000);

Or use Vigilmon's native Slack integration to post recovery and downtime events directly to a #network-ops channel.

Summary

Your OPNsense deployment now has four layers of external monitoring:

1. Management UI HTTPS check — confirms OPNsense is serving the web interface with a keyword check for the OPNsense title.
2. REST API status check — polls /api/core/system/status with API key auth to confirm the backend API daemon is healthy.
3. WAN uptime check — monitors a public-facing service or TCP port behind OPNsense to catch WAN link failures from the outside.
4. Heartbeat monitor — your daily backup script pings Vigilmon; missing pings mean the backup failed.
5. SSL certificate monitor — alerts you 14 days before the management UI certificate expires.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history. You get notified within 60 seconds of any failure in your OPNsense firewall stack.

Monitor your OPNsense infrastructure free at vigilmon.online

#opnsense #firewall #networking #monitoring #devops #bsd