Skip to content

discover.md

Latest commit

 

History

History
222 lines (149 loc) · 7.34 KB

discover.md

File metadata and controls

222 lines (149 loc) · 7.34 KB
Raw

SMART Sniffer -- Drive Discovery

Drive Discovery (--discover)

The --discover command probes every drive on your system, tests whether SMART data is readable, detects protocol mismatches, and offers to write the correct config for you. It's the fastest way to get SMART Sniffer working on NAS devices and non-standard hardware.

When to use it

Run --discover when:

  • You just installed the agent on a NAS (Synology, QNAP, TrueNAS) and want to confirm your drives are detected
  • Drives show as UNSUPPORTED in Home Assistant
  • You added or replaced a drive and want the agent to pick it up
  • You're not sure if your hardware needs device_overrides

You don't need --discover on standard Linux, macOS, or Windows machines with SATA or NVMe drives. Those are detected automatically by smartctl --scan and work out of the box.

How to run it

sudo smartha-agent --discover

The agent must already be installed. --discover uses the same smartctl binary the agent uses at runtime, so if the agent works, discovery works.

What it does

Discovery runs in three phases:

Phase 1: Standard scan

Runs smartctl --scan-open (or --scan as fallback) to find all drives the OS knows about. For each drive, it tests whether SMART data is readable using the reported protocol.

Phase 2: Platform-specific probing

If the system is detected as Synology (via /etc/synoinfo.conf or the presence of /dev/sata1), discovery also probes the proprietary /dev/sata1 through /dev/sata8 paths that smartctl --scan doesn't find on its own.

QNAP is detected via /etc/config/qpkg.conf or /sbin/get_hd_smartinfo. On QNAP, the agent notes that SAT fallback is handled automatically at runtime.

Phase 3: SAT fallback testing

For any drive where the initial protocol (usually SCSI) fails to return SMART data, discovery automatically retries with SAT (SCSI-to-ATA Translation). NAS devices commonly report SATA drives as SCSI through their HBA controllers -- SAT is the fix.

Example output

Standard Linux (no issues)

SMART Sniffer -- Drive Discovery

Scanning drives...

  /dev/sda
    Protocol:   ATA
    SMART data: Yes
    Model:      Samsung SSD 870 EVO 1TB
    Serial:     S1234567890
    Result:     OK

  /dev/nvme0
    Protocol:   NVMe
    SMART data: Yes
    Model:      WD Black SN770 500GB
    Serial:     W1234567890
    Result:     OK

Found 2 drive(s). 2 readable.
No config changes needed.

Synology (protocol fix needed)

SMART Sniffer -- Drive Discovery

Scanning drives...

  Standard scan found 0 drives.

Detected Synology platform. Probing /dev/sata paths...

  /dev/sata1
    Scan protocol: sat
    SMART data:    Yes
    Model:         WD Red Plus 4TB
    Serial:        WD-WCC7K1234567
    Result:        Needs device_override (not found by standard scan)

  /dev/sata2
    Scan protocol: sat
    SMART data:    Yes
    Model:         WD Red Plus 4TB
    Serial:        WD-WCC7K7654321
    Result:        Needs device_override (not found by standard scan)

  /dev/sata3 -- not present
  /dev/sata4 -- not present

Found 2 drive(s). 2 readable.
2 drive(s) need device_overrides in your config.

Proposed additions to config.yaml:

  device_overrides:
    - device: /dev/sata1
      protocol: sat
    - device: /dev/sata2
      protocol: sat

Write to /etc/smart-sniffer/config.yaml? [Y/n]:

QNAP (auto-handled)

SMART Sniffer -- Drive Discovery

Scanning drives...

  /dev/sda
    Scan protocol: SCSI
    SMART data:    No
    SAT retry:     Yes -- SMART data available
    Model:         Seagate IronWolf 8TB
    Serial:        ZA1234567
    Result:        OK (agent will auto-detect SAT at runtime)

Detected QNAP platform.

Found 1 drive(s). 1 readable.
No config changes needed -- the agent handles protocol detection automatically.

What it writes to config

When drives need device_overrides, discovery shows you exactly what it will write and asks for confirmation. It only adds a device_overrides section -- it never modifies your existing config fields (port, scan_interval, token, etc.).

Before writing, it automatically backs up your config to config.yaml.bak.

Example addition:

device_overrides:
  - device: /dev/sata1
    protocol: sat
  - device: /dev/sata2
    protocol: sat

After writing, restart the agent to apply:

sudo systemctl restart smart-sniffer

Dry run mode

To see what discovery would find without modifying your config:

sudo smartha-agent --discover --no-write

This runs the full scan and shows the proposed config changes but skips the write step.

Re-running discovery

You can re-run --discover at any time. Common reasons:

  • Added a new drive -- re-run to detect it and add its override
  • Replaced a drive -- the new drive may have a different path or protocol
  • Drives show as UNSUPPORTED after an update -- re-run to re-test protocol detection

Important: --discover appends device_overrides to your config. If you run it multiple times, you may end up with duplicate entries. Check your config.yaml after re-running and remove any duplicates.

When discovery isn't enough

Discovery handles protocol detection and Synology/QNAP platform quirks. It doesn't help with:

  • Virtual disks in VMs -- virtual disk controllers don't pass SMART commands regardless of protocol. See the Virtual Machines guide or the Proxmox guide.
  • Hardware RAID controllers -- if your drives sit behind a hardware RAID controller (MegaRAID, Adaptec, etc.), smartctl needs a RAID-specific device type (-d megaraid,0). Discovery doesn't probe RAID controllers yet. See the RAID Controllers guide for controller identification and config examples.
  • USB-attached drives -- some USB enclosures don't pass SMART commands. Try -d sat manually with smartctl to test.

Config preservation warning

If you later reinstall the agent and choose "N" at the "Keep current settings?" prompt, the installer rewrites config.yaml from scratch. This will erase your device_overrides. The installer does not currently preserve custom config sections during reconfigure.

To avoid losing your overrides:

  1. Choose "Y" (keep current settings) during reinstall if you only need to update the agent binary
  2. Back up your config.yaml before reinstalling
  3. Re-run --discover after reinstalling if you chose "N"

Manual device_overrides

You don't have to use --discover. You can write device_overrides by hand in config.yaml:

device_overrides:
  - device: /dev/sata1
    protocol: sat
  - device: /dev/sata2
    protocol: sat
  - device: /dev/sdb
    protocol: scsi

Each entry needs:

  • device -- the block device path (e.g., /dev/sata1, /dev/sda)
  • protocol -- the smartctl device type (sat, scsi, nvme, ata, or a RAID type like megaraid,0)

Discovery is just the automated way to generate these entries. The result is the same either way.

Related