TerraMaster TOS for Home Assistant

Local monitoring of TerraMaster NAS devices from Home Assistant over SSH.

Features

• NAS model, TOS version, Linux distribution and kernel
• Uptime, last restart, CPU, CPU cores, memory and temperature
• Physical disks and SMART health information
• RAID arrays, degradation and synchronization progress
• Volumes, capacity and usage
• Network interfaces, counters and real-time throughput
• SSH, Telnet and SNMP service detection
• Shared-folder discovery from the TOS database
• SMB, NFS and AFP protocol detection
• Secure HTML pages for all shares or one selected share
• English and French translations

The integration polls locally and does not require a cloud account.

Requirements

• Home Assistant with HACS
• SSH enabled on the TerraMaster NAS
• A TOS account allowed to connect through SSH
• Administrator access through sudo for optional SMART, service and shared-folder details

The integration uses read-only commands. The configured password is used for SSH and, when available, read-only sudo collection.

Installation

HACS custom repository

1. Open HACS.
2. Open the menu and choose Custom repositories.
3. Add https://github.com/minimicro34/ha-terramaster.
4. Select Integration as the category.
5. Install TerraMaster TOS.
6. Restart Home Assistant.

Manual installation

Copy:

custom_components/terramaster

to:

/config/custom_components/terramaster

and restart Home Assistant.

Configuration

In Home Assistant:

1. Go to Settings → Devices & services.
2. Select Add integration.
3. Search for TerraMaster TOS.
4. Enter the NAS address, SSH port, username and password.

The default SSH port is 9222, but the configured TOS port can be used.

The SSH host key is recorded during the first connection and checked on later connections.

Shared folders

The main Shared folders sensor displays the number of detected shares.

Its attributes contain:

• the share names;
• all detected protocols;
• open_shares, a secure link to the general shared-folder page.

Each individual shared-folder diagnostic entity keeps the detailed information:

• path, type, visibility and recycle-bin state;
• volume, RAID and filesystem;
• capacity, used space and available space in decimal GB;
• usage percentage;
• SMB, NFS and AFP URLs;
• open_share, a secure link to the HTML page for that share.

Passwords are never included in connection URLs. SMB and AFP URLs can include the configured username so the operating system can request or reuse the password.

Devices and entities

The NAS is the main Home Assistant device. Physical disks, RAID arrays, volumes and network interfaces are represented as child devices where appropriate.

Some metrics require administrator access. When optional privileged collection is unavailable, the basic NAS metrics continue working.

Tested hardware

Confirmed during development:

• TerraMaster F2-210
• TOS 4.2.41

Other TOS 4, TOS 5 and TOS 6 devices may work, but should be treated as unverified until reported by users.

Troubleshooting

Shared folders are missing

Verify that the configured SSH user can run:

sudo sqlite3 -separator '|' /etc/base/nasdb   'SELECT foldername,mntpath,device,type,hidden,recycle FROM share;'

SMART data is missing

Verify that smartctl is installed on the NAS and that the configured account can execute it through sudo.

Authentication or host-key error

Remove and re-add the integration only after confirming that the NAS address and SSH host key change are expected.

Privacy and security

• Communication stays on the local network.
• No cloud service is used.
• The SSH server host key is pinned.
• Shared-folder HTML pages use a random token stored in the Home Assistant config entry.
• Passwords are not exposed in entity attributes or URLs.

Development checks

pytest
mypy custom_components/terramaster
ruff check .

Release history

1.0.0

First stable release with system, SMART, RAID, volume, network, services and shared-folder monitoring.

Contributing

Contributions are welcome.

Please read CONTRIBUTING.md before submitting changes.

For significant changes, please open an issue before submitting a pull request.

Support

If you find TerraMaster TOS for Home Assistant useful and would like to support its development, you can buy me a coffee.

Your support helps me dedicate more time to improving the integration, adding new features, testing additional TerraMaster TOS configurations and fixing issues.

Bug reports, feature suggestions, contributions and GitHub stars are also greatly appreciated.

Please use GitHub Issues for bug reports and feature requests.

When reporting an issue, please include whenever possible:

• TerraMaster NAS model;
• TOS version;
• TerraMaster integration version;
• Home Assistant version;
• a clear description of the problem;
• relevant Home Assistant logs;
• Home Assistant diagnostics.

For SSH or data-collection problems, please also include:

• the authentication method used (password or SSH key);
• whether the SSH connection works outside Home Assistant;
• which sensor or data category is affected;
• relevant command errors, with sensitive information redacted.

Never include passwords, SSH private keys, authentication credentials or other sensitive NAS information.

License

Copyright (c) 2026 minimicro34

This project is licensed under the GNU General Public License v3.0 or later.