Monitoring Shinobi NVR with Vigilmon

Shinobi is the world's most-starred open-source Network Video Recorder, built on Node.js and designed for self-hosters who want full control over camera recording without cloud subscriptions. It handles RTSP/RTMP/HTTP camera streams, motion detection, multi-user access, and both MJPEG and HLS video output — but when the recording daemon stalls or the web UI disappears, you typically find out when reviewing footage after an incident. Vigilmon gives you continuous visibility into Shinobi's health: web UI availability, API responsiveness, WebSocket stream health, SSL certificate integrity on proxied deployments, and heartbeat confirmation that recordings are actively capturing.

What You'll Set Up

• HTTP uptime monitor for the Shinobi web UI (port 8080 superuser login page)
• REST API health check for the Shinobi monitor status endpoint
• TCP port monitor for Shinobi's socket.io WebSocket connection
• SSL certificate alerts for HTTPS-proxied Shinobi deployments
• Cron heartbeat to confirm recordings are active and not stalled

Prerequisites

• Shinobi NVR installed and running (Docker or native Linux install, port 8080)
• At least one camera monitor configured and in recording mode
• Your Shinobi auth_key, group_key, and a monitor ID from the superuser panel
• A free Vigilmon account

Step 1: Monitor the Shinobi Web UI

Shinobi's web interface runs on port 8080. The superuser login page at /super/ is the canonical health signal — if it returns a non-200 response, Shinobi's Node.js process has crashed or the server is unreachable.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://your-shinobi-host:8080/super/
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If Shinobi is behind an Nginx reverse proxy with a domain name, use the proxied URL instead:

https://nvr.yourdomain.com/super/

This catches Node.js process crashes, port binding failures, and host-level network issues in under 60 seconds.

Step 2: Check the Shinobi REST API

Shinobi exposes a REST API that reports per-monitor status. An API probe verifies that Shinobi's application logic is healthy, not just that port 8080 is open.

The monitor status endpoint returns a JSON object describing whether the camera monitor is running, in error, or idle:

http://your-shinobi-host:8080/api/:auth_key/monitor/:group_key/:monitor_id

Replace :auth_key, :group_key, and :monitor_id with values from your Shinobi superuser panel (API tab under your account).

Add a Vigilmon HTTP monitor for this endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the full API URL with your credentials substituted.
3. Set Check interval to 2 minutes.
4. Under Response body check, enter "status" to confirm the JSON response contains a status field.
5. Set Expected HTTP status to 200.
6. Click Save.

A non-200 response or missing status key indicates the monitor has become misconfigured or the API service has faulted.

Step 3: TCP Port Monitor for WebSocket Stream Health

Shinobi uses socket.io over port 8080 for real-time video streaming to browser clients. The same port serves both HTTP and WebSocket traffic. A TCP-level check confirms the port is accepting connections even when a full HTTP probe would miss a partial failure.

1. Click Add Monitor → TCP Port.
2. Enter your Shinobi host address.
3. Set Port to 8080.
4. Set Check interval to 1 minute.
5. Click Save.

If you run Shinobi's socket.io on a separate port (configured via conf.json), add a second TCP monitor for that port. A TCP failure at this level typically indicates a firewall change, a port binding conflict, or a full Node.js crash that the HTTP probe may not catch until the next check cycle.

Step 4: SSL Certificate Alerts for HTTPS Deployments

Most production Shinobi deployments sit behind Nginx with a Let's Encrypt certificate. Certificate renewal can fail silently when the ACME challenge port is blocked or the renewal cron job is misconfigured — and your cameras keep recording over HTTP while the cert is expired and client browser warnings go unnoticed.

Enable SSL monitoring on the HTTP monitor from Step 1:

1. Open the Shinobi web UI monitor in Vigilmon.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Sample Nginx configuration for a Shinobi reverse proxy:

server {
    listen 443 ssl;
    server_name nvr.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/nvr.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/nvr.yourdomain.com/privkey.pem;

    location / {
        proxy_pass         http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
    }
}

The Upgrade and Connection headers are required so that socket.io WebSocket connections pass through the proxy correctly.

A 21-day alert window gives you enough time to investigate renewal failures and manually run:

sudo certbot renew --force-renewal

Step 5: Heartbeat Monitoring for Recording Health

A running web UI doesn't guarantee recordings are active. Shinobi can be up and responsive while a specific monitor is stalled, out of disk space, or has lost its RTSP stream. Use Vigilmon's cron heartbeat to periodically confirm that a camera monitor is actively recording.

Shinobi provides a trigger API endpoint per monitor. Set up a cron job on the Shinobi host that queries monitor status and only pings Vigilmon when the monitor reports it is recording:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 5 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Create a check script on your Shinobi host:

#!/bin/bash
# /usr/local/bin/check-shinobi-recording.sh

AUTH_KEY="your_auth_key"
GROUP_KEY="your_group_key"
MONITOR_ID="your_monitor_id"
SHINOBI_URL="http://localhost:8080"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"

STATUS=$(curl -sf "${SHINOBI_URL}/api/${AUTH_KEY}/monitor/${GROUP_KEY}/${MONITOR_ID}" \
  | jq -r '.monitors[0].status // empty')

if [ "$STATUS" = "record" ] || [ "$STATUS" = "start" ]; then
  curl -sf "$HEARTBEAT_URL" > /dev/null
fi

Make it executable and schedule it:

chmod +x /usr/local/bin/check-shinobi-recording.sh

Add to crontab:

*/5 * * * * /usr/local/bin/check-shinobi-recording.sh

If the monitor status stops being record or start — due to a lost RTSP stream, disk-full condition, or Shinobi daemon fault — the script stops pinging and Vigilmon fires an alert after 5 minutes of silence. You'll know recordings have stalled before you need the footage.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and connect Slack, email, or a webhook to your NVR alert group.
2. Set Consecutive failures before alert to 2 on the web UI and API monitors to avoid false positives from transient network blips.
3. For the heartbeat monitor, keep the alert threshold at 1 missed ping — a single missed heartbeat on a 5-minute schedule already represents 5+ minutes of recording uncertainty.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | http://host:8080/super/ | Node.js crash, server unreachable | | REST API | /api/:auth_key/monitor/:group/:id | API fault, misconfigured monitor | | TCP Port | Host port 8080 | Port binding failure, firewall change | | SSL Certificate | https://nvr.yourdomain.com | Let's Encrypt renewal failure | | Cron Heartbeat | Vigilmon heartbeat URL | Stalled recording, RTSP stream loss |

Shinobi gives you a powerful self-hosted NVR without cloud lock-in — but that self-hosted freedom means you own the reliability too. With Vigilmon watching the web UI, API, WebSocket port, and recording heartbeat, you'll know the moment Shinobi stops protecting your property, not after the fact when you need the footage most.