How to set up UptimeKuma with OPNSense API for CARP monitoring

Download Markdown

Table of Contents

We will configure Monit to constantly watch the CARP status. If it detects a change (e.g., from MASTER to BACKUP), it will run a script that sends a "ping" to a special Uptime Kuma monitor.

Step 1: Create a "Push" Monitor in Uptime Kuma

  1. In Uptime Kuma, create a new monitor.
  2. Select the monitor type "Push".
  3. Give it a name, like OPNsense1-CARP-MASTER-Status.
  4. Save it. Uptime Kuma will give you a unique Push URL. It looks like http://192.168.8.60:3001/api/push/xxxxxxxx.
  5. Copy this URL.

Step 2: Enable Monit in OPNsense

  1. Go to Services -> Monit -> Settings.
  2. Check "Enable Monit".
  3. Set the "Polling Interval" to something reasonable, like 60 or 120 seconds.
  4. Click Save.

Step 3: Create the CARP Check in Monit

  1. Go to Services -> Monit -> Service Tests Settings.
  2. Click + Add.
  3. Configure the test:
    • Enable: Checked.
    • Name: Check_CARP_Master_Status
    • Condition: if status != 0 then alert.
    • Action: Exec
    • Path: /usr/local/opnsense/scripts/monit/check_carp.sh (We will create this script next).

Step 4: Create the Check Script on OPNsense

This is the most technical part. You will need to SSH into your OPNsense firewall and choose option 8 for ‘Shell’ (or use the web GUI's System -> Diagnostics -> Command Prompt).

  1. Create a new file/folder:

    # Create a folder if it does not exist
mkdir -p /usr/local/opnsense/scripts/monit
# Create an empty folder
touch /usr/local/opnsense/scripts/monit/check_carp.sh
# Make it executable
chmod +x /usr/local/opnsense/scripts/monit/check_carp.sh

  2. Edit the file (using vi or ee from the shell, or by pasting into the command prompt's ‘Execute Shell Command’ box):

#!/bin/sh

# Set this to the specific VHID you want to monitor.
VHID_TO_CHECK=1
# Paste your Uptime Kuma Push URL here
PUSH_URL="http://192.168.8.60:3001/api/push/xxxxxxxx?status=up&msg=OK&ping="

# Define full paths to commands to ensure they are found by Monit's minimal environment
IFCONFIG_CMD="/sbin/ifconfig"
GREP_CMD="/usr/bin/grep"
CURL_CMD="/usr/local/bin/curl"

# Check if the specific CARP VHID is in MASTER state using full paths
if ${IFCONFIG_CMD} | ${GREP_CMD} "carp: MASTER" | ${GREP_CMD} -q "vhid ${VHID_TO_CHECK}"; then
    # If we are MASTER for this specific VHID, send the "up" signal to Uptime Kuma
    ${CURL_CMD} -sS --fail -m 10 "$PUSH_URL" > /dev/null
    # Exit with status 0 (OK) for Monit
    exit 0
else
    # If not MASTER for this specific VHID, do nothing and exit with a failure code.
    # Uptime Kuma will time out and report the monitor as down.
    exit 1
fi

Step 5: Add the script to Monit’s Settings

  1. In your OPNsense GUI, navigate to Services -> Monit -> Service Settings.
  2. Click the + Add button to create a new service.
  3. Fill out the form as follows:
    • Enable: Checked.
    • Name: CARP_Master_Check_Program (or any descriptive name you like).
    • Type: Select Custom from the dropdown list.
    • Path: Enter the full path to your script: /usr/local/opnsense/scripts/monit/check_carp.sh
    • Timeouts: 10 seconds should be sufficient
    • Tests: In this dropdown menu, you should see the test we created earlier. Select Check_CARP_Master_Status. This is the critical step that links the program to the test.
  4. Click Save.
  5. A green "Apply" button will appear at the top of the page. Click it to make the changes live.

Troubleshooting

  • Script not executing? SSH in and check the following:
# Ensure that the script is executable - need to see 'x' in the permissions
ls -lah /usr/local/opnsense/scripts/check_carp.sh

# Confim monit is running
service monit status

# Check monit service
monit status

# Check monit's syntax check
monit -t

Now, every minute or two, Monit will run this script. If the firewall is the CARP master, the script will send a successful "ping" to Uptime Kuma, and the monitor will show as "Up". If the firewall fails over and is no longer the master, the script won't send the ping, and your Uptime Kuma monitor will go down after its configured grace period.

More in OPNSense