The 2024 source tutorial addressed a display/mapping compatibility problem on non-ZimaCube hardware. It assumed the SATA or NVMe device could already be seen by Linux tools such as lsblk or lspci, but ZimaOS's storage shelf did not map the third-party controller layout correctly.
That distinction matters today because current ZimaOS has since received several third-party storage fixes. ZimaOS 1.4.4 explicitly fixed third-party NVMe disks appearing missing in Storage, and 1.6.1 optimized the disk-shelf display logic for third-party machines with many disks. Update first before editing the historical configuration file.
The Historical SATA Fix Used SataStartNumber
The official source told SATA users to inspect controller addressing with:
lsblk -o hctland then edit /etc/casaos/local-storage.conf so SataStartNumber matched the HCTL numbering expected by the machine.
The Historical NVMe Fix Used PCI Addresses
For NVMe devices, the source used lspci to identify PCI addresses and placed them in the NVME field of the same configuration file before restarting zimaos-local-storage.
The Thread Contains a Real Separator Disagreement
The official 2024 text says multiple NVMe addresses should be separated with commas. In October 2025, a community user reported that commas did not work on their system and that spaces did.
This contradiction should remain visible. It is evidence that the manual file format or parser behavior changed or differed between versions; it is not a reason to declare one separator universally correct for current ZimaOS.
ZimaOS 1.4.4 Added a Product-Level Third-Party NVMe Fix
IceWhale's 1.4.4 release notes explicitly say that NVMe disks from third-party devices showing as missing in Storage were fixed.
See the official third-party NVMe display fix.
ZimaOS 1.6.1 Further Optimized Large Third-Party Disk Shelves
IceWhale later optimized disk-shelf display logic when third-party devices have too many disks. That directly overlaps the old UI-mapping problem and is another reason current users should not start by editing a 2024 config.
First Determine Whether the Disk Is Missing from Linux or Only the UI
- If
lspci/lsblkcannot see the device, investigate hardware, controller mode, power, seating, and driver support. - If Linux sees the device but Storage does not, collect the current ZimaOS version and UI/storage-service evidence.
Treat local-storage.conf Edits as Historical/Advanced
ZimaOS is now a more immutable appliance OS than many general Linux distributions. Manual edits under /etc can be version-sensitive and may be replaced by later updates. Keep a copy of the original file and use current support guidance if the modern UI still misidentifies disks.
A Missing Disk Tile Is Not the Same as a Missing Disk
The source tutorial was primarily about how third-party disks were arranged and exposed in the ZimaOS Storage UI. If lsblk and kernel logs see a drive but the Storage page does not display it correctly, the problem is different from a controller/driver that cannot detect the disk at all.
Back Up local-storage.conf Before Editing It
The historical method modifies a native ZimaOS configuration file. Save the original file first and record the current ZimaOS version so you can revert if the disk shelf becomes worse after the change.
Because OTA releases have since changed third-party disk handling, an old hand-edited value may also become obsolete after update.
PCI Addresses Can Change When Hardware Topology Changes
Moving an NVMe card to another slot, changing a PCIe bifurcation setting, or updating platform firmware can change how devices enumerate. A hard-coded address list therefore belongs to that hardware topology, not to the SSD model itself.
Preserve the Source's Separator Disagreement
The official 2024 instructions describe comma-separated NVMe addresses, while a later community user said spaces worked on their system and commas did not. There is not enough source evidence to replace the official syntax universally with the community variant.
On a current release, update first and use the exact current parser behavior before editing the field.
Large Third-Party Disk Shelves Received Later Product-Level Improvements
ZimaOS 1.6.1 specifically improved display behavior for third-party devices with larger disk counts. Users with HBA cards, multi-bay enclosures, or more than six drives should therefore reproduce the issue on the current release before changing legacy shelf-number settings.
Third-Party Disk Display FAQ
Does a disk missing in the ZimaOS shelf mean Linux cannot see it?
No. The original tutorial specifically addressed cases where the hardware existed but the UI mapping was wrong.
Did ZimaOS later add official fixes?
Yes. 1.4.4 fixed third-party NVMe disks appearing missing, and 1.6.1 optimized third-party disk-shelf display.
Should current users blindly edit SataStartNumber or NVME?
No. Update and confirm the current failure layer first.
