You will use sg_map26 to translate between a SCSI generic node such as /dev/sg0 and its ordinary block device such as /dev/sda. It also resolves the related sysfs paths. The examples are read-only: this command does not read or write disk contents, change udev names, or alter kernel state.
Allow about ten minutes. You need a Linux shell and the sg3-utils package. This guide was checked with package version 1.46-3ubuntu4; the installed program reports sg_map26: version: 1.17 20200501. The local manual page identifies its documented utility release as sg3_utils-1.35, so use the installed help and output as the final authority when another machine differs.
Start by checking which executable your shell will run and asking it for its version:
$ command -v sg_map26
/usr/bin/sg_map26
$ sg_map26 --version
sg_map26: version: 1.17 20200501No elevated privileges are normally required for mapping. If a device node is unreadable in your environment, keep the same command and investigate the device permissions through your normal system policy. Do not grant broad access merely to make a name lookup convenient.
Checkpoint: command -v should resolve to the package-managed binary you intend to use, and --version should complete successfully.
With the default result mode, give sg_map26 a device special file and it searches for the corresponding mapped special file. On this host, /dev/sg0 maps to /dev/sda:
$ sg_map26 /dev/sg0
/dev/sdaThe result is a relationship, not a guarantee that every SCSI device has a block or character node of the kind you expect. Enclosures and some SES devices can be available only through an sg node. A missing mapping can also mean that the relevant driver or sysfs information is not present.
To map in the other direction, pass the primary device:
$ sg_map26 /dev/sda
/dev/sg0The command prints one relationship at a time. If you need an inventory of all devices and their names, use a discovery tool such as lsscsi rather than looping over guessed device names.
The --result option makes the distinction between mapped and matching files explicit. The default is --result=0. These modes are useful when a script needs a specific kind of path; the --result modes are:
| Mode | Returns | Example with /dev/sda |
|---|---|---|
0 | Mapped device special file | /dev/sg0 |
1 | Mapped sysfs path | /sys/.../scsi_generic/sg0 |
2 | Matching device special file | /dev/sda |
3 | Matching sysfs path | /sys/block/sda |
For example, use result 3 when a later operation needs the block device's sysfs directory rather than another device node:
$ sg_map26 --result=3 /dev/sda
/sys/block/sdaUse result 1 when starting with the block device but needing the sg interface's sysfs location. The exact path can include the host controller and target hierarchy, so scripts should consume the returned path rather than assume a fixed directory depth:
$ sg_map26 --result=1 /dev/sda
/sys/devices/.../scsi_generic/sg0The shortened path above is illustrative. Your system will print its complete path.
Checkpoint: choose 0 or 1 for the other, mapped representation; choose 2 or 3 for the same device represented as a matching special file or sysfs path.
The input may be a sysfs device directory, or its dev file. For a block device, both forms identify the same device:
$ sg_map26 /sys/block/sda
/dev/sg0
$ sg_map26 /sys/block/sda/dev
/dev/sg0If automatic detection is unsuitable for a wrapper or validation script, declare the input variety with --given_is=1. Value 0 means a block or character special file, including a symlink; value 1 means a sysfs dev file or its parent directory.
$ sg_map26 --given_is=1 --result=0 /sys/block/sda
/dev/sg0The option is a declaration, not a conversion. If it disagrees with the supplied path, the command reports an error. Usually leaving it out is clearer because the program first checks for a special file and otherwise treats the input as sysfs.
For result 0 or 2, --symlink also searches the relevant device directory for symlinks to the matching special file. This matters for names such as /dev/disk/by-id/... or a local optical-drive alias, but it can produce several lines:
$ sg_map26 --result=2 --symlink /dev/sda
/dev/sdaOn a machine with aliases, each matching symlink may be printed. Do not treat the first line as a stable canonical name unless your own naming policy says it is. The option is ignored for sysfs results because sysfs paths are not searched as device-node symlinks.
--dev_dir=DIR changes where result 0 or 2 searches for the resulting special files. It is useful when device nodes or links are deliberately kept in a controlled directory. It does not relocate the device and does not change udev rules:
$ sg_map26 --dev_dir=/dev --result=0 /dev/sda
/dev/sg0Do not point --dev_dir at an arbitrary directory and infer that a missing result proves the device is absent. It may simply be absent from that search directory.
First check the input spelling and the relevant node or sysfs path:
$ test -e /dev/sg0 && echo 'sg node exists'
sg node exists
$ test -e /sys/block/sda && echo 'sysfs block path exists'
sysfs block path exists
$ sg_map26 --verbose /dev/sg0Verbose mode adds diagnostic output and is useful when the relationship cannot be found. A non-zero exit status means the lookup failed; it is not a request to repair the device. Check that sysfs is mounted, that the input is the expected block or character node, and that the relevant kernel driver has created the corresponding entries.
If a device has disappeared, stop and identify the correct node again before using any follow-up storage command. Device names can be reused after hotplug events. Never substitute /dev/sda for an unresolved result in a destructive command, and do not use sudo as a generic response to a failed mapping. This utility itself does not require a write operation or a service restart.
sg_map26 --version confirmed the installed utility.dev file.--symlink and --dev_dir are used only when their search behaviour is wanted.