Inspect SCSI Referral Segments Safely with sg_referrals

sg_referrals sends a SCSI REPORT REFERRALS command and decodes what the device hands back about the segments it points you towards. It is a read: the tool queries referrals, it does not configure them, so there is nothing here that changes the storage.

Allow about 10 minutes for a single device once you know its SCSI generic path. The examples use /dev/sgX as an obvious placeholder. Replace it with the actual SCSI generic device, and do not guess: an incorrect path can query a different disk or enclosure entirely.

Before you start

  1. Install the sg3-utils package and confirm that the command is available.
  2. Identify the SCSI generic device associated with the target hardware.
  3. Have permission to open that device. Use an ordinary shell first, and reach for sudo only if the device permissions require it.

This guide was checked with Ubuntu package sg3-utils 1.46-3ubuntu4. The installed program reports sg_referrals version 1.13 20180628. Later releases can add or alter diagnostic details, so treat the device response and your local help output as authoritative over this page.

Checkpoint: confirm the local interface

Check the version before you go anywhere near hardware:

sg_referrals --version

On the checked installation, the relevant output is:

version: 1.13 20180628

Now read the usage text. This catches a misspelt option and confirms this installation accepts the long options used below:

sg_referrals --help

The options that matter are --lba, --maxlen, --one-segment, --hex, --raw, --readonly and --verbose. Options that take values need them written out, for example --lba=0 and --maxlen=256.

Step 1: make a conservative query

Start at LBA zero, ask for the default-sized response, and explicitly open the device read-only:

sg_referrals --readonly --lba=0 --maxlen=256 /dev/sgX

The command sends REPORT REFERRALS and decodes the response into user-data-segment referral descriptors. The exact lines depend on the device. One that does not support referrals may return a SCSI sense error instead of decoded descriptors: that is a device capability result, not evidence the option was ignored.

The manpage documents 256 bytes as the default allocation length when --maxlen is omitted. Supplying it explicitly makes a captured command easier to review later and avoids relying on memory about that default.

Step 2: narrow the response to one segment

If the full response is noisy, ask about a particular segment by supplying its starting LBA and adding --one-segment:

sg_referrals --readonly --lba=1048576 --one-segment --maxlen=256 /dev/sgX

--lba selects the first user-data segment whose referral parameter data should be reported. --one-segment narrows the result to the user-data segment specified by that LBA. Keep the LBA inside the device's addressing range: the tool cannot turn an invalid address into a meaningful referral.

Increase the allocation length only when the response is truncated or the device documentation calls for it:

sg_referrals --readonly --lba=1048576 --maxlen=4096 /dev/sgX

--maxlen is the response length in bytes placed in the command's allocation-length field. It controls how much data the device may return, not how many referrals exist.

Step 3: capture a machine-reviewable form

Use hexadecimal output when you need a stable record for comparison or vendor support:

sg_referrals --readonly --hex --maxlen=4096 /dev/sgX > referrals.hex

The output file is ordinary text containing the response in ASCII hexadecimal. Check that it is non-empty and keep the command line beside it:

test -s referrals.hex && wc -c referrals.hex

This creates a local capture, not a device change. Remove it once you no longer need it with rm -- referrals.hex. Do not use --raw in a terminal: it writes binary response data straight to standard output. Redirect it to a deliberately named file instead:

sg_referrals --readonly --raw --maxlen=4096 /dev/sgX > referrals.bin

Common traps and recovery

The manpage says the default device open mode is read-write, even though REPORT REFERRALS is a reporting command. Always include --readonly for an inspection query. It stops this utility requesting a read-write file descriptor where the operating system permits that distinction. The option does not override a device's own command permissions.

Do not confuse --hex with --raw: hexadecimal suits a terminal and a text capture, while raw output is binary. If you accidentally write binary data to the screen, stop the command with Ctrl-C and run reset if the terminal display is disturbed. A partially written capture can simply be discarded and recreated.

If the command reports permission denied, repeat the same read-only command with elevated privileges:

sudo sg_referrals --readonly --hex --maxlen=4096 /dev/sgX

If it reports an unsupported command, a check condition, or no referral descriptors, record the device identity, the exact command, the exit status and any sense information. The utility exits with status zero on success and non-zero otherwise. This is a query, so it changes no persistent configuration, and there is no device-side undo step to worry about.

Done means