Read a SATA General Purpose Log Safely with sg_sat_read_gplog

sg_sat_read_gplog pulls a raw ATA General Purpose log through the SAT translation layer, straight from the drive, with no decoding done for you. It saves the hexadecimal response and helps you tell a bad device path from an unsupported transport. The bytes come back normally grouped as ATA-style little-endian 16-bit words.

• What you need: the sg3-utils package, a SATA disk or SSD that exposes SAT through the chosen SCSI device, and permission to open that device.
• What it will do: send a real ATA command to real hardware, though it is not a filesystem repair operation. Confirm the target first, and use a maintenance window if the disk belongs to a busy service. Allow about fifteen minutes for a first inspection.
• Versions used here: Ubuntu package sg3-utils 1.46-3ubuntu4; the installed binary reports version: 1.20 20180628, while the local manpage identifies its reference text as sg3_utils-1.41. Trust the installed command's help if those documents disagree.

1. Confirm the installed command

Start with read-only inspection of the binary and its interface. These commands do not touch a disk:

$ command -v sg_sat_read_gplog
/usr/bin/sg_sat_read_gplog
$ sg_sat_read_gplog --version
version: 1.20 20180628
$ dpkg-query -W -f='${Package} ${Version}\n' sg3-utils
sg3-utils 1.46-3ubuntu4

The version discrepancy is useful evidence, not a reason to guess. It can happen when the package metadata and the utility's own version string come from different release conventions. Record both when reporting a problem.

2. Identify the SAT device

The final argument is a SCSI device path, not a mount point and not automatically a partition. Common examples are /dev/sg2 or another generic SCSI device node. The number is host-specific, so do not copy it from this guide. Map the disk to its SCSI generic device with the tools already used on your host, then verify the identity before reading it.

For example, list the available generic SCSI nodes and inspect the one you intend to use:

$ ls -l /dev/sg*
$ sg_inq /dev/sgX
$ readlink -f /dev/sgX

Replace sgX with an actual node. sg_inq is a separate sg3-utils utility, used here only to identify the path. If the node does not describe the SATA device you expect, stop: a successful command against the wrong disk is still the wrong result.

Device access commonly needs elevated privileges. Try the identification command as your ordinary account first. If the operating system denies access, use sudo for that one command or arrange the appropriate group permission under your system policy. Do not make a broad permission change just to avoid one access error.

3. Read the log directory first

With the target confirmed, read log address zero and page zero. The manpage describes log address zero as the directory of available logs. The installed command defaults to both values, but writing them explicitly makes a script and its audit trail easier to understand:

$ sudo sg_sat_read_gplog --readonly --log=0 --page=0 /dev/sgX

The command normally exits silently apart from the hexadecimal response when it succeeds. Its exit status is the first check:

$ printf 'exit status: %s\n' "$?"
exit status: 0

A block of hexadecimal is not decoded meaning: this utility currently does not interpret individual log pages. Keep the raw response, the exact command line, and the device identity together. A page directory tells you which addresses exist, but interpreting a particular page needs the relevant ATA specification or the disk vendor's documentation.

4. Capture a known log and preserve the raw bytes

Once you know the log address and page number you need, pass them with --log and --page. For a safe capture, redirect standard output to a new file rather than overwriting an existing record:

$ sudo sg_sat_read_gplog --readonly --log=LOG_ADDRESS --page=PAGE_NUMBER /dev/sgX > sat-log.txt
$ status=$?
$ printf 'exit status: %s\n' "$status"
exit status: 0
$ test -s sat-log.txt && echo 'capture is non-empty'
capture is non-empty

Replace LOG_ADDRESS and PAGE_NUMBER with decimal values you have verified. The documented ranges are 0 through 255 for the log address and 0 through 65535 for the page number. The command reads --count 512-byte blocks; the installed help reports a default count of one. Set it explicitly when the page format needs more than one block:

$ sudo sg_sat_read_gplog --readonly --count=2 --log=LOG_ADDRESS --page=PAGE_NUMBER /dev/sgX > sat-log-2-blocks.txt

Shell redirection creates or truncates its destination before the utility runs. Choose a fresh filename or use a temporary name and rename it only after a successful exit:

$ sudo sg_sat_read_gplog --readonly --log=LOG_ADDRESS --page=PAGE_NUMBER /dev/sgX > sat-log.txt.new
$ status=$?
$ if [ "$status" -eq 0 ] && [ -s sat-log.txt.new ]; then mv sat-log.txt.new sat-log.txt; else rm -f sat-log.txt.new; fi
$ exit "$status"

5. Select the output form deliberately

By default, the response shows as hexadecimal grouped into 16-bit words using ATA little-endian conventions. That is convenient for reading ATA documentation, but it is not the byte order used to write the SCSI command itself. The distinction matters when comparing output with a SCSI trace.

• One --hex gives hexadecimal bytes.
• Two gives the default-style word grouping.
• Three gives word-grouped output without offsets or trailing ASCII, meant to be accepted by hdparm --Istdin.

$ sudo sg_sat_read_gplog --readonly --hex --log=0 --page=0 /dev/sgX
$ sudo sg_sat_read_gplog --readonly -HHH --log=0 --page=0 /dev/sgX

Use the form that matches the next tool or the evidence format you are documenting. Watch for accidentally calling --hex repeatedly in a script: -H, -HH and -HHH are different output modes.

6. Diagnose transport and device failures

A non-zero exit status means the operation was not successful. Add --verbose to expose more detail, while keeping the same device and log values:

$ sudo sg_sat_read_gplog --readonly --verbose --log=0 --page=0 /dev/sgX
$ printf 'exit status: %s\n' "$?"

First re-check the path with sg_inq. Then check whether the enclosure, HBA or operating-system driver actually provides SAT: this utility sends ATA READ LOG EXT through an ATA PASS-THROUGH SCSI command, and it cannot make a non-SAT path understand that command. Some transports also cannot carry the default 16-byte CDB. If the transport is limited to 12-byte commands, try the documented alternative:

$ sudo sg_sat_read_gplog --readonly --len=12 --log=0 --page=0 /dev/sgX

Use that option because the transport requires it, not as a general retry. If a device needs the DMA form to return valid data, use --dma:

$ sudo sg_sat_read_gplog --readonly --dma --log=0 --page=0 /dev/sgX

The ordinary command uses ATA READ LOG EXT. The DMA variant is a compatibility choice for devices that require it, not a guarantee that every bridge supports it.

7. Keep the safety boundaries clear

--readonly opens the device with the Unix read-only flag, a sensible default for an inspection workflow because the program otherwise opens the device read-write. The utility still sends a command to the drive, and read-only opening does not fix a broken bridge or prevent every device-side effect. Do not treat this command as evidence that a disk is healthy under load.

--ck_cond requests an ATA Result descriptor in the SCSI sense buffer whether the ATA command succeeds or fails. It is useful when you need lower-level result information, but it makes output and diagnosis more transport-dependent:

$ sudo sg_sat_read_gplog --readonly --ck_cond --verbose --log=0 --page=0 /dev/sgX

Use it when collecting evidence for a SAT problem, not as a routine spell to make a failed read work. Older USB mass-storage paths can truncate sense data, producing misleading results. Capture the command, utility version and bridge details before escalating.