Unraid HBAviewer

Monitor LSI / Broadcom SAS Host Bus Adapters (HBAs) directly from Unraid — temperature, PHY health, attached drives, SMART, the firmware event log, and real-time performance graphs — across three controller generations, with the correct backend auto-detected per card. An optional, opt-in firmware/BIOS update tab is available for users who need it.

Inspired by DevlinDelFuego for the SAS2308 / 9207-8i. This was a project I had been working on for a while with a similar capability but extends it to SAS3 (9300) and SAS3.5 tri-mode (9400) controllers and multi-controller systems since I have SAS3 HBAs. I wanted something that had metrics and firmware/bios flashing capability so I had a bunch of scripts but didn't know how to tie it together cleanly until I saw Devlin's program.

Supported hardware

The plugin detects the controller generation and uses the right tool automatically:

Multiple controllers are shown side by side. Both SAS and SATA drives are supported.

SAS3 / SAS3.5 cards need storcli installed on the system — Broadcom's CLI, which is not bundled here (it's proprietary). The easiest way to install it on Unraid is the storcli plugin by dkaser — search "storcli" in Community Applications. SAS2 cards use the bundled lsiutil and need nothing extra.

Features

• Overview — per-controller temperature gauge with a configurable alert threshold, plus a real health rollup (goes yellow/red on high temp, a failed drive, or PHY errors — not just heat). Shows chip, firmware, BIOS, driver version, IT/IR mode, connected-drive count, and PCIe info. Pre-P20 SAS2 firmware is flagged; cards with no onboard sensor show N/A · no sensor instead of erroring.
• HBA Health — five independent indicators (thermal, link integrity, topology, host link, controller read) with a worst-of rollup and a reason string naming the offending PHY. An indicator that cannot be measured reads grey/unknown, never green — a collector that times out or a card that is pulled must not look healthy.
• PHY Health — per-PHY link state, negotiated speed, attached SAS address, and error counters (invalid DWords, disparity, loss-of-sync, reset) — read from the controller (lsiutil) or from Linux sysfs (mpt3sas) on SAS3/3.5. Set a baseline per controller and every counter is then shown as a delta and an errors/hour rate, so "40,000 invalid DWords two months ago" stops looking like "40,000 last night". The baseline lives on /boot and survives reboots; a reboot or driver reload invalidates it rather than reporting a negative delta.
• Top offenders — above the PHY table, the PHYs with the highest error rate since the baseline, each named by the drive it serves (enclosure/slot, or /dev/sdX on SAS2). PHYs with no baseline are excluded rather than ranked at zero — zero would read as "measured and clean" when it means "never measured".
• Attached Drives — /dev name, what Unraid calls the disk (Parity, Disk 1, Cache), enclosure/slot, HBA port, model, serial, state, size, SAS address, link speed, firmware, and a per-drive SMART button. The /dev name and the Unraid slot appear on the PHY and SMART tables too, so a row here can be matched against the Main page without tracking sdX by eye.
• Array Map — a grid of the physical bays, arranged the way they sit in the chassis, so a problem drive is a place you can walk to rather than a slot number. You place each drive once — drag it into its bay, or click the drive then the bay — and the layout is saved to /boot; lock it when you are done so a stray click cannot undo it. Copy map puts the layout on your clipboard so it can live somewhere other than the flash drive, Restore map rebuilds it from that text, and Undo covers a mistaken Clear or resize. Colour is the signal: bays stay neutral until something needs attention, a temperature bar makes a hot row visible without reading every number, empty bays are drawn as empty bays, and a disk being rebuilt into parity shows as such. Nothing on the machine knows your chassis layout — on a direct-attach backplane the enclosure/slot addressing is invented by the controller — so this is the one thing the plugin cannot work out for you.
• Locate a drive — blink one drive's activity light from the Drives table or a bay on the Array Map, so a row becomes a bay you can walk to. Needs no SES, no enclosure processor and no GPIO — it works by reading the drive twice a second, so anything with a tray light can be found, including plain HBAs on dumb backplanes. Stops itself after five minutes so a forgotten blink cannot keep a disk awake indefinitely.
• SMART tab — health, temperature, grown defects, pending sectors, and power-on hours for every drive, collected in the background so it never blocks the UI and (on SAS) never spins up a standby drive. The collection is kept until you press Refresh rather than expiring on a timer — reading every drive takes ~1 s each and the numbers change over weeks — and every screen that shows it states how old it is.
• Event Log — the firmware event log, archived to /boot so history survives reboots and firmware ring-buffer wrap, with copy-to-clipboard for support tickets.
• Enclosure / topology — an enclosure summary per controller (direct-attach vs expander/backplane).
• Dashboard tile — at-a-glance temperature and health on the Unraid dashboard (Unraid 7.2+).
• Notifications (opt-in, off by default) — sends one Unraid notification each time a controller's health status changes, and never repeats while it stays the same. Delivery follows your existing Unraid notification settings.
• Diagnostic bundle — one button collects the raw storcli/lsiutil output, the sysfs state and the plugin's own parsed JSON into a single archive for a bug report. Anonymised by default with one length-preserving map for the whole bundle, so serials, WWNs, SAS addresses and the hostname are replaced while models, sizes, firmware versions, temperatures and error counters stay real. Your flash GUID, licence key and share names are never collected at all.
• Export / API — a read-only JSON snapshot of every controller (/plugins/hbaviewer/export.php) plus the same data in Prometheus text format (?format=prometheus), for Homepage-style widgets and dashboards. Both are session-gated, so an unauthenticated Prometheus scraper cannot poll them — see HOWTO.md.
• Performance graphs (real-time, in-browser) — live per-controller throughput, IOPS, %util, latency, PHY error-rate, and temperature, sampled ~2 s from /proc/diskstats and sysfs (zero-dependency — no sampler daemon, no flash writes; history lives in the browser and resets on reload).
• Firmware / BIOS Update (advanced, opt-in, off by default) — an assisted flash page that detects the card + running firmware, runs a read-only per-controller sanity check, takes your model-correct image, and flashes one controller behind hard guardrails with a live log. See the safety section below.

All monitoring data is read directly from the HBA (storcli / lsiutil), Linux sysfs, and smartctl — no agents, no polling daemons, no external calls.

Firmware / BIOS updates (advanced, opt-in)

⚠ Flashing HBA firmware can permanently brick your controller. This feature is off by default and is for users who already know how to flash an LSI/Broadcom HBA from a console. If you are not sure, do not enable it.

HBAviewer is otherwise strictly read-only. The optional Firmware/BIOS Update tab is assisted, not automatic: it detects the card and runs the tools, but you supply the model-correct firmware image and (if not already installed) the flash tool.

Enabling it: Settings → Advanced — Firmware Flashing → tick Enable firmware/BIOS flashing → Save. A red Firmware/BIOS Update button then appears at the bottom of that same Settings page, and is the only way in — the Monitor does not link to it. Reaching the one screen that writes to hardware means coming back past the warning that explains what it costs to get wrong.

How a flash works, per controller:

1. Verify — a read-only listing scoped to that one controller (storcli /cN show or sasNflash -c N -list) confirms the tool sees the exact card you're about to flash.
2. Upload — the exact firmware .bin/.rom for your model (optionally a BIOS .rom, and the sas2flash/sas3flash binary if it isn't in PATH).
3. Confirm & flash — tick the acknowledgement, type FLASH, and flash. A live log streams; on success it prompts you to reboot.

Tools used (auto-detected in PATH, or upload them — none are bundled):

Guardrails (all enforced server-side, not just in the browser):

• Opt-in toggle gates the whole feature (default off).
• The Unraid array must be STOPPED — the flash is refused otherwise.
• Read-only verify first, scoped to the single target controller, so you flash the card you actually confirmed — not another HBA in the box.
• Explicit acknowledgement checkbox and a typed FLASH confirmation.
• Single-flight lock — one flash at a time, never auto-retried.
• Uploaded filenames are sanitised and confined to a fixed working directory.

Caveats — read these:

• Bricking is a real, unavoidable risk if the image doesn't match the card. Double-check the model/chip against the image before you flash.
• The flash tools are proprietary and per-generation — not shipped with the plugin. Install them (e.g. via a storcli/flash plugin) or upload them.
• Some SAS2 cards need a specific sas2flash build (e.g. a 9207-8i wants the P14 tool). Use the right one; the plugin won't second-guess it.
• storcli 94xx flashing semantics vary by firmware package (a downrev may need noverchk); the log is shown verbatim — treat it as best-effort.
• Linux flashers update the BIOS region but cannot erase it.
• Stop any Unassigned Devices on the HBA as well before flashing.

Documentation

Requirements

• Unraid 6.12 or newer (7.2+ for the dashboard tile)
• A supported LSI / Broadcom SAS controller (see the table above)
• For SAS3 / SAS3.5 cards: storcli installed — easiest via the dkaser/unraid-storcli plugin (search "storcli" in Community Applications)
• smartctl (ships with Unraid) for the SMART features
• The lsiutil binary for SAS2 cards is bundled in the .txz — nothing extra is downloaded

Installation

1. In the Unraid web UI go to Plugins → Install Plugin

2. Paste the plugin URL:

   https://raw.githubusercontent.com/FugginOld/Unraid-HBAviewer/main/hbaviewer.plg
   

3. Click Install

After installation, find the monitor under Tools → HBAviewer → HBA Monitor.

Layout

Tools
└── HBAviewer
    └── HBA Monitor   (tabs: Overview · HBA Health · PHY Health · Drives
                              · Array Map · SMART · Event Log · Performance)

User Utilities
└── HBAviewer          (full settings page)
└── HBAviewer Firmware (Firmware/BIOS Update*)
                        *opt-in, off by default; the page and its menu entry
                         only exist once it is enabled

Dashboard
└── HBA Temperature tile (Unraid 7.2+)

Configuration

Open User Utilities → HBAviewer. The settings page opens instantly and shows the detected Access Method (storcli or lsiutil) so you can confirm the right backend is in use before opening the Monitor.

The drive bay map deliberately has no row on this page. Its grid size and its lock live with the map itself (the Array Map tab), because a layout is something you build while looking at it, not a number you set on one page and go check on another. They are still persisted the same way everything else here is.

Save your settings, then click Open HBAviewer Monitor. The Monitor page opens immediately with a "Loading HBA information" banner and reads the hardware in the background — the first read can take up to a minute on slow controllers, and the page fills in automatically when it's ready (no blank hang, no timeout).

Building from source

git clone https://github.com/FugginOld/Unraid-HBAviewer.git
cd Unraid-HBAviewer

# Fetch the lsiutil binary and build the .txz (see build.sh for details)
bash build.sh

# build.sh prints the MD5 and version to update in hbaviewer.plg

The bundled hbaviewer.x86_64 is the original lsiutil v1.70 compiled for Linux x86-64. storcli is not bundled — SAS3/3.5 cards use the copy installed on your system. build.sh also fetches Chart.js (the Performance tab's charting library, MIT) into the plugin dir; like the lsiutil binary it isn't committed to the repo. The Performance tab degrades gracefully with a message if it's absent.

Testing

The shell parsers and PHP helpers have a golden-file test suite that needs no hardware:

bash tests/run.sh

It runs the parser goldens plus the PHP unit tests (using a local php, or the php:8.2-cli Docker image if php isn't installed), and needs GNU awk.

CI additionally syntax-checks every language the plugin ships — php -l, bash -n, node --check — and runs ShellCheck, PHPStan and actionlint on top.

Fixtures are real controller output wherever possible — captured with the scripts/capture*.sh helpers or contributed by reporters on the issue tracker, with identifiers masked length-preservingly so column alignment (which the parsers key on) survives. A fixture that was modelled by hand rather than captured has caused a real bug here before, so treat fixtures as evidence rather than as editable test data.

Credits

• DevlinDelFuego — Unraid-LSIUtil — the original Unraid plugin this repo (Unraid-HBAviewer) is inspired on.
• Thomas Lovell — LSIUtil — the lsiutil binary that makes the SAS2 path possible.
• Broadcom — storcli (used for SAS3 / SAS3.5 controllers) and the original lsiutil source.
• dkaser — unraid-storcli — the easiest way to install storcli on Unraid for SAS3 / SAS3.5 cards.

Special Thanks

Thanks to the early users (in no particular order) @jac2424, @PaliKinG3, @iassis, @t0ffemannen to help fix and troubleshoot the early release bugs.

License

MIT — see LICENSE for details.