How to monitor TrueNAS externally

What the alert system cannot report

TrueNAS has a thorough internal alerting system. That is the trap: it is good enough that people assume it covers everything, when it structurally cannot report the failures where TrueNAS is not running.

• The box does not come back from a reboot after an update. Every alert about that outage would have to be sent by the machine that is off.
• Network changes leave the interface unreachable, which is easy to do over a remote session and impossible to alert about afterwards.
• Apps or VMs stop while the middleware keeps answering, so the API is green and the service everyone uses is gone.
• A UPS event, a PSU failure, a tripped breaker. All of these look the same from inside: nothing.

The one signal that covers all of them is absence, observed from somewhere else.

What to check, and a caveat about the API

TrueNAS serves its web interface on port 80 for HTTP and 443 for HTTPS by default, which is unusual for a NAS and worth remembering when you write check URLs. Both are configurable under System and General Settings.

The REST API lives under /api/v2.0. One endpoint answers without credentials: core/ping returns pong, and it is intentionally unauthenticated. Unauthenticated requests are rate limited, so at a one or five minute cadence it is a clean keyword check target.

curl -fsSk https://truenas.example.com/api/v2.0/core/ping
# "pong"

Everything else requires an API key sent as a bearer token. Create one from the toolbar user menu under API Keys; it is shown once. TrueNAS treats API keys as password equivalent, they bypass two factor authentication, and key authentication attempted over plain HTTP is revoked automatically. Use HTTPS, and store the header encrypted, which Undownable does by default.

curl -fsSk https://truenas.example.com/api/v2.0/system/info \
  -H 'Authorization: Bearer YOUR_API_KEY'
# {"version":"...","hostname":"...","uptime_seconds":...}

The caveat: the REST API is deprecated in favour of a versioned JSON-RPC 2.0 API over websocket. The transition began in 25.04 Fangtooth, 25.10 Goldeye added a daily alert when deprecated endpoints are used, and removal is planned for the 26 line. It still works today, which is a good argument for keeping external monitoring to a cheap liveness signal rather than a rich integration you will have to rewrite.

If the interface is not published

It usually should not be. A NAS web interface on the public internet is a login page guarding all of your data, and no monitoring benefit justifies it. Push a heartbeat out instead. TrueNAS can run a cron job from the web interface under Data Protection, or you can add one on the shell:

*/2 * * * * curl -fsS -m 10 https://undownable.com/ping/your-monitor-id > /dev/null

Gate it on the local API so the heartbeat tracks the middleware rather than just the kernel:

*/2 * * * * curl -fsSk -m 10 https://127.0.0.1/api/v2.0/core/ping > /dev/null \
  && curl -fsS -m 10 https://undownable.com/ping/your-monitor-id > /dev/null

Here is where TrueNAS gets more interesting than most services. What you actually care about is not whether the web interface loads, it is whether your pool is healthy. Gate the heartbeat on zpool status and the monitor becomes a pool health alarm that reaches you off site:

*/10 * * * * zpool status -x | grep -q 'all pools are healthy' \
  && curl -fsS -m 10 https://undownable.com/ping/your-monitor-id > /dev/null

A degraded or faulted pool stops the ping, and you get paged whether or not the mail configuration on the box still works. Set the interval generously, say fifteen minutes for a ten minute cron, and keep it as a separate monitor from the liveness heartbeat.

Cover replication and snapshots too

Scheduled replication is a classic silent failure: the task stops being scheduled, and the fact only surfaces when a restore is needed. Give it a heartbeat monitor with an interval slightly longer than the schedule, pinged from the end of the task. The same applies to scrubs: a monthly scrub gets a 35 day window.

Alerts that do not depend on the NAS

TrueNAS alert channels are worth configuring and worth not relying on alone. External delivery reaches you when the box, the link, or the power is the problem:

• ntfy, hosted or self hosted with an access token beginning with tk_ sent as a bearer token, stored encrypted. Do not host it on the NAS you are monitoring.
• Telegram, which needs nothing from your side of the connection.
• Email as a durable fallback, and a webhook if you want to fan out further.

Set a confirmation threshold so an update reboot does not page you, and a maintenance window over update night. If you run apps or VMs here, give the important ones their own checks.