Read SCSI Log Pages Safely with sg_logs

You will use sg_logs to discover and read SCSI log pages, one page at a time. It can also limit a large response and save raw data for later decoding. The examples use the installed sg_logs from the Ubuntu sg3-utils package, version 1.46-3ubuntu4. Its executable reports sg3_utils version 1.81 20200110; the local compressed manpage is labelled sg3_utils-1.45, so trust the installed command for its current option summary.

Allow 10 to 15 minutes. You need a shell and access to a SCSI device such as /dev/sg2. Discovery and decoding from a file are ordinary read-only operations. Reading a real device may need elevated privileges, depending on its device-node permissions.

1. Confirm the installed command

Start by checking the binary and version. This does not contact a device:

$ command -v sg_logs
/usr/bin/sg_logs
$ sg_logs --version
Version string: 1.81 20200110

The version output is useful when comparing a report with a different host. Do not copy an option from an online example without checking sg_logs --help on the target machine.

Checkpoint: if command -v finds nothing, install the distribution package through your normal system-management process. Do not create a substitute script with the same name.

2. Inspect known page names without touching hardware

The --enumerate option lists pages known to this utility and ignores the device argument. Restricting it to generic direct-access pages keeps the first result manageable:

$ sg_logs --enumerate --filter=-10
Known log pages in acronym order:
  ac      0xf             Application client
  aptr    0x16            ATA pass-through results
  bop     0x15,0x2        Background operation
  bou     0x1             Buffer over-run/under-run
  bsr     0x15            Background scan results
  ...

The exact list depends on the utility's internal tables and can be longer than this excerpt. Use sg_logs --enumerate for every known page. Use --verbose if you need to see which known pages have no decoding logic and are therefore hex-only.

Enumeration is not a device capability check. It tells you what sg_logs knows how to decode, not what your disk or tape drive actually supports.

3. List pages supported by the device

Set a device placeholder before running a hardware query:

$ DEVICE=/dev/sg2
$ sg_logs --readonly --list "$DEVICE"
# page names and codes printed here are device-specific

--list reads the supported log pages page. Repeat it to include subpages, and repeat it a third time to list every page and subpage reported by the device. An empty or failed result is useful evidence that this device does not expose the page set you expected.

--readonly forces an O_RDONLY open. Without it, the program tries read-write first and falls back to read-only if that fails. Even a successful read-write open can have unwanted close-time effects on some operating systems, so use --readonly for inspection. If the device node is not readable, rerun the same command with the minimum privilege needed, for example sudo sg_logs --readonly --list "$DEVICE". Do not grant broad device access just to make one command convenient.

4. Read one page and choose a bounded response

Once the list gives you a page name or number, request only that page. A temperature query is a useful example:

$ sg_logs --readonly --page=temperature --maxlen=252 "$DEVICE"
# decoded temperature fields printed here are device-specific

Known pages are decoded as text by default. Page names are utility acronyms, page numbers, or page and subpage pairs. The manpage documents decimal numbers unless you use a leading 0x or a trailing h, so --page=0xd and --page=dh identify the temperature page in this version.

With no --maxlen, sg_logs normally fetches four bytes first, learns the response length, then fetches the full page. --maxlen=252 requests one bounded response instead. This is useful for old devices that do not handle the two-stage exchange correctly and for keeping large pages, such as background scan results, under control. Values of 1 and negative values are rejected; the maximum is 65535 bytes.

Checkpoint: if the device reports an illegal request, first run sg_logs --readonly --list "$DEVICE" and select a page it actually reports. A page known to the utility is not automatically present on every device.

5. Make output easier to script

Use --name when you need one decoded name and value per line:

$ sg_logs --readonly --name --page=temperature "$DEVICE"
# name=value entries printed here are device-specific

The names are intended to be easier to parse, but they remain utility output rather than a stable cross-vendor schema. Keep the command version and device model with collected results.

Use --filter=FL to select one parameter code, from 0 through 65535, instead of printing every parameter on a page:

$ sg_logs --readonly --page=0x2f --filter=0 "$DEVICE"
# one decoded parameter is printed here when the device supports it

If you need bytes rather than a decoded interpretation, add --hex. One use prints hexadecimal, two uses add an ASCII column, and three uses remove addresses and trailing ASCII so the result is suitable for a file. Treat raw or hex capture as evidence, not as something to edit and send back to a device.

6. Decode a saved response without a device

--in=FN can decode a file containing an ASCII-hex or binary log-page response. A hyphen reads standard input. This is useful for analysis on a separate host:

$ sg_logs --in=/tmp/log-page.hex --page=0xd
# decoded fields printed here are capture-specific
$ cat /tmp/log-page.hex | sg_logs --in=- --page=0xd

For ASCII input, use one or two hexadecimal digits per byte, separated by whitespace or commas. Text from a hash mark to the end of a line is ignored. Add --raw when the input file contains binary rather than ASCII hex. In file-decoding mode the device argument is ignored, and the page and subpage codes are taken from the response. Use --pdt=DT only when the peripheral device type is not available and decoding needs an explicit type.

Checkpoint: preserve the original capture. If you need to remove sensitive identifiers before sharing it, make a copy under /tmp and document exactly what changed. Never pass a modified or untrusted capture to --select.

7. Keep LOG SELECT behind a deliberate change review

The normal invocation sends SCSI LOG SENSE and reads data. --select switches to LOG SELECT, which sends data or control requests to the device. --reset implies --select and can clear some error-counter log pages. --sp asks the device to save parameters to non-volatile storage. These options can change device state and may need read-write access.

Do not add them to a diagnostic command just because an example includes them. Before using LOG SELECT, confirm the vendor's behaviour, capture the current page, record the exact command, and arrange an operational window if the device or workload could be affected. There is no universal undo for a vendor-specific log change. Recovery is device-specific: use the vendor's documented restore procedure, or restore a previously captured parameter list only after verifying its format and meaning.

Done means