Storage Health

Dashboard Status

This module is live for TrueNAS, ASUSTOR NAS units, and UniFi NAS sources through the local UniFi Drive API with SNMP fallback diagnostics.

The card keeps Total Capacity prominent, then combines each source's capacity and pool/volume health into one named system row. Healthy pool and volume details stay folded into the source row, while warning rows still name the affected source or device.

Admin Fields

• TrueNAS URL
• TrueNAS API Key
• Allow TrueNAS self-signed TLS (true/false)
• Capacity warning percent
• ASUSTOR temp warning °C
• ASUSTOR 1 name
• ASUSTOR 1 host/IP
• ASUSTOR 1 SNMP port
• ASUSTOR 1 SNMP community
• ASUSTOR 2 name
• ASUSTOR 2 host/IP
• ASUSTOR 2 SNMP port
• ASUSTOR 2 SNMP community
• UniFi NAS 1 name
• UniFi NAS 1 local URL
• UniFi NAS 1 local username
• UniFi NAS 1 local password
• UniFi NAS 1 local API key
• UniFi NAS 1 allow self-signed TLS (true/false)
• UniFi NAS 1 host/IP
• UniFi NAS 1 SNMP port
• UniFi NAS 1 SNMP community
• UniFi NAS 2 name
• UniFi NAS 2 local URL
• UniFi NAS 2 local username
• UniFi NAS 2 local password
• UniFi NAS 2 local API key
• UniFi NAS 2 allow self-signed TLS (true/false)
• UniFi NAS 2 host/IP
• UniFi NAS 2 SNMP port
• UniFi NAS 2 SNMP community

Admin Layout

The Storage Health admin form is split into collapsible sections for TrueNAS, warning thresholds, ASUSTOR 1, ASUSTOR 2, UniFi NAS 1, and UniFi NAS 2 so each NAS unit can be configured independently without keeping every device field visible at once. TrueNAS and warning thresholds start open; device sections can be expanded as needed.

TrueNAS Setup

Use the URL the dashboard container can reach:

TrueNAS URL: https://192.168.1.50

Create an API key in TrueNAS and paste it into TrueNAS API Key.

The dashboard reads:

• System information.
• Pool health and capacity.
• Disk list and disk state where exposed.
• Active alerts.
• Recent jobs.

If TrueNAS uses its default internal certificate, either put TrueNAS behind a trusted internal reverse proxy or set:

Allow TrueNAS self-signed TLS: true

What The Card Shows

• Prominent total fleet capacity usage.
• Healthy pool and volume count.
• Healthy disk count.
• Active storage alerts.
• Named TrueNAS, ASUSTOR, and UniFi NAS system panels.
• Per-pool and per-volume status and capacity bars.
• Storage-related failed jobs when TrueNAS reports them.
• Recent storage-related jobs as compact status pills.

Open Details on the card to see every raw row the dashboard received.

UniFi NAS polling prefers the local UniFi Drive API when a local URL plus username/password or API key is configured. The dashboard calls /api/auth/login, /proxy/drive/api/v2/storage, and /api/system from the backend, so UniFi credentials stay server-side. Create a local UniFi account with read access to UniFi Drive, set the local URL as a full URL such as https://unas.local or as a bare NAS host/IP such as 10.0.0.18; bare values default to HTTPS. Leave Allow self-signed TLS enabled for the default UniFi certificate unless the console is behind a trusted proxy. If both local username/password and an API key are configured, the dashboard uses the local login session first because that is the best-tested path for UniFi Drive; API-key auth is used when it is the only local API credential or when the session login is blocked by MFA/SSO or login-attempt rate limits. Once a NAS hits one of those session blockers, the dashboard uses API-key auth first for that NAS for six hours to avoid repeatedly triggering UniFi OS login protection. Storage Health diagnostics show the selected auth mode when the local API responds without matching capacity data. The parser handles pool capacity fields returned directly, inside common storage containers, and with snake_case names used by newer UniFi Drive payloads. It also matches globally returned disk rows back to pools when Drive returns pool and disk objects separately. When the Drive API responds but its payload shape does not match known pool or aggregate-capacity fields, Storage Health shows local API response-key diagnostics, matched pool count, and global disk count so the next parser adjustment can match the installed UniFi Drive firmware.

UniFi NAS SNMP remains as a fallback and diagnostic path. SNMP capacity tries the standard host-storage table first, then the common UCD disk table used by many Linux SNMP agents. If a UniFi NAS exposes only partial one-row SNMP tables, the dashboard can match rows by position when indexes differ. If the NAS returns No Such Object for storage OIDs, those replies are ignored as empty tables and Storage Health prompts the operator to configure the local UniFi Drive API, because that firmware is not exposing capacity through SNMP.

Warning Thresholds

Storage capacity warnings default to 90% for TrueNAS, ASUSTOR, UniFi NAS, and the fleet capacity row. ASUSTOR temperature warnings are off by default across system, CPU, and disk readings so normal warm disks do not create alerts until an operator chooses a threshold.

Tune these in the Storage Health admin fields or use environment fallbacks:

STORAGE_CAPACITY_WARNING_PERCENT=90
ASUSTOR_TEMP_WARNING_CELSIUS=0

Set ASUSTOR_TEMP_WARNING_CELSIUS to the Celsius value you want to warn at, or leave it at 0 to keep temperature alerts disabled. Set the capacity threshold to 0 to disable capacity warnings. Disk SMART/status warnings remain status-based and are not affected by the temperature threshold.

API Endpoints Used

The dashboard connects to TrueNAS JSON-RPC 2.0 over WebSocket at /api/current. It authenticates with auth.login_ex using the configured API key and username, and falls back to legacy auth.login_with_api_key on older or migrated systems that still accept that method. Set TrueNAS Username or TRUENAS_USERNAME to the local user that owns the API key; blank values default to root.

The dashboard calls these TrueNAS JSON-RPC methods:

system.info
pool.query
disk.query
alert.list
core.get_jobs

TrueNAS alert text is normalized before display so API-provided HTML line breaks and links appear as readable warning text. This JSON-RPC/WebSocket path avoids the deprecated TrueNAS REST API.

ASUSTOR Setup

ASUSTOR ADM supports SNMP monitoring. The dashboard currently polls ASUSTOR through SNMP v2c using the ASUSTOR enterprise MIB. SNMP v3 is useful in other monitoring tools, but this dashboard integration expects the v1/v2 service and community string.

In ADM, open:

Services > SNMP

Enable:

SNMP V1 / SNMP V2 service: enabled
Community: YOUR_READ_ONLY_COMMUNITY

Use a unique community string instead of public if the NAS and dashboard are not isolated to a trusted management network.

Then enter each NAS in the dashboard admin settings:

ASUSTOR 1 name: Media NAS 1
ASUSTOR 1 host/IP: 192.168.1.60
ASUSTOR 1 SNMP port: 161
ASUSTOR 1 SNMP community: YOUR_READ_ONLY_COMMUNITY

Repeat for ASUSTOR 2 when needed.

ASUSTOR Field Reference

Dashboard field	What to enter	Example
ASUSTOR 1 name	Friendly display name for the NAS. This does not need to match ADM.	Media NAS 1
ASUSTOR 1 host/IP	DNS name or IP address reachable from the dashboard container. Do not include http://, https://, or an ADM web port.	192.168.1.60
ASUSTOR 1 SNMP port	SNMP agent port. ASUSTOR uses UDP 161 by default.	161
ASUSTOR 1 SNMP community	The v1/v2 community string configured in ADM. Treat it like a password.	your-long-community

Use the same pattern for ASUSTOR 2.

Version Details

The dashboard uses:

SNMP version: v2c
Transport: UDP
Default port: 161
ASUSTOR enterprise OID: 1.3.6.1.4.1.44738

ADM itself has supported SNMP since ADM 2.4.0. The dashboard also reads the ADM version through SNMP because ASUSTOR adjusted some disk table columns in ADM 5.1+. That lets the dashboard map disk temperature, size, and S.M.A.R.T. status more safely across ADM versions.

Quick Connectivity Test

From a machine that can reach the NAS, test the standard system description first:

snmpwalk -v2c -c YOUR_READ_ONLY_COMMUNITY -On 192.168.1.60 1.3.6.1.2.1.1.1.0

Then test the ASUSTOR enterprise tree:

