tutorial

Monitoring NetAlertX with Vigilmon

NetAlertX scans your network for unknown devices — but who monitors the monitor? Here's how to use Vigilmon to watch NetAlertX's web UI, REST API, PHP response health, SSL certificates, and scheduled ARP/nmap scan heartbeats.

NetAlertX (formerly Pi.Alert) is an open-source network device presence monitoring and alerting tool. Running on Python with a Docker-friendly setup, it continuously scans your network using ARP and nmap to detect new, unknown, or offline devices — popular on Raspberry Pi and Linux home servers. The irony of any network monitor is that it can go down itself. When NetAlertX's web UI becomes unreachable or its scheduled scans stop running, you lose visibility into your entire network without any warning. Vigilmon solves this by monitoring NetAlertX itself — its web interface, REST API, response health, SSL certificate, and scan job heartbeats.

What You'll Set Up

  • HTTP uptime monitor for the NetAlertX web UI (default port 20211)
  • REST API endpoint availability check (/api/)
  • PHP response keyword check for application health
  • SSL certificate expiry alerts for HTTPS-proxied NetAlertX setups
  • Cron heartbeat for NetAlertX scheduled ARP/nmap device discovery runs

Prerequisites

  • NetAlertX running (Docker or bare-metal) and accessible on port 20211 or via a reverse proxy
  • A free Vigilmon account

Step 1: Monitor the NetAlertX Web UI

NetAlertX serves its web interface on port 20211 by default. The main page (/index.php) is your primary availability signal.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your NetAlertX URL: 
    http://192.168.1.x:20211/index.php
    Or if you're using a reverse proxy with a domain: 
    https://netalertx.yourdomain.com/
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Enable Keyword Check and enter NetAlertX to confirm the page is rendering correctly.
  7. Click Save.

The keyword check distinguishes a healthy application response from an nginx 502 Bad Gateway or PHP crash page that still returns HTTP 200.

Step 2: Monitor the NetAlertX REST API

NetAlertX exposes a REST API endpoint at /api/. Monitoring it confirms the application's backend is responding and can serve data.

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: 
    http://192.168.1.x:20211/api/
  3. Set Check interval to 5 minutes.
  4. Set Expected HTTP status to 200.
  5. Enable Keyword Check and enter api or devices (the API response includes these strings).
  6. Click Save.

The API monitor complements the web UI monitor — it's possible for the PHP frontend to serve pages while the API backend has a routing or configuration error, or vice versa.

Step 3: PHP Response Keyword Check for Application Health

NetAlertX is a PHP application. PHP misconfiguration or a broken update can cause it to serve a partially rendered page or a PHP warning banner instead of the correct UI. A keyword check verifies the actual application content.

  1. Open the web UI monitor from Step 1.
  2. Expand Keyword Check.
  3. Set keyword to NetAlertX and enable Keyword must be present mode.
  4. Also add a Negative keyword check for Fatal error if your Vigilmon plan supports it — this catches PHP fatal errors that render inline with HTTP 200.
  5. Save.

This is especially useful after NetAlertX updates, when PHP version mismatches or database schema changes can cause silent failures.

Step 4: SSL Certificate Alerts for HTTPS-Proxied NetAlertX

NetAlertX itself doesn't terminate TLS — but many homelab and small business setups front it with an nginx or Caddy reverse proxy that handles SSL. If your certificate expires, users get a browser security warning and access is blocked.

  1. Open the NetAlertX web UI monitor (make sure its URL uses https://).
  2. Enable Monitor SSL certificate under the SSL section.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

Check your current certificate expiry:

echo | openssl s_client -connect netalertx.yourdomain.com:443 -servername netalertx.yourdomain.com 2>/dev/null \
  | openssl x509 -noout -dates

For Caddy reverse proxy setups, Caddy auto-renews certificates. A Vigilmon SSL monitor still catches renewal failures early — before browsers start showing security warnings to users.

Step 5: Heartbeat Monitoring for NetAlertX Scan Jobs

NetAlertX's core value is its periodic ARP and nmap network scans that detect new or offline devices. These scans run on a schedule configured in app.conf or the NetAlertX UI. If the scan scheduler stops working — due to a process crash, Docker container OOM kill, or configuration error — you stop receiving device alerts entirely, with no indication anything is wrong.

Set Up the Heartbeat Monitor

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set Expected ping interval to match your NetAlertX scan frequency (e.g. 30 minutes if scans run every 30 minutes).
  3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Wire It Into NetAlertX's Scan Execution

NetAlertX runs periodic scans via its internal scheduler or an external cron job. To add a heartbeat ping, wrap the scan call:

If using an external cron to trigger scans:

*/30 * * * * docker exec netalertx python /app/back/run_scan.py && curl -s https://vigilmon.online/heartbeat/abc123

If NetAlertX runs inside Docker with its own internal scheduler, add a sidecar health ping via a cron job that checks the last scan timestamp in NetAlertX's database:

*/30 * * * * docker exec netalertx sqlite3 /app/db/app.db "SELECT MAX(Scan_Date) FROM Scans;" | grep -q "$(date +%Y-%m-%d)" && curl -s https://vigilmon.online/heartbeat/abc123

This confirms a scan completed today before pinging Vigilmon.

For bare-metal NetAlertX installations:

*/30 * * * * /usr/bin/python3 /opt/netalertx/back/run_scan.py >> /var/log/netalertx/scan.log 2>&1 && curl -s https://vigilmon.online/heartbeat/abc123

If the scan process exits non-zero (e.g. nmap not found, insufficient permissions, or a Python exception), the && prevents the heartbeat ping. Vigilmon alerts after 30 minutes with no ping received.

Step 6: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add email, Slack, ntfy.sh webhook, or any other channel.
  2. Set Consecutive failures before alert to 2 on the web UI monitor — Docker container restarts can cause a single probe to miss.
  3. Set threshold to 1 on the heartbeat monitor — a missed network scan should alert immediately, not after a grace period.
  4. If NetAlertX is running on a Raspberry Pi, consider adding a TCP port monitor on port 22 (SSH) as a host-level availability check:
    • Type: TCP Port
    • Host: 192.168.1.x
    • Port: 22

This distinguishes NetAlertX application failures from the Raspberry Pi host being unreachable entirely.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | :20211/index.php | Application down, PHP errors | | Keyword check | NetAlertX on main page | Partial render, PHP warnings | | REST API | :20211/api/ | API backend failure | | SSL certificate | Your reverse proxy domain | Certificate expiry | | Scan heartbeat | Heartbeat URL | Missed ARP/nmap scans | | TCP port (host) | :22 on Pi/server | Host unreachable |

NetAlertX keeps watch over every device on your network — but it needs someone watching it too. With Vigilmon monitoring NetAlertX's web interface, API endpoint, PHP response health, SSL certificate, and scan job heartbeats, you get a complete safety net. If NetAlertX itself goes silent, you'll know immediately rather than discovering it only when an unknown device joins your network undetected.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles