Run SCSI Diagnostics Safely with sg_senddiag

sg_senddiag finds the diagnostic pages a SCSI device supports and starts the right self-test without guessing at its flags. It also reports how long an extended self-test should take before you commit to one. Allow 10 minutes for a read-only inspection. A real self-test may take seconds, minutes, or, for an extended foreground test, up to two hours or longer on some hardware.

Before you touch a device

This guide targets the sg3-utils package installed here, version 1.46-3ubuntu4. The executable reports utility version 0.63 20180628, while the installed manual page identifies the sg3_utils documentation as version 1.43. The command accepts a SCSI generic device such as /dev/sg2; modern Linux also permits suitable SCSI block devices.

You need the package installed and permission to issue SCSI commands. Reading information may work as an ordinary user if the device permissions allow it. Starting a test or sending a diagnostic page normally requires sudo. Identify the exact device first. Do not substitute a disk because its number looks similar.

ls -l /dev/sg* /dev/sd* 2>/dev/null
lsblk -o NAME,TYPE,SIZE,MODEL,SERIAL,MOUNTPOINTS

Warning: sg_senddiag sends commands to hardware. A foreground self-test can delay other SCSI commands. For a disk, unmount its file systems before a foreground test. A default self-test with the Device Offline or Unit Offline bit can also affect other work on the target or logical unit. Do not test a production path until its owner has approved the interruption.

Checkpoint 1: confirm the utility

Check the installed binary and its version. This does not contact a device.

$ sg_senddiag --version
Version string: 0.63 20180628

If the command is missing, install the distribution package through your normal change process. Do not work around a missing binary by copying an unverified executable into the system.

Checkpoint 2: see the page names

With no device, --list prints page names known to this version of the utility. It does not ask hardware what it supports.

$ sg_senddiag --list
Page_Code  Description
 0x00      Supported diagnostic pages
 0x01      Configuration (SES)
 0x02      Enclosure status/control (SES)
 0x0a      Additional (device) element status (SES-2)
 0x3f      Protocol specific (SAS transport)

The complete output includes more entries. The page code is useful when you later use --page, but a page being listed here does not prove that a particular enclosure or disk implements it.

Checkpoint 3: ask the device which pages it supports

Pass the exact device to --list. The utility sets the Page Format bit, sends SEND DIAGNOSTIC, then fetches the response with RECEIVE DIAGNOSTIC RESULTS.

sudo sg_senddiag --list /dev/sg2

Success prints supported page names and codes for that device. A failure usually means the path is wrong, permissions are insufficient, the device rejected the command, or a transport layer returned a SCSI error. Retry with one --verbose only after confirming the device path:

sudo sg_senddiag --verbose --list /dev/sg2

For a supported diagnostic page other than page zero, request its raw response without issuing SEND DIAGNOSTIC:

sudo sg_senddiag --page=2 --hex /dev/sg2

--page=0 decodes the response as the Supported Diagnostic Pages page. Other page values are output in hexadecimal. Use this for inspection, not for changing enclosure state.

Checkpoint 4: choose the self-test

The safest first test is usually a background short self-test. Code 1 starts it and returns immediately; the device records results in its self-test results log page.

sudo sg_senddiag --selftest=1 /dev/sg2

An extended background test uses code 2. A foreground short test uses 5, and a foreground extended test uses 6. Foreground tests wait for completion. The manual says short tests should finish in two minutes or less, but extended duration is vendor-specific.

Ask the device for its expected extended-test duration before choosing code 2 or 6:

sudo sg_senddiag --extdur /dev/sg2

The value comes from mode page 0x0a and is printed in seconds, with minutes in parentheses. It is an estimate supplied by the device, not a guarantee.

Foreground tests need a service window

A foreground extended test can keep later SCSI commands queued and cause them to time out. The utility's foreground timeout defaults to 7200 seconds. Values below that default are ignored, so this does not shorten a foreground test:

sudo sg_senddiag --timeout=7200 --selftest=6 /dev/sg2

For a disk, unmount first and check that nothing still has a file open. When the test has finished, remount the file systems using your normal mount configuration. If you started a background test instead, code 4 requests its abortion:

sudo sg_senddiag --selftest=4 /dev/sg2

Do not combine --selftest=ST with --test. The latter selects the default Self Test bit rather than one of the numbered codes. --doff and --uoff are meaningful with --test, but they can delay other operations and should be treated as a deliberate service-impacting choice.

Sending a diagnostic page

--raw sends bytes as a diagnostic page. The first byte should be the diagnostic page code, and --pf will normally be needed. This is a write-like hardware operation: do not copy an example page into a different enclosure or disk.

sudo sg_senddiag --pf --raw=01,00,00,00 /dev/sg2

The four bytes above are only a syntax example, not a generally valid enclosure command. Use bytes from the device vendor or a trusted standards-based procedure. Never select a self-test alongside --raw.

For a reviewed byte sequence in a file, --raw=- reads comma-, space-, tab-, or newline-separated hexadecimal bytes from standard input. Lines may contain comments beginning with #.

sudo sg_senddiag --pf --raw=- /dev/sg2 < reviewed-page.txt

Done means