hddscan guide

hddscan finds sectors on a rotating disk that return data too slowly or not at all. You can drive it from an interactive form or entirely from the command line; both do the same things with the same defaults, so a report from one can be compared with a report from the other.

Install

git clone https://github.com/IntelliStream-DataHub/hddscan
cd hddscan
make                # dynamic build; needs glibc 2.38 or newer where it runs
make static         # no glibc floor: one file for a rescue system
sudo make install   # /usr/local/sbin/hddscan, the man page, and a dm-badblocks link

Or take a static binary from Releases, built and tested on x86_64 and aarch64. It is one file with no glibc version floor, so it also runs from a rescue system:

tar xzf hddscan-1.0-linux-x86_64.tar.gz
sudo install hddscan-1.0-linux-x86_64/hddscan /usr/local/sbin/

It needs nothing beyond libc. It uses these tools when they are installed and does without them otherwise; hddscan --check-deps says which are missing and prints the dnf or apt line that installs them.

Reading a drive needs root. Everything else (reports, run records, the maps on image files) does not.

Concepts

Profiles

The first question is what you are about to do with the drive, because that decides how it should be tested. A profile sets the mode and the passes that go with it; any flag you give explicitly overrides it.

Verdicts and sectors

Every sector that does not simply come back is one of three things:

Each drive then gets a verdict, which is also the exit status: HEALTHY (0), SUSPECT (1) or FAILING (2); 130 means the scan was interrupted. Every report also carries a Coverage line. A verdict of HEALTHY over 3% of a drive is not a healthy drive, and the report will not let that difference get lost.

The terminal UI

Run sudo hddscan on a terminal with no device named and it opens the form. If work is already running on the machine, it shows that first.

The form

Drives come first. Space picks one, a picks every free hard disk, and g picks every free disk on the same controller as the one under the cursor, which is one keystroke per shelf. Drives that are mounted, in use or already in a run are shown but cannot be picked.

The settings below are in three groups, because they answer different questions:

• How to test: profile, mode, chunk size, scan order. Changing the profile resets the rest to what that profile means.
• Drive settings: look-ahead, caches, auto-reallocation, recovery limit, background scan. These change the drive itself and are put back when the run ends, unless Save to drive or the profile says otherwise.
• Low level format: used only when Mode is format.

Press s to start. Anything that writes, saves a setting or erases the drive asks again, and needs y.

The dashboard

Rate, ETA and latency are measured over the last 30 seconds, so a drive that has just walked into a bad patch shows it now rather than hours later. Latency is in milliseconds, yellow over 50 and red over 100; a drive that has spent the whole window drilling into one slow chunk shows its single-sector reads instead, marked sector. Bad and weak counts turn red and yellow once they are not zero. Drives needing attention sort to the top. A shelf is more drives than a screen holds, so the table pages with < >, and g swaps it for an overview with one line per drive:

The dashboard is only a viewer. q quits and leaves the run going; x then y stops it, and so do Ctrl-C or Esc, immediately. A stopped drive still writes its report, with a Coverage line saying how far it got.

Runs

A scan or a format is a run, owned by a supervisor process of its own rather than by the terminal that started it. Close the window or lose the ssh session and it carries on; start hddscan again and this list is the first thing you see. Enter opens a run, x stops one, f forgets a finished one. A drive already in a live run is refused by any other, since two runs on one spindle would time each other's seeks.

The summary

A scan can run for days, so its result does not scroll away when the last drive finishes: the summary holds every verdict until you press a key. n starts another test and q quits. For a drive whose scan covered the whole drive and found damage, h hides it behind a device-mapper device (see below). ↑ ↓ choose the drive, marked with >, and y confirms:

Keys

The command line

Name a device and hddscan runs without the form. Devices can be given as /dev/sdb, sdb, or a regular file to use as an image.

Common tasks

# a drive with data on it: read-only, never writes
sudo hddscan --profile inservice /dev/sdb

# a drive going into service: writes every sector, verifies, re-reads
sudo hddscan --confirm sdb /dev/sdb

# quick triage of every free disk on the machine
sudo hddscan --profile survey --all

# weeks later, on a drive an earlier predeploy run wrote
sudo hddscan --profile decay /dev/sdb

# give a drive its best chance: write, rewrite what is still slow,
# force a reallocation of anything unreadable, then re-read the lot
sudo hddscan --repair --confirm sdb --recovery-time 300 /dev/sdb

# a shelf, in the background
sudo hddscan --confirm sdb --detach /dev/sd{b..z}

--confirm takes the device name as given, or the drive's serial. A full pass over a 14 TB drive takes about a day, and --repair roughly twice that. On a drive that is already sick, two flags matter more than they look: --recovery-time 300 stops the drive grinding a second on each bad sector, and --retries 3 stops the tool grinding twenty attempts on each.

Watching runs

sudo hddscan --status                  # every run on this machine
sudo hddscan --status sdq              # the run a given drive is in
sudo hddscan --status-json             # the same, for a script
sudo hddscan --attach 20260912-080512  # open the dashboard on one
sudo hddscan --stop 20260912-080512    # stop it; partial reports are still written
sudo hddscan --forget 20260912-080512  # drop a finished run's records

Records live in /var/lib/hddscan as root and ~/.local/state/hddscan otherwise, as plain key-and-value text.

Reading a report

Every drive gets a text report: the drive, the profile and mode, the Coverage line, latency percentiles and distributions, a surface map, the counters, and every suspect sector with how many tries it took. It ends with the verdict and what to do next.

A report never contradicts itself. Two numbers describing the same thing are computed the same way, and blocks the scan could not test (for example on a drive formatted with protection information and never written since) are listed as not covered rather than counted as either good or bad.

Hiding bad blocks

A drive with a few hundred bad sectors can still be a good backup target, as long as we make the bad/weak sectors inaccessible. There are two ways to arrange that:

• ext2/3/4 can take a list of bad blocks when the filesystem is made. The report prints the commands, with the numbers filled in.
• Any filesystem, ZFS included: hddscan writes a map of the damage onto the drive and loads it with device-mapper, so the filesystem sees a slightly smaller device with none of the known damage in it. No kernel module.

sudo hddscan --profile inservice /dev/sdc          # a whole-drive scan
sudo hddscan --hide-bad --confirm sdc /dev/sdc     # map it: /dev/mapper/bb-<serial>
sudo zpool create -o ashift=12 -O compression=zstd backup /dev/mapper/bb-<serial>

The damage is only ever taken from a scan that covered the whole drive and finished. A list from a sampled or interrupted scan would hide the damage it happened to look at and leave the rest in the middle of the new device. The drive is found by serial, since sdc may be sdd after a reboot.

The map keeps the drive in its original order and steps over the damage known when it was made. Damage found later is moved to the nearest of the spare extents held back for it, 0.1% of the drive spread across the platter, so a moved extent costs a short seek. Two copies of the map, with checksums, live at the start and end of the drive. hddscan dm manages it directly, and is also installed as dm-badblocks:

sudo hddscan dm status /dev/sdc
sudo hddscan dm remap /dev/sdc --bad new.bb --block-size 512    # sectors from the kernel log
sudo hddscan dm activate-all                                    # what runs at boot

contrib/dm-badblocks.service activates every mapped drive at boot, before local filesystems and ZFS imports. On a single disk, ZFS can repair a bad block only if it has a second copy, so set copies=2 on the datasets that matter.

Drive settings

hddscan can change how a drive behaves, through sdparm or hdparm. Settings a scan needs are put back when the run ends, on Ctrl-C and on error; settings meant to last are saved on the drive and announced with the command that undoes each one.

• For the scan: the drive's look-ahead is turned off, so a prefetch cannot mask a marginal sector, and so is its read cache.
• Predeploy and repair also turn the write cache off for the run, so the write pass times the platter rather than the drive's memory.
• Predeploy and repair save --fix-config (auto-reallocation on for reads and writes, read cache on) and the drive's own background scan, weekly. --no-fix-config and --bms keep opt out. None of it applies if you override the mode.
• --persist saves the settings you named explicitly, never a default. --apply-settings applies them without a scan.

Low level format

# see exactly what it would run
sudo hddscan --format --format-pi none --confirm sdb --dry-run /dev/sdb

# strip protection information, keep the sector size
sudo hddscan --format --format-pi none --confirm sdb /dev/sdb

# change the sector size too, and ask for a fast format
sudo hddscan --format --format-blocksize 4096 --format-pi none \
             --format-fast --confirm sdb /dev/sdb

--format runs a SCSI FORMAT UNIT on every selected drive in parallel, as a run like any other. It erases the drive and cannot be called back, so it prints the exact sg_format command first. --format-pi defaults to keep, because sg_format itself defaults to stripping protection information. Removing it can recover real capacity: on one 14 TB Seagate it gave back 284 GB.

Files it writes

Option reference

Generated from hddscan --help. man 8 hddscan has the same options at more length.

Usage: hddscan [options] [device ...]
       hddscan --list
       hddscan --status [RUN|DRIVE]

Run on a terminal with no device named, hddscan opens the interactive picker; --no-tui turns that off. Devices may be given as /dev/sdb, sdb, or a regular file to use as an image. With no device and --all, every unmounted rotational disk is scanned.

Exit status: 0 healthy, 1 suspect, 2 failing or usage error, 130 interrupted.