Monitoring NetBox with Vigilmon: Web UI Health, REST API Availability, SSL Certificates & Uptime Checks

NetBox is the de facto source of truth for network infrastructure teams — the authoritative inventory for IP addresses, VLANs, racks, devices, cables, circuits, and every other physical and logical network asset. Network automation pipelines, IPAM tooling, provisioning systems, and Ansible playbooks all pull from NetBox at runtime. When NetBox is unavailable, those pipelines fail silently, provisioning stops, and the team loses visibility into the network model at exactly the moment changes are happening. Vigilmon gives you an external, independent monitoring layer for NetBox: web UI availability, REST API health, background worker process status, SSL certificate expiry, and alerting for a system your entire network automation stack depends on.

What You'll Build

• A web UI availability monitor confirming the NetBox frontend is accessible
• A REST API health check verifying the NetBox API is responding and processing requests
• A background worker status check (RQ workers that handle async tasks)
• SSL certificate monitoring for your NetBox domain
• Alerting configured for a source-of-truth-critical system

Prerequisites

• NetBox (v3.x or v4.x) installed and accessible via HTTPS
• A NetBox API token (read-only access is sufficient for health checks)
• A free account at vigilmon.online

Step 1: Monitor the NetBox Web UI

The NetBox web frontend is served by Gunicorn behind Nginx or Apache. A Gunicorn worker crash, a failed Django migration after an upgrade, or a database connectivity issue can take the UI down while the server process stays running. Monitor the NetBox login page directly:

curl -I https://your-netbox.example.com/

A healthy response returns 200 with the NetBox login page. Add the monitor:

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://your-netbox.example.com/.
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Keyword: NetBox (appears in the page title of a healthy installation).
6. Label: NetBox - Web UI.
7. Click Save.

Reverse proxy: NetBox is typically deployed behind Nginx. A Gunicorn crash returns a 502 Bad Gateway from Nginx — Vigilmon catches this as a non-200 response. An Nginx crash would return a connection refused/timeout. Both scenarios fire the alert.

Step 2: Monitor the NetBox REST API

NetBox's REST API is the interface used by Ansible, Terraform, automation pipelines, and developer tooling. The API has its own Gunicorn worker pool and can degrade independently of the web UI in multi-process deployments. Verify it is responding:

curl -I https://your-netbox.example.com/api/

A healthy response returns 200 with the NetBox API root endpoint listing all available API endpoints. Add the monitor:

1. Add Monitor → HTTP.
2. URL: https://your-netbox.example.com/api/.
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Keyword: dcim (the device/cable module endpoint name, present in every healthy NetBox API root).
6. Label: NetBox - REST API Root.
7. Click Save.

Step 3: Add an Authenticated API Smoke Test

The unauthenticated root check confirms the API is routing, but it does not verify that authentication, database queries, or application logic are functioning. Add an authenticated smoke test using a read-only API token:

Create a dedicated read-only API token in NetBox:

1. In the NetBox UI, go to Admin → API Tokens → Add Token.
2. User: create a vigilmon-monitor user with read-only permission to any object type.
3. Generate and copy the token.

Then verify the authenticated probe works:

curl -H "Authorization: Token your-api-token" \
  https://your-netbox.example.com/api/status/

A healthy response returns a JSON object with the NetBox version and Python version:

{
  "netbox-version": "4.1.0",
  "python-version": "3.11.4",
  ...
}

Add the monitor:

1. Add Monitor → HTTP.
2. URL: https://your-netbox.example.com/api/status/.
3. Request headers: Authorization: Token your-api-token.
4. Check interval: 5 minutes.
5. Expected status: 200.
6. Keyword: netbox-version.
7. Label: NetBox - API Status (Authenticated).
8. Click Save.

What this catches: Database connectivity failures, Django ORM errors after a failed migration, and permission system issues that would leave the unauthenticated API root working while authenticated queries fail.

Step 4: Monitor the NetBox Background Worker

NetBox uses Redis Queue (RQ) workers to handle background tasks: script execution, webhooks, reports, and scheduled jobs. If the RQ worker process dies, webhooks stop firing, scripts stop running, and reports never complete — but the web UI and API appear fully operational. NetBox 3.5+ exposes a worker health endpoint:

curl -H "Authorization: Token your-api-token" \
  https://your-netbox.example.com/api/status/

Look for the rq-workers-running field in the response:

{
  "rq-workers-running": 1,
  ...
}

Add the monitor:

1. Add Monitor → HTTP.
2. URL: https://your-netbox.example.com/api/status/.
3. Request headers: Authorization: Token your-api-token.
4. Check interval: 5 minutes.
5. Expected status: 200.
6. Keyword: rq-workers-running (present when workers are reported in the status response).
7. Label: NetBox - RQ Worker Status.
8. Click Save.

Worker count: NetBox reports the count of running workers. A zero-worker state ("rq-workers-running": 0) will still return 200 — the keyword check confirms the field is present but does not verify the count. For a count-sensitive check, use Vigilmon's response body matching combined with a webhook to your alerting system.

Step 5: Monitor SSL Certificates

NetBox is accessed by automation pipelines, Ansible playbooks, and developer tooling — all of which will break immediately on certificate expiry:

curl -v https://your-netbox.example.com/ 2>&1 | grep -i "expire"

Add SSL monitoring:

1. Add Monitor → SSL Certificate.
2. Domain: your-netbox.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

Automation pipeline impact: When the NetBox SSL certificate expires, Ansible playbooks and Python scripts using requests will throw SSLError exceptions at runtime — typically at the worst possible moment during a network change window. The 30-day Vigilmon alert gives your team a full month to renew before any pipeline impact.

Step 6: Monitor a Specific Data Endpoint

For NetBox installations where the device inventory or IP address database is the critical output, add a monitor on a specific API endpoint that confirms data is being served correctly. This catches scenarios where the database is up but NetBox's data layer is broken:

curl -H "Authorization: Token your-api-token" \
  "https://your-netbox.example.com/api/dcim/devices/?limit=1"

A healthy response returns a paginated JSON object with a count field:

{"count": 1234, "next": null, "previous": null, "results": [...]}

Add the monitor:

1. Add Monitor → HTTP.
2. URL: https://your-netbox.example.com/api/dcim/devices/?limit=1.
3. Request headers: Authorization: Token your-api-token.
4. Check interval: 5 minutes.
5. Expected status: 200.
6. Keyword: count.
7. Label: NetBox - Device Inventory Endpoint.
8. Click Save.

Step 7: Configure Alerting

In Vigilmon under Settings → Notifications, configure alert channels for your network team:

| Monitor | Trigger | Action | |---|---|---| | NetBox - Web UI | Non-200 or NetBox keyword missing | Gunicorn down or Django broken; check Gunicorn service and Nginx error logs | | NetBox - REST API Root | Non-200 or dcim keyword missing | API routing broken; check Gunicorn worker count and Nginx upstream config | | NetBox - API Status (Authenticated) | Non-200 or netbox-version missing | Database or auth failure; check PostgreSQL status and Django migration state | | NetBox - RQ Worker Status | Non-200 or rq-workers-running missing | Worker status API broken; separately verify RQ worker process is running | | NetBox - Device Inventory | Non-200 or count missing | Data layer failure; check PostgreSQL queries and NetBox error logs | | SSL Certificate | < 30 days to expiry | Renew certificate immediately; automation pipelines will break on expiry |

Alert sensitivity: Set all NetBox monitors to alert after 2 consecutive failures. NetBox is typically accessed by automated tooling on a fixed schedule, not continuously, so a single failed check is more likely to be a transient network blip than a real outage. However, if NetBox backs critical change management workflows, tighten this to 1 failure.

Escalation path: Route NetBox alerts to your network operations and platform engineering channels. NetBox unavailability during active change windows (when engineers are provisioning devices or updating IP allocations) is particularly disruptive.

Common NetBox Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Gunicorn process crash | Web UI fires with 502 Bad Gateway from Nginx | | PostgreSQL database unreachable | API Status fires; Web UI may show Django error page (500) | | Failed Django migration after NetBox upgrade | API Status fires; Web UI shows 500 error | | Redis unavailable (RQ workers cannot process) | RQ Worker Status shows issue; Web UI and API appear operational | | NetBox upgrade breaks API schema | Device Inventory monitor fires with unexpected response format | | TLS certificate expires | SSL monitor alerts at 30-day threshold; all HTTPS monitors fail together | | Nginx misconfiguration after update | Web UI fires; direct Gunicorn port may still be accessible | | Disk full on NetBox host | PostgreSQL write failures; API Status and inventory monitors fire | | NetBox custom scripts/plugins causing OOM | Gunicorn workers crash; Web UI returns 502 or 500 | | Network partition isolating NetBox host | All monitors fire simultaneously |

Why Monitor NetBox with an External Tool

NetBox is often the only authoritative source of IP allocations, VLAN assignments, and device inventory for a network. When it is unavailable, automation pipelines that query NetBox at runtime fail silently or cache stale data. The insidious part: failures in upstream automation (Ansible playbooks that cannot reach NetBox) often manifest as configuration drift or provisioning errors, not immediately as visible service outages. Vigilmon catches NetBox unavailability at its source, giving your team a direct alert the moment the service degrades — before downstream automation failures surface in production.

NetBox is critical network operations infrastructure, and infrastructure that manages your infrastructure requires its own monitoring. Vigilmon provides the external layer: web UI availability, API health, background worker status, data endpoint integrity, and SSL certificate expiry — all checked independently from outside your network.

Start monitoring NetBox in under 5 minutes — register free at vigilmon.online.