SmartCheck is a local Linux web application for testing SAS/SATA hard drives and selecting drives that are suitable for reuse. It reads the device identity, starts a short SMART self-test, tracks its progress, reads the final SMART/SAS report, stores the result in SQLite, and supports barcode selection.
The current interface has 8 test slots. It is designed primarily for directly connected SAS drives through a controller that supports SMART/SCSI passthrough.
- Linux
- Python 3.10 or newer
smartctl7.4 or newer fromsmartmontoolslibcap2-binfor password-free SMART self-test commands- Eight or fewer whole-disk devices visible as
/dev/sdX - A barcode scanner that behaves like a keyboard, if barcode selection is used
On Debian or Ubuntu:
sudo apt update
sudo apt install smartmontools libcap2-bin python3 python3-venv python3-pipThe application must be able to access the disk devices without running the web server as root. The following setup is normally required once per PC:
sudo usermod -aG disk "$USER"
sudo setcap cap_sys_rawio+ep "$(command -v smartctl)"Log out and back in after changing the disk group. Verify the capability:
id -nG
getcap "$(command -v smartctl)"The output of getcap should contain:
cap_sys_rawio+ep
Do not run the web server
with sudo during normal use. Reapply setcap after upgrading the
smartmontools package if the capability is removed.
Copy the complete hdd-triage directory to the new computer. Do not copy
venv/, .venv/, .git/, or Python __pycache__ directories; run.sh
creates the virtual environment automatically.
From the project directory:
cd ~/hdd-triage
chmod +x run.sh
./run.shrun.sh installs the Python dependencies into the local venv/ directory and
starts Uvicorn at:
http://127.0.0.1:8000/
Stop the server with Ctrl+C.
The script accepts these database-reset options:
./run.sh --clear-db
./run.sh --reset
./run.sh -cThey permanently delete the local inventory before starting. Do not use them when historical test results are still needed.
Before starting the application, inspect the devices Linux can see:
lsblk -d -o NAME,PATH,TYPE,TRAN,MODEL,SERIAL,SIZEThe application considers only whole /dev/sdX disks. It ignores partitions
such as /dev/sda1 and NVMe devices such as /dev/nvme0n1.
The first five seconds after application startup are a quarantine period:
- All whole disks already visible are recorded as startup disks and ignored.
- Any disk appearing during those five seconds is also ignored.
- Only a disk connected after the five-second period is assigned to a slot.
- A removed startup disk can be detected if it is reconnected after startup.
This prevents the computer's existing system or storage disks from being tested automatically. To test a disk, start the application first, wait five seconds, and then connect the disk.
Only eight disks can occupy slots. Additional disks are ignored until a slot is released.
After a disk appears after startup, the application:
-
Reads its model and serial number.
-
Starts the short test with the same automatic command that works manually:
smartctl -t short /dev/sdX
-
Reads progress every two seconds with:
smartctl -a /dev/sdX
-
Converts
XX% of test remaininginto completion progress. -
After completion, reads the final extended report:
smartctl -x /dev/sdX
-
Stores the final result and selected SAS values in
data/inventory.db.
For SAS disks, the final report uses values that are actually available from
-x. ATA-only attribute columns that the SAS device does not provide are not
displayed as fake zeroes.
A disk receives PASSED only when all required checks pass:
- SMART Health Status is
OK. - The latest short self-test is
Completed. - Temperature is at most 55 C.
- Grown defects are zero.
- Uncorrected read errors are zero.
- Available pending, reallocated, and uncorrectable sector values meet the configured zero thresholds.
The five main values shown in the interface are:
- SMART Health
- Short self-test
- Temperature
- Grown defects
- Uncorrected read errors
SAS Non-medium errors and SAS link counters such as invalid DWORD,
running-disparity, and loss-of-synchronization counts are retained and shown
as connection warnings when present. They do not automatically fail the disk,
because they may indicate a cable, backplane, or HBA problem rather than a
media defect.
The thresholds are configured in src/config.py.
Click Platten auswählen to open the historical inventory. The inventory
contains results from previous runs, not only disks currently connected to the
computer. Drives with PASSED are selected automatically; you can change the
checkboxes manually.
Click Scanner für Auswahl starten, then scan a drive barcode. The result is:
- PLATTE NEHMEN: the barcode belongs to a selected drive with
PASSED. - PLATTE NICHT NEHMEN: the drive is not selected, is unknown, or did not pass.
Barcode values with a trailing period are supported. For example,
W4Z1EPVJ. is also checked as W4Z1EPVJ.
The selection view shows only the compact decision indicators. Technical diagnostic messages and unavailable fields are kept out of the scan workflow.
For each disk change:
- Wait until the current self-test is complete.
- Click Slot freigeben.
- Remove the disk.
- Wait until it disappears from
lsblk. - Insert the next disk.
- Wait for the new
/dev/sdXdevice to appear.
Slot freigeben does not physically eject a disk. It only clears the slot and suppresses rediscovery of that still-connected device. Follow the controller or enclosure's safe removal procedure.
The historical inventory is stored in:
data/inventory.db
The JSON inventory endpoint is:
http://127.0.0.1:8000/api/inventory
The database stores the serial number, model, test result, self-test result, SMART health, available SAS diagnostics, test duration, slot, and timestamp.
Run the project startup script from the project directory. It installs and uses the local virtual environment:
cd ~/hdd-triage
rm -rf venv
./run.shIf virtual-environment creation fails, install python3-venv and retry.
Check both permissions and the raw-I/O capability:
id -nG
getcap "$(command -v smartctl)"
ls -l /dev/sda /dev/sg* 2>/dev/nullThe user must be in the disk group and smartctl should have
cap_sys_rawio+ep. Do not hardcode a password and do not run the application
with sudo as a permanent workaround.
Confirm that Linux creates a whole-disk node:
lsblk
ls /dev/sd*If no new /dev/sdX appears, check the HBA, bay, power, cable, backplane, and
controller before investigating the application.
Test the same command manually:
smartctl -t short /dev/sdX
smartctl -a /dev/sdXThe output must include self-test progress and a self-test log. If the device
reports Operation not supported, the disk/controller path cannot provide a
usable short self-test result.
Reload with:
Ctrl+Shift+R
The page uses versioned static asset URLs to avoid stale browser caching.
hdd-triage/
├── run.sh
├── requirements.txt
├── data/
│ └── inventory.db
├── src/
│ ├── main.py
│ ├── monitor.py
│ ├── smart_logic.py
│ ├── database.py
│ └── config.py
├── templates/
│ └── index.html
└── static/
├── js/main.js
└── css/style.css