snmpwalk -v2c -c YOUR_READ_ONLY_COMMUNITY -On 192.168.1.60 1.3.6.1.4.1.44738

If those commands work from the Docker host but the dashboard still fails, test from inside the container network:

docker exec -it homelab-dashboard snmpwalk -v2c -c YOUR_READ_ONLY_COMMUNITY -On 192.168.1.60 1.3.6.1.4.1.44738

The published dashboard image includes snmpwalk for this reason.

The dashboard uses ASUSTOR's vendor MIB under:

1.3.6.1.4.1.44738

ASUSTOR data shown:

• NAS reachability.
• Model and ADM version when reported by SNMP.
• Volume capacity.
• Disk health count.
• Temperature warnings.
• Volume/RAID status.

ASUSTOR's MIB layout differs slightly between ADM 4.x/5.0 and ADM 5.1+. The dashboard checks the ADM version and maps the disk temperature/S.M.A.R.T. columns accordingly.

UniFi NAS Setup

The dashboard can poll two UniFi NAS / UniFi Drive devices through SNMP. This first integration uses standard SNMP system and host-storage tables so it can report reachability, identity, uptime, and storage capacity without relying on private UniFi Drive API routes.

Step 1: Find The NAS IP Address

Use the local management IP for each UNAS unit. Do not use unifi.ui.com, a Site Manager URL, or the UniFi Drive web URL.

Good examples:

192.168.1.70
unas-1.local

Bad examples:

https://unifi.ui.com
https://192.168.1.70
192.168.1.70:443

Ways to find the IP:

1. Open UniFi Network.
2. Go to Devices.
3. Select the UNAS device.
4. Look for the device IP address in the side panel or device details.

You can also use the local web access address you use for the UNAS, but paste only the hostname or IP into the dashboard.

Step 2: Enable SNMP In UniFi Network

SNMP is configured in the UniFi Network application, not inside the UniFi Drive file browser.

Open:

Settings > CyberSecure > Traffic Logging > SNMP

Then:

1. Enable SNMP.
2. Select v1/v2c.
3. Enter a read-only community string.
4. Click Apply Changes.

Use:

SNMP version: v1/v2c
Community: YOUR_READ_ONLY_COMMUNITY
Port: UDP 161

Use a unique community string instead of public. Treat the community string like a password.

Step 3: Confirm Network Reachability

The dashboard container must be able to reach each UNAS IP on UDP port 161.

Check firewall rules between:

Dashboard container/Docker host -> UNAS IP -> UDP 161

If the UNAS units are on a separate VLAN, allow SNMP from the dashboard host or dashboard container network to the NAS management IPs.

Step 4: Test SNMP Before Saving In The Dashboard

From the Docker host or another machine that can reach the NAS, test the standard SNMP system tree:

snmpwalk -v2c -c YOUR_READ_ONLY_COMMUNITY -On 192.168.1.70 1.3.6.1.2.1.1

Expected result: several lines beginning with 1.3.6.1.2.1.1, usually including system description, uptime, and system name.

Then test the host-storage table:

snmpwalk -v2c -c YOUR_READ_ONLY_COMMUNITY -On 192.168.1.70 1.3.6.1.2.1.25.2.3.1

Expected result: storage rows with descriptions, allocation units, size, and used values. This is what the dashboard uses for capacity.

If the host responds to the system tree but not the storage tree, the dashboard can still show reachability but may not show capacity until UniFi exposes host-storage rows for that device/firmware.

If those commands work from the Docker host but the dashboard still fails, test from inside the dashboard container:

docker exec -it homelab-dashboard snmpwalk -v2c -c YOUR_READ_ONLY_COMMUNITY -On 192.168.1.70 1.3.6.1.2.1.25.2.3.1

The published dashboard image includes snmpwalk for this reason.

Step 5: Enter The Dashboard Settings

Open the dashboard admin page and find Storage Health.

For the first UniFi NAS:

UniFi NAS 1 name: UniFi NAS 1
UniFi NAS 1 host/IP: 192.168.1.70
UniFi NAS 1 SNMP port: 161
UniFi NAS 1 SNMP community: YOUR_READ_ONLY_COMMUNITY

For the second UniFi NAS:

UniFi NAS 2 name: UniFi NAS 2
UniFi NAS 2 host/IP: 192.168.1.71
UniFi NAS 2 SNMP port: 161
UniFi NAS 2 SNMP community: YOUR_READ_ONLY_COMMUNITY

Click Save settings, then use Test saved connection on the Storage Health settings card.

Step 6: Read The Dashboard Result

The card can show:

• UniFi NAS: NAME: identity, uptime, and reachability.
• UniFi NAS Capacity: NAME: combined capacity from returned storage rows.
• UniFi NAS Volumes: NAME: individual storage rows returned by SNMP.

If the identity row works but capacity is missing, the SNMP path is reachable and the remaining issue is likely what that UNAS firmware exposes through the host-storage table.

UniFi NAS Field Reference

Dashboard field	What to enter	Example
UniFi NAS 1 name	Friendly display name for the NAS.	UniFi NAS 1
UniFi NAS 1 host/IP	DNS name or IP reachable from the dashboard container. Do not include http://, https://, or a web UI port.	192.168.1.70
UniFi NAS 1 SNMP port	SNMP agent port. UniFi SNMP uses UDP 161 by default.	161
UniFi NAS 1 SNMP community	The v1/v2c community configured in UniFi. Treat it like a password.	your-long-community

UniFi NAS data shown:

• NAS reachability.
• SNMP system name and description.
• Uptime when reported.
• Storage capacity rows from the standard host-storage table.
• Capacity warnings when a returned storage row is 90% full or higher.

Screenshot Checklist

Use real environment screenshots for these spots:

Screenshot	Capture
asustor-adm-services-snmp.png	ADM desktop with Services > SNMP open.
asustor-adm-snmp-v2-community.png	The enabled SNMP V1 / SNMP V2 service checkbox and Community field. Redact the community string.
dashboard-storage-settings-asustor.png	Dashboard admin Storage Health fields for ASUSTOR 1/2. Redact communities.
dashboard-storage-card-asustor.png	Storage Health dashboard card after ASUSTOR data is polling.
unifi-snmp-settings.png	UniFi Network SNMP settings page showing v1/v2c enabled. Redact the community string.
dashboard-storage-settings-unifi-nas.png	Dashboard admin Storage Health fields for UniFi NAS 1/2. Redact communities.
dashboard-storage-card-unifi-nas.png	Storage Health dashboard card after UniFi NAS data is polling.

Do not use screenshots that expose SNMP community strings, LAN addresses you do not want public, serial numbers, or hostnames you consider sensitive.

Troubleshooting

• 401 or 403: confirm the API key is valid and has enough TrueNAS permissions.
• Certificate error: set Allow TrueNAS self-signed TLS to true or use a trusted reverse proxy.
• Partial data: the dashboard keeps showing available storage data even if one endpoint fails.
• No disks or pools: confirm the API key can read storage and disk information.
• ASUSTOR has no data: confirm SNMP V1 / SNMP V2 service is enabled in ADM, UDP port 161 is reachable from the dashboard container, and the community string matches exactly.
• Timeout: confirm firewall rules allow UDP 161 from the Docker host or dashboard container to the NAS.
• Authentication failure: SNMP v2c usually fails as a timeout when the community string is wrong. Re-copy the community from ADM and save the dashboard settings again.
• Partial ASUSTOR disk data: confirm the NAS is on a supported ADM release and run the enterprise-tree snmpwalk command above to see what the NAS exposes.
• UniFi NAS has identity but no capacity: check the Storage Health volume row for host-storage and UCD table counts, then run the host-storage snmpwalk command above. Some firmware may expose fewer storage rows through SNMP than the UniFi Drive UI.
• UniFi NAS does not respond: confirm SNMP is enabled in UniFi Network, the NAS supports SNMP in its current firmware, and UDP 161 is reachable from the dashboard container.

References

• ASUSTOR SNMP online help: https://www.asustor.com/online/online_help?id=27&lan=en
• ASUSTOR NAS MIB Guide: https://download.asustor.com/college/en/NAS_271_ASUSTOR_NAS_MIB_Guide.pdf
• UniFi SNMP Monitoring: https://help.ui.com/hc/en-us/articles/33502980942615-SNMP-Monitoring-in-UniFi-Network