tutorial

Uptime monitoring for TrueNAS storage platform

TrueNAS (formerly FreeNAS) is enterprise-grade network-attached storage trusted with petabytes of critical data. When TrueNAS goes offline — even briefly — N...

TrueNAS (formerly FreeNAS) is enterprise-grade network-attached storage trusted with petabytes of critical data. When TrueNAS goes offline — even briefly — NFS mounts hang, SMB connections drop, iSCSI volumes go read-only, and replication jobs fail silently. The longer it takes to detect the failure, the deeper the data access disruption runs.

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

  • Monitoring the /api/v2.0/system/state REST endpoint
  • Monitoring the TrueNAS web UI availability
  • TCP port checks for SMB (445)
  • SSL certificate alerts
  • Heartbeat monitoring for scheduled scrub and replication tasks

Prerequisites

  • TrueNAS CORE 13.x or TrueNAS SCALE 23.x / 24.x running with the web UI accessible
  • API key generated from the TrueNAS UI (System → API Keys)
  • A free account at vigilmon.online

Part 1: The TrueNAS REST API health endpoint

TrueNAS exposes a full REST API at /api/v2.0. The most useful endpoint for external health monitoring is:

GET /api/v2.0/system/state

This endpoint returns a JSON string representing the system boot state:

"READY"

On TrueNAS SCALE, the same endpoint is available at the same path. A healthy system returns HTTP 200 with body "READY". During boot, upgrades, or degraded states, it returns "BOOTING", "SHUTTING_DOWN", or an error.

Verify the endpoint manually

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://truenas.example.com/api/v2.0/system/state

Expected response:

"READY"

To generate an API key without full admin access, create a dedicated monitoring user in Accounts → Users and generate an API key for that account.

Part 2: Expose the API for external monitoring

The TrueNAS web UI and API run on the same nginx instance (port 443 with HTTPS or port 80 without). The API is accessible from the same base URL as the web UI.

If TrueNAS is on a private network, use one of these approaches:

Option A — WireGuard VPN (recommended for home lab)

TrueNAS SCALE includes a built-in WireGuard plugin. Connect Vigilmon's monitoring nodes are not inside your VPN, so this option only works if you run Vigilmon's open-source agent inside your network and push results to the Vigilmon API.

Option B — Reverse proxy on your edge server

If you have an internet-facing server, proxy only the health endpoint:

server {
    listen 443 ssl;
    server_name truenas-health.example.com;

    ssl_certificate     /etc/letsencrypt/live/truenas-health.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/truenas-health.example.com/privkey.pem;

    location = /api/v2.0/system/state {
        proxy_pass https://192.168.1.100/api/v2.0/system/state;
        proxy_set_header Authorization "Bearer YOUR_API_KEY";
        proxy_ssl_verify off;  # If TrueNAS uses a self-signed cert internally
    }

    location / {
        return 403;
    }
}

Option C — Direct access (for internet-facing TrueNAS deployments)

If TrueNAS is directly on the internet (not recommended for most deployments), ensure the API is behind a valid TLS certificate and point Vigilmon at https://truenas.example.com/api/v2.0/system/state.

Part 3: Set up HTTP monitoring in Vigilmon

Monitor the system state endpoint

  1. Log in to vigilmon.online and click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: https://truenas.example.com/api/v2.0/system/state
  4. Set interval to 1 minute.
  5. Under Custom headers, add:
    • Key: Authorization
    • Value: Bearer YOUR_API_KEY
  6. Add a keyword check: must contain READY.
  7. Add your alert channel.
  8. Click Save.

The keyword check on READY means you get alerted not only when the endpoint is unreachable, but also when TrueNAS is stuck in a non-ready state (booting after a crash, for example) without being fully down.

Monitor the web UI

The TrueNAS web UI is the primary administration interface. Monitor it separately from the API to catch UI failures independently:

  1. Click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: https://truenas.example.com/
  4. Set interval to 1 minute.
  5. Add a keyword check: must contain TrueNAS or FreeNAS.
  6. Click Save.

Part 4: TCP port monitoring for SMB/CIFS

SMB on port 445 is the protocol used by Windows, macOS (with SMB enabled), and Linux clients for file access. When the Samba daemon crashes or the network stack fails, port 445 stops responding before any higher-level API does.

  1. In Vigilmon, click Add Monitor.
  2. Choose TCP monitor.
  3. Enter:
    • Host: truenas.example.com
    • Port: 445
  4. Set interval to 1 minute.
  5. Name it TrueNAS SMB.
  6. Add your alert channel.
  7. Click Save.

For iSCSI deployments, add a second TCP monitor for port 3260:

  1. Click Add Monitor, choose TCP monitor.
  2. Host: truenas.example.com, Port: 3260.
  3. Name it TrueNAS iSCSI.

For NFS deployments, add TCP monitor for port 2049.

Part 5: SSL certificate monitoring

TrueNAS serves its web UI over HTTPS. Whether you use a Let's Encrypt certificate (configured via System → Certificates → ACME DNS) or a manually uploaded certificate, expiry tracking is critical. An expired certificate blocks all web UI access and breaks any automation that uses the REST API over TLS.

  1. In Vigilmon, click Add Monitor.
  2. Choose SSL monitor.
  3. Enter: truenas.example.com
  4. Set alert threshold to 21 days before expiry.
  5. Add your alert channel.

If you expose the API through a separate proxy domain (e.g., truenas-health.example.com), add an SSL monitor for that domain too.

Part 6: Heartbeat monitoring for scrub and replication tasks

TrueNAS runs periodic tasks — pool scrubs, replication jobs, cloud sync, and S.M.A.R.T. tests — that are critical to data integrity but produce no alerts when they fail silently.

Set up heartbeat monitors

Create one heartbeat monitor per critical periodic task.

For monthly pool scrub:

  1. In Vigilmon, click Add Monitor.
  2. Choose Heartbeat monitor.
  3. Name it TrueNAS Pool Scrub.
  4. Set interval to 30 days with a 48-hour grace period.
  5. Copy the heartbeat URL: https://hb.vigilmon.online/ping/scrub123
  6. Click Save.

For daily replication:

  1. Create another heartbeat monitor named TrueNAS Replication.
  2. Set interval to 24 hours with a 4-hour grace period.
  3. Copy the heartbeat URL: https://hb.vigilmon.online/ping/repl456

Wire heartbeats into TrueNAS tasks

TrueNAS supports custom pre- and post-scripts for periodic tasks (Tasks → Cron Jobs). Add a post-script that pings Vigilmon after the task completes:

#!/bin/bash
# Post-script for pool scrub — add as a cron job in TrueNAS UI
# Tasks → Cron Jobs → Add

POOL="tank"
HEARTBEAT_URL="https://hb.vigilmon.online/ping/scrub123"

# Run scrub and wait for completion
zpool scrub $POOL
while zpool status $POOL | grep -q "scrub in progress"; do
    sleep 60
done

# Check if scrub completed without errors
if zpool status $POOL | grep -q "scrub repaired 0B"; then
    curl -fsS "$HEARTBEAT_URL"
else
    echo "Scrub completed with errors — not pinging heartbeat" >&2
fi

For replication tasks, TrueNAS exposes them via the API. Trigger and monitor them in a script:

#!/bin/bash
# Post-replication heartbeat script

HEARTBEAT_URL="https://hb.vigilmon.online/ping/repl456"
API_KEY="YOUR_API_KEY"
TASK_ID=1  # Your replication task ID

# Start replication and wait
RESULT=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "https://localhost/api/v2.0/replication/run" \
  -H "Content-Type: application/json" \
  -d "{\"id\": $TASK_ID}")

# If replication succeeded, ping Vigilmon
if echo "$RESULT" | grep -q '"state": "SUCCESS"'; then
    curl -fsS "$HEARTBEAT_URL"
fi

Part 7: Webhook alerts and incident response

Configure a webhook in Vigilmon to receive DOWN/UP events and integrate with your incident management workflow:

# truenas_alert_handler.py
from flask import Flask, request

app = Flask(__name__)

STORAGE_MONITORS = {'TrueNAS SMB', 'TrueNAS iSCSI', 'TrueNAS NFS'}

@app.post('/webhook/vigilmon')
def handle_truenas_alert():
    data = request.json
    monitor_name = data.get('monitor_name', '')
    status = data.get('status')

    if status == 'down':
        if monitor_name in STORAGE_MONITORS:
            # Storage protocol down — high severity
            page_oncall(monitor_name, severity='P1')
        else:
            # API or UI down — medium severity
            page_oncall(monitor_name, severity='P2')

    return '', 204

Vigilmon sends this payload on state transitions:

{
  "monitor_id": "mon_abc123",
  "monitor_name": "TrueNAS SMB",
  "status": "down",
  "host": "truenas.example.com",
  "port": 445,
  "checked_at": "2026-07-12T03:01:00Z",
  "response_time_ms": 5000
}

Summary

Your TrueNAS deployment now has six layers of monitoring:

  1. /api/v2.0/system/state endpoint — confirms TrueNAS is booted and ready, with a READY keyword check, polled every minute.
  2. Web UI monitor — catches UI failures independently of the API and storage services.
  3. SMB TCP check (port 445) — alerts within 60 seconds when Windows/macOS file shares stop responding.
  4. SSL monitor — alerts 21 days before the management certificate expires and blocks API access.
  5. Pool scrub heartbeat — detects silently failed monthly scrubs before data integrity degrades.
  6. Replication heartbeat — detects silently failed backup replication before a disaster recovery situation reveals the gap.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history. You get notified within 60 seconds of any failure across the application, storage protocol, and certificate layers.

Monitor your TrueNAS storage platform free at vigilmon.online

#truenas #freenas #nas #monitoring #storage #smb #zfs #devops

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